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

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

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

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

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

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء API، بعد التقديم يمكنك اختيارها مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • name: الاسم.
  • id_card: رقم الهوية.
  • image_url: رابط صورة الوجه التي تحتاج إلى المعالجة.
  • validity_end: تاريخ انتهاء صلاحية الهوية، التنسيق: YYYYMMDD، استخدم “00000000” بدلاً من ذلك لفترة طويلة؛
  • validity_begin: تاريخ بدء صلاحية الهوية، التنسيق: YYYYMMDD.
  • encryption: اختياري، معلمات تشفير الحقول الحساسة (إذا كان هناك حاجة لإرسال نص مشفر).
بعد الاختيار، يمكنك أن تلاحظ أن الجانب الأيمن قد أنشأ أيضًا كودًا مطابقًا، كما هو موضح في الصورة:

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

url = "https://api.acedata.cloud/identity/idcard/check-2e"

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

payload = {
    "name": "***",
    "id_card": "***",
    "validity_begin": "***",
    "validity_end": "***"
}

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

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

عند استدعاء API، إذا واجهت خطأ، ستقوم API بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 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"
}

​
الخاتمة

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