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

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

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

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

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

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: الشكل الذي ترغب في تلقي نتيجة الاستجابة به، هنا يتم ملؤه بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، بعد التقديم يمكنك اختيارها مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • image_url: رابط صورة الهوية التي تحتاج إلى معالجتها.
  • config: خيارات تكوين اختيارية، حقل قيمة منطقية، الافتراضي هو false، يدعم copy_warn، border_check_warn، reshoot_warn، detect_ps_warn، temp_id_warn، quality (عتبة 0-100).
بعد الاختيار، يمكنك أن تلاحظ أن الجانب الأيمن قد أنشأ أيضًا الكود المقابل، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "sim": 99.76,
  "result": "Success",
  "description": "نجاح",
  "name": "اسم الهوية",
  "sex": "جنس الهوية",
  "nation": "أمة الهوية",
  "birth": "تاريخ ميلاد الهوية",
  "address": "عنوان السكن في الهوية",
  "id_num": "رقم الهوية",
  "portrait": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBA.....DEhE2lbPMcOtG3f/DLT/yX8if7Kxn/AD7h85wdttPifRf1e6//2Q==",
  "warnings": "",
  "quality": 0,
  "encryption": null
}
تتضمن النتيجة العائدة عدة حقول، كما هو موضح أدناه:
  • sim: درجة التشابه، نطاق القيم [0.00، 100.00]. يُوصى بأن تكون درجة التشابه أكبر من أو تساوي 70 لتعتبر نفس الشخص، يمكنك ضبط العتبة وفقًا للسيناريو المحدد (معدل الخطأ عند عتبة 70 هو واحد من الألف، ومعدل الخطأ عند عتبة 80 هو واحد من عشرة آلاف).
  • result: رمز خطأ العمل، في حالة النجاح يتم إرجاع “Success”، وفي حالة الخطأ يرجى الرجوع إلى قائمة رموز الخطأ في قسم FailedOperation أدناه.
  • description: هنا نتيجة التحقق من الاسم ورقم الهوية.
  • name: معلومات الاسم في الهوية، إذا لم يتم تحميل صورة الهوية، ستكون فارغة.
  • sex: معلومات الجنس في الهوية، إذا لم يتم تحميل صورة الهوية، ستكون فارغة.
  • nation: معلومات الأمة في الهوية، إذا لم يتم تحميل صورة الهوية، ستكون فارغة.
  • birth: معلومات تاريخ الميلاد في الهوية، إذا لم يتم تحميل صورة الهوية، ستكون فارغة.
  • address: معلومات عنوان السكن في الهوية، إذا لم يتم تحميل صورة الهوية، ستكون فارغة.
  • id_num: معلومات رقم الهوية في الهوية، إذا لم يتم تحميل صورة الهوية، ستكون فارغة.
  • portrait: ترميز base64 لصورة الهوية، إذا فشلت عملية قص الصورة، سيتم استخدام الصورة الكاملة للهوية للمقارنة وإرجاع فارغ.
  • warnings: معلومات التحذير، عندما يتم تكوين معلومات التحذير في التكوين، سيتوقف مقارنة الصور، وستعود النتيجة بخطأ (FailedOperation.OcrWarningOccurred) مع هذه المعلومات التحذيرية.
  • quality: درجة جودة الصورة، عندما يتم تكوين تحذير ضبابية الصورة في الطلب، تكون هذه المعلمة ذات معنى، نطاق القيم (0-100)، حاليًا العتبة الافتراضية هي 50، وأي شيء أقل من 50 سيؤدي إلى تحذير ضبابية.
  • encryption: معلومات تشفير البيانات الحساسة.
يمكنك أن ترى أن معلومات الهوية تتمتع بموثوقية عالية. بالإضافة إلى ذلك، إذا كنت ترغب في إنشاء الكود المناسب للتكامل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/identity/idcard/check-1e' \
-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/check-1e"

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)

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

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

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

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