واجهة API مجانية للتعرّف على جوازات السفر

هذه واجهة API مجانية للتعرّف الضوئي على جوازات السفر يمكنك استدعاؤها قبل أن يكون لديك حساب. ينشر التوثيق مفتاح sandbox عامًا، وهذا المفتاح يُجري 10 عمليات تعرّف لكل عنوان IP، وكلها عمليات تعرّف حقيقية – بلا تسجيل، ولا بطاقة ائتمان، ولا مكالمة مبيعات تعترض طريقك. سجّل، وسنضيف إلى حسابك 20 وحدة رصيد فوق ذلك. بعد ذلك يكلّف المستند المُتعرَّف عليه سنتًا واحدًا، بسعر ثابت، مهما كان الحجم. أرسل صورة فوتوغرافية أو نسخة ممسوحة ضوئيًا من جواز سفر أو بطاقة هوية أو وثيقة سفر؛ واحصل على JSON منظّم يتضمن حامل المستند، والمستند، وكل حقل عُثر عليه، ومنطقة القراءة الآلية (MRZ) مع أرقام التحقق فيها مُتحقَّقًا منها. المسح الفاشل لا يكلّف شيئًا.

نفّذ الاستدعاء الأول اقرأ الدليل

نفّذ أول عملية تعرّف بلا حساب

انسخ المفتاح من التوثيق وأرسل صورة. هذا هو التكامل كله:

IMG=$(base64 -i passport.jpg | tr -d '\n')

curl -s https://api.doc.cheap/v1/scans \
  -H "Authorization: Bearer sk_sandbox_public" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-call-1" \
  -d '{"image":"'"$IMG"'","options":{"mode":"full"}}'

sk_sandbox_public هو مفتاح sandbox العام – منشور عن قصد، وليس سرًّا، وعدد طلباته محدود. ويعني Idempotency-Key أن الطلب المُعاد لا تُحتسب عليه رسوم مرة ثانية، وهذا مهم يوم تعيد تشغيل طابور.

ما الذي تحصل عليه

بنية استجابة واحدة، وثماني مجموعات، وكل المفاتيح حاضرة دائمًا. يسرد مستكشف الحقول كل مفتاح مع نوعه، و مرجع الـ API (بالإنجليزية) هو العقد نفسه.

{
  "meta": { "schema_version": "1.0", "status": "recognized", "billed": true,
            "confidence": "high",
            "timing": { "upload_ms": 118, "processing_ms": 684, "total_ms": 826 } },
  "document": { "kind": "passport", "country": "GRC", "country_name": "Greece",
                "number": "AM7304518", "series": null,
                "issue_date": "2022-03-10", "expiry_date": "2032-03-10",
                "is_expired": false, "days_remaining": 2001 },
  "holder": { "given_names": "ELENI SOFIA", "surname": "PARADEIGMA",
              "birth_date": "1994-03-08", "sex": "F", "nationality": "GRC" },
  "mrz": { "status": "passed", "reason": null, "lines": ["…", "…"] },
  "fields": [ "…" ], "images": { "…": null },
  "quality": { "overall": "pass" },
  "authenticity": { "overall": "not_checked", "checks": [] }
}

قيمة meta.status واحدة من خمس سلاسل بالضبط: recognized، no_document_found، unreadable، unsupported_document، rejected.
التواريخ بصيغة ISO-8601 دائمًا. القيمة الغائبة هي null، ولا يغيب المفتاح أبدًا.
الحقل meta.billed موجود في كل استجابة، ويبيّن هل كلّف ذلك الاستدعاء شيئًا.
تحمل fields[] كل حقل في المستند، مقروءًا من المنطقة المرمّزة ومن المنطقة المطبوعة كلٌّ على حدة، ولكلٍّ منها درجة ثقتها، لتمكن مقارنة القراءتين. وتصل القيم المكتوبة بخطها الأصلي إلى جانب النقحرة اللاتينية، موسومةً بلغتها.

حاملة المستند في المثال عيّنة اصطناعية: شخص مُختلَق، مع حساب حقيقي لأرقام التحقق على قيم مُختلَقة. وتُشرح المنطقة التي تحملها في صفحة صيغ MRZ.

التكلفة بعد الاستدعاءات المجانية

1¢ للمستند. سعر ثابت، لكل الحسابات، مهما كان الحجم.

رقم واحد مهما كان الحجم: لا شرائح، ولا قائمة أسعار تطلبها، ولا شيء للتفاوض عليه. وحدة الرصيد الواحدة تساوي سنتًا واحدًا، والسنت الواحد يساوي مستندًا واحدًا يُتعرَّف عليه.

لا تُحتسب الرسوم إلا على المستندات المُتعرَّف عليها. لا تُحتسب الرسوم إلا على مستند تم التعرّف عليه بنجاح. المسح الذي لا يجد مستندًا، أو لا يستطيع قراءة الصورة، أو لا يستطيع تحديد النوع، يُجيب بحكمه ولا يكلّف شيئًا.

✓ التعرّف مجانًا على 10 مستندات لكل عنوان بمفتاح sandbox العام، دون أي حساب على الإطلاق – بحد أقصى 10 طلبات في الساعة، أيًّا كانت الإجابة.
✓ عند التسجيل نضيف إلى رصيدك 20 مستندًا مجانًا.

كيف تُحتسب الرسوم كيف يُقارَن ذلك بالبدائل

ماذا يحدث للصورة

مع مفتاح sandbox لا يُحتفظ بشيء. لا تُكتب الصورة على القرص أبدًا – فهي تعيش في الذاكرة طوال مدة الطلب – ولا تُخزَّن النتيجة كذلك. أما مع مفتاح live الخاص بك فتُحفظ النتيجة لتتمكن من قراءتها لاحقًا: لعدد الساعات الذي يحدده الطلب في retain_hours، وإن لم يحدده فللمدة المضبوطة في إعداد الاحتفاظ بحسابك، وهي سنة واحدة (8760 ساعة) ما لم تغيّرها.

أرسل retain_hours: 0 كي لا يُحتفظ بشيء – لا نتيجة مخزَّنة، ولا شيء تسترجعه لاحقًا. القرار لك، في كل استدعاء.

عندما تتعذّر قراءة الصورة

الاستجابة تقول ذلك، وهي مجانية. يميّز meta.status بين الحالات، وفي الحالات الثلاث تكون قيمة meta.billed هي false:

no_document_found – لا شيء يشبه المستند في الإطار.
unreadable – عُثر عليه، وتعذّرت قراءته – وهج، أو ضبابية، أو دقة غير كافية.
unsupported_document – قُرئ، لكن هذا النوع غير مدعوم.

تحمل كل استجابة تفصيل توقيتاتها الخاص، ويُنشر الوسيط الحي على صفحة الحالة بدلًا من التعهّد به هنا.

أدوات مجانية لا تحتاج إلى أي مفتاح

محلّل MRZ – الصق منطقة TD1 أو TD2 أو TD3، وشاهد كل حقل وكل رقم تحقق. يعمل في متصفحك.
مولّد MRZ – أنشئ منطقة صالحة للاختبار.
مستكشف حقول المستند – تصفّح مفردات الحقول التي تجيب بها الـ API.

تستدعيها من مساعد بدلًا من الشيفرة؟ يتيح خادم MCP التعرّف نفسه في صورة ثلاث أدوات.

الأسئلة الشائعة

ما التعرّف الضوئي على جوازات السفر؟

التعرّف الضوئي على جوازات السفر (OCR) هو القراءة الآلية لصفحة البيانات في جواز السفر من صورة فوتوغرافية أو نسخة ممسوحة ضوئيًا. وله نصفان. منطقة القراءة الآلية (MRZ) هي السطران المؤلّفان من 44 حرفًا أسفل الصفحة، المطبوعان بخط مصمَّم لتقرأه آلة والمحميّان بأرقام التحقق. والمنطقة المرئية هي كل ما طُبع ليقرأه إنسان: الاسم والرقم والتواريخ نفسها، إضافةً إلى ما لا تحمله المنطقة – مكان الميلاد، وجهة الإصدار، والصورة الشخصية. قراءة النصف الأول وحده أسهل وتخبرك بأقل؛ وقراءة النصفين تتيح لك المقارنة بينهما.

هل توجد واجهة API مجانية للتعرّف على جوازات السفر؟

نعم، ضمن حدود. هذه الواجهة تنشر في التوثيق مفتاح sandbox يُجري 10 عمليات تعرّف لكل عنوان IP بلا حساب ولا بطاقة، وكلها عمليات تعرّف حقيقية، ويضيف التسجيل 20 وحدة رصيد – أي 30 مستندًا قبل أي دفع. ودون اتصال بالإنترنت، تقرأ مكتبة PassportEye المفتوحة المصدر مع tesseract منطقة القراءة الآلية مجانًا على جهازك؛ لكنها لا تقرأ الجانب المطبوع، ودقتها مع صور الهاتف تعتمد كليًا على المعالجة المسبقة للصور التي تُجريها أنت. أما «مجاني إلى الأبد وبأحجام كبيرة» فغير موجود في هذه الفئة لدى أي أحد، ونحن منهم.

كم تكلّف واجهة API للتعرّف على جوازات السفر؟

هنا، $0.01 للمستند، بسعر ثابت، مهما كان الحجم، ولا شيء عندما يفشل التعرّف. تختلف أسعار القوائم المنشورة لدى الآخرين في وحداتها – بعض المزوّدين يحتسب بالصفحة، ونحن نحتسب بالمستند – لذا قارن على الوحدة نفسها قبل أن تقارن الأرقام. والأرقام، كلٌّ منها مقروء من صفحة المزوّد نفسه ومرتبط بها، موجودة في صفحة المقارنة.

هل تخزّنون صورة جواز السفر؟

لا. لا تُكتب الصورة على القرص أبدًا؛ فهي موجودة في الذاكرة طوال مدة الطلب وتختفي عند إرسال الاستجابة. ومع مفتاح sandbox لا تُخزَّن النتيجة كذلك. أما مع مفتاح live فتُحفظ لعدد الساعات الذي تمرّره في retain_hours، وإن لم تمرّره فللمدة المضبوطة في إعداد الحساب – سنة واحدة (8760 ساعة) ما لم تغيّرها – ومع retain_hours: 0 لا يُحتفظ بشيء. لا يوجد هنا أي مخزن للمستندات، وهذا هو الجواب المختصر عمّا يحدث لجوازات سفر مستخدميك.

ماذا يحدث إذا تعذّرت قراءة الصورة؟

تحصل على إجابة ولا تُحتسب عليك رسوم. تحمل الاستجابة meta.status – بقيمة unreadable حين يُعثر على المستند وتتعذّر قراءته، أو no_document_found حين لا يكون في الإطار ما يشبه المستند – و meta.billed بقيمة false. وتحمل مجموعة quality الحكم على الصورة نفسها. أعد التصوير دون وهج على المنطقة، واملأ الإطار بصفحة البيانات، وحافظ على دقة المنطقة فوق 300 DPI تقريبًا.