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

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة التطبيقات للتعرف على بطاقة الهوية والتحقق من المعلومات للتقدم للحصول على الخدمة المناسبة، بعد دخول الصفحة، انقر على زر “Acquire” كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال رابط صورة بطاقة الهوية، للحصول على نتائج التحقق بعد المعالجة، يجب أولاً تمرير حقل image_url ببساطة، ثم يمكننا ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، يمكنك اختياره مباشرة بعد التقديم.
كما تم تعيين جسم الطلب، بما في ذلك:
  • image_url: رابط صورة بطاقة الهوية التي تحتاج إلى معالجتها.
  • encryption: اختياري، معلمة تشفير الحقول الحساسة (إذا كان هناك حاجة لإرسال نص مشفر).
بعد الاختيار، يمكنك أن تلاحظ أن الجانب الأيمن قد تم إنشاء كود مطابق، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتائج التالية: 
{
  "result": "0",
  "description": "الاسم ورقم الهوية متطابقان",
  "name": "اسم بطاقة الهوية",
  "id_card": "رقم بطاقة الهوية",
  "sex": "جنس بطاقة الهوية",
  "nation": "أمة بطاقة الهوية",
  "birth": "تاريخ ميلاد بطاقة الهوية",
  "address": "عنوان السكن في بطاقة الهوية"
}
تتضمن النتائج العائدة عدة حقول، كما هو موضح أدناه:
  • result، رمز نتيجة التحقق، تفاصيل الرسوم كما يلي.
    • رموز النتائج المدفوعة:
      • 0: الاسم ورقم الهوية متطابقان
      • -1: الاسم ورقم الهوية غير متطابقين
    • رموز النتائج غير المدفوعة:
      • -2: رقم الهوية غير قانوني (طول، رقم تحقق، إلخ غير صحيح)
      • -3: اسم غير قانوني (طول، تنسيق، إلخ غير صحيح)
      • -4: خطأ في خدمة قاعدة البيانات
      • -5: لا يوجد سجل لرقم الهوية في قاعدة البيانات
      • -6: نظام المقارنة المعتمد في مرحلة التحديث، يرجى المحاولة لاحقًا
      • -7: عدد مرات التحقق تجاوز الحد اليومي.
  • description، هنا نتيجة التحقق من الاسم ورقم الهوية.
  • name، معلومات الاسم في بطاقة الهوية، إذا لم يتم تحميل صورة بطاقة الهوية، ستكون فارغة.
  • id_card، معلومات رقم الهوية في بطاقة الهوية، إذا لم يتم تحميل صورة بطاقة الهوية، ستكون فارغة.
  • sex، معلومات الجنس في بطاقة الهوية، إذا لم يتم تحميل صورة بطاقة الهوية، ستكون فارغة.
  • nation، معلومات الأمة في بطاقة الهوية، إذا لم يتم تحميل صورة بطاقة الهوية، ستكون فارغة.
  • birth، معلومات تاريخ الميلاد في بطاقة الهوية، إذا لم يتم تحميل صورة بطاقة الهوية، ستكون فارغة.
  • address، معلومات عنوان السكن في بطاقة الهوية، إذا لم يتم تحميل صورة بطاقة الهوية، ستكون فارغة.
يمكن ملاحظة أن المعلومات المتعلقة بالاسم ورقم الهوية في بطاقة الهوية متطابقة وفعالة، كما تم استخدام تقنية OCR لاستخراج المعلومات الأخرى وعرضها. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/identity/idcard/ocr' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": {image_url}
}'
كود التكامل بلغة Python كما يلي: 
import requests

url = "https://api.acedata.cloud/identity/idcard/ocr"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": {image_url}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
التحقق من المعلومات المخصصة

نحن نقدم أيضًا طريقة للتحقق دون تسريب معلومات صورة بطاقة الهوية، حيث يمكنك فقط إدخال الاسم name ورقم الهوية id_card للتحقق من صحة وتوافق الاسم ورقم الهوية، فيما يلي المعلومات المحددة المدخلة:

بعد النقر على التشغيل، حصلنا على النتائج التالية: 
{
    "address": "",
    "birth": "",
    "description": "الاسم ورقم الهوية متطابقان",
    "id_card": "رقم بطاقة الهوية",
    "name": "اسم بطاقة الهوية",
    "nation": "",
    "result": "0",
    "sex": ""
 }
من النتائج، لا يتم تسريب أي معلومات خاصة أخرى، ويمكن أيضًا إتمام التحقق من صحة وتوافق الاسم ورقم الهوية.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم الواجهة بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 400 token_mismatched: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صحيحة.
  • 400 api_not_implemented: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صحيحة.
  • 401 invalid_token: غير مصرح، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد المسموح به.
  • 500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

​
مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

من خلال هذه الوثيقة، أصبحت على دراية بكيفية استخدام واجهة برمجة التطبيقات للتعرف على بطاقة الهوية والتحقق من المعلومات للتحقق من صحة وتوافق الاسم ورقم الهوية المدخلين. نأمل أن تساعدك هذه الوثيقة في تكامل واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.