راهنمای اتصال به سرویس
استخراج تصویر با multipart/form-data و کنترل مستقل فیلدها با application/json انجام می‌شود. مسیرهای /api/ و /openapi.json به هدر X-API-Key نیاز دارند. فایل OpenAPI با کلید معتبر قابل دریافت است. این صفحه و کنسول وب بدون اینترنت و CDN کار می‌کنند.
مسیرها
| مسیر | کاربرد |
|---|---|
| POST /api/v1/extract | فیلدهای هویتی، شواهد و متن OCR |
| POST /api/v1/document | خواندن متن کامل ۱ تا ۶ تصویر از یک سند؛ متن TXT و JSON به‌ترتیب صفحات |
| GET /api/v1/document-kinds | انواع سند و محدودیت‌های شناسایی مبتنی بر عنوان |
| POST /api/v1/ocr | فقط متن و مختصات خطوط |
| POST /api/v1/validate | کنترل متن فیلدها بدون تصویر یا فراخوانی OCR |
| GET /api/v1/profiles | سیاست‌های کنترل فیلد، نه الگوهای تضمین‌شده تشخیص مدرک |
| GET /api/v1/capabilities | قابلیت‌ها، زبان‌ها و آمادگی موتور |
| GET /openapi.json | قرارداد ماشین‌خوان OpenAPI |
| GET /health/ready | آمادگی موتور و فایل‌های زبان |
| GET /health/live | زنده‌بودن فرایند |
استخراج سند چندصفحه‌ای
تصاویر را با کلید تکراری pages به ترتیب ارسال کنید؛ کلید مدرک document_kind می‌تواند iran_shenasnameh یا afghanistan_tazkira_paper باشد. متن کامل در full_text برگردانده می‌شود. فیلدهای صاحب مدرک تنها از صفحه اول استخراج می‌شوند، زیرا نام‌ها در صفحات ثبت وقایع ممکن است متعلق به افراد دیگر باشند. موضوعات احتمالی وقایع در topic_evidence فقط برچسبِ همراه شاهد متنی هستند.
curl -X POST http://127.0.0.1:4000/api/v1/document \ -H "X-API-Key: YOUR_API_KEY" \ -F "pages=@p1.jpg" -F "pages=@p2.jpg" \ -F "languages=fa,ps" -F "document_kind=iran_shenasnameh"
نمونه درخواست
curl -X POST http://127.0.0.1:4000/api/v1/extract \ -H "X-API-Key: YOUR_API_KEY" \ -F "front=@/path/to/front.jpg" \ -F "back=@/path/to/back.jpg" \ -F "languages=fa,en" \ -F "document_type=national_id" \ -F "calendar=jalali" \ -F "engine_mode=tesseract" \ -F "rotation=0" \ -F "psm=6" \ -F "include_raw=true"
تصویر پشت اختیاری است. هدر Content-Type را در درخواست curl دستی تنظیم نکنید تا boundary به‌درستی ساخته شود. در PowerShell از curl.exe استفاده کنید.
پارامترهای استخراج
| پارامتر | مقادیر |
|---|---|
| front | تصویر اجباری JPEG، PNG یا WEBP |
| back | پشت همان مدرک، اختیاری |
| languages | auto یا ترکیبی از fa,en,tr,ar,ps. حالت auto هر پنج زبان را فعال می‌کند؛ تشخیص زبان مستقل نیست. |
| document_type | auto / national_id / passport / driving_license / residence_permit / other |
| engine_mode | tesseract یا hybrid. حالت hybrid به سرویس مدل بینایی پیکربندی‌شده نیاز دارد. |
| calendar | unknown / gregorian / jalali / hijri. پیش‌فرض unknown؛ تقویم از زبان حدس زده نمی‌شود. |
| document_profile | generic / ir_national_id / tr_identity_card / passport_td3؛ انتخاب صریح سیاست کنترل، بدون حدس کشور |
| date_order | auto / ymd / dmy / mdy؛ حالت auto تاریخ عددی با روز و ماه مبهم را حدس نمی‌زند. |
| date_overrides | رشته JSON شامل تنظیم calendar و/یا order برای date_of_birth، issue_date، expiry_date؛ نمونه پایین |
| rotation | 0 / 90 / 180 / 270 / auto؛ ساعت‌گرد، پس از اصلاح EXIF، برای هر دو تصویر |
| psm | 6: بلوک متن، 11: متن پراکنده، 3: چیدمان خودکار |
| include_raw | true / false؛ مقدار false متن OCR و رشته خام MRZ را حذف می‌کند، نه خود فیلدهای هویتی. |
تنظیم مستقل تاریخ‌های یک مدرک
-F 'calendar=gregorian' \
-F 'date_order=ymd' \
-F 'date_overrides={"date_of_birth":{"calendar":"jalali","order":"ymd"}}'تنظیم هر فیلد بر تنظیم عمومی اولویت دارد. تاریخ دارای نام ماه یا نشان تقویم صریح می‌تواند بدون حدس زبان تفسیر شود. متن اصلی در value و تاریخ در تقویم مبدا در normalized باقی می‌ماند. تبدیل شمسی/میلادی در date_info جداگانه درج می‌شود. محدوده شمسی ۱۲۰۰ تا ۱۶۰۰ است. قمری فقط کنترل مقدماتی ماه و روز دارد و تبدیل نمی‌شود. سده تاریخ MRZ حدس زده نمی‌شود.
کنترل بدون تصویر
POST /api/v1/validate
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
"document_profile": "ir_national_id",
"calendar": "jalali",
"fields": {
"given_names": "نمونه",
"surname": "آزمایشی",
"national_id": "0000000000",
"date_of_birth": "۱۳۹۹/۱۲/۳۰"
}
}این ورودی عمداً شماره نامعتبر دارد؛ پاسخ HTTP 200 به معنی انجام کنترل است، نه صحت اطلاعات. نتیجه هر قاعده در validation.checks قرار دارد. شماره‌ها باید رشته باشند؛ عدد JSON پذیرفته نمی‌شود و صفر حذف‌شده بازسازی نمی‌گردد. سقف درخواست این مسیر ۶۴ KiB است. API باید در حال اجرا باشد، اما این مسیر به آماده‌بودن OCR نیاز ندارد.
معنای نتیجه
هر فیلد شامل value، normalized، source، evidence_line_ids، ocr_confidence، status و alternatives است. observations تمام خوانش‌های ثبت‌شده تا سقف ۳۲ مورد برای هر فیلد را نگه می‌دارد. date_info شامل اعتبار تاریخ و تبدیل‌های صریح است. validation شامل نتیجه قواعد محلی، فیلدهای ناقص و تعارض‌هاست. فیلد یافت‌نشده null می‌ماند. امتیاز OCR، احتمال کالیبره‌شده صحت فیلد نیست. تا اعتبارسنجی روی مدارک هدف، needs_review همواره true است. تعارض پشت و رو پنهان نمی‌شود و در alternatives می‌آید.
مختصات به شکل [x,y,width,height] و نسبت به تصویر پردازش‌شده پس از چرخش و تغییر اندازه است. واحد پیکسل است. ابعاد تصویر پردازش‌شده در pages موجود است.
محدودیت و خطاها
هر تصویر حداکثر ۱۲ MiB و ۲۴ مگاپیکسل؛ کل درخواست حداکثر ۲۵ MiB. حداکثر دو تصویر و دو درخواست پردازشی هم‌زمان به‌صورت پیش‌فرض. کدهای متداول: 401 کلید نامعتبر، 408 مهلت بارگذاری، 413 حجم بیش از حد، 415 قالب نامعتبر، 422 پارامتر نامعتبر، 429 نرخ درخواست، 502 پاسخ نامعتبر مدل، 503 موتور آماده نیست یا ظرفیت پر است، 504 پایان مهلت پردازش.
قالب MRZ فعلاً فقط TD3 است؛ نتیجه چک‌دیجیت اثبات اصالت نیست. OCR عمومی به معنی تضمین استخراج همه قالب‌های مدرک در همه کشورها نیست. کارت‌های بدون برچسب، چیدمان پیچیده و تصاویر کم‌کیفیت به ارزیابی و تکمیل پروفایل نیاز دارند.
سیاست‌های کنترل
generic قاعده شماره کشور خاصی ندارد. ir_national_id و tr_identity_card فقط شکل و چک‌دیجیت محلی شماره را کنترل می‌کنند. passport_td3 کنترل گذرنامه TD3 را فعال می‌کند. هیچ‌کدام استعلام ثبت رسمی، تأیید صدور، تشخیص جعل یا گواهی پوشش همه طرح‌های کارت نیستند. همه پاسخ‌ها نیازمند بازبینی باقی می‌مانند.
نگهداری داده
برنامه تصویر و نتیجه را در پایگاه داده یا آرشیو ذخیره نمی‌کند؛ فایل موقت OCR و آپلود در /tmp ایجاد و بسته می‌شود. Compose، /tmp را روی tmpfs قرار می‌دهد. تنظیم swap، گزارش‌گیری سرویس مدل و reverse proxy و نگهداری مرورگر باید جداگانه بررسی شود. قبل از انتشار بیرون از شبکه مورد اعتماد، HTTPS را در reverse proxy برقرار کنید.