إعادة المعالجة واستيراد القاعدة البيومترية

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

النطاق

تغطي هذه المادة نوعين من العمليات:

• إعادة المعالجة: إعادة معالجة السجلات البيومترية للمستخدمين الذين مروا بالفعل عبر قاعدة العميل وقاعدة Unico لإعادة التقييم أو الترحيل بين الأنظمة.
• استيراد القاعدة البيومترية: الرفع الأولي أو تحديث قاعدة تحتوي على صور سيلفي لأغراض التحقق من الهوية و/أو تصنيف المخاطر.
• استيراد قاعدة الوثائق: رفع قاعدة وثائق إلى جانب صور السيلفي لأغراض التحقق عبر Facematch أو CPF Match (البرازيل فقط).

المتطلبات المسبقة

• يجب أن يكون لدى العميل عقد نشط أو اتفاقية عدم إفصاح موقعة مع Unico وأن يكون في مرحلة التكامل (استثناء إذا تمت الموافقة من فريق الحوكمة).
• سيتبع المشروع اتفاقيات TPS (المعاملات في الثانية) الرسمية. انظر اتفاقية TPS أدناه.
• قبل الحصول على بيانات اعتماد الإنتاج، يجب إجراء اعتماد التكامل الكامل لضمان جودة البيانات وتوافق الحمولة والأداء المستقر.
• يجب إنشاء حساب خدمة مخصص لإعادة المعالجة أو الاستيراد (مثال: "Reprocessing" أو "Legacy_Import").
• سيتم إنشاء مفتاح API مخصص خصيصًا لإعادة المعالجة/الاستيراد.
• (اختياري) يمكن إنشاء فرع مخصص لإعادة المعالجة/الاستيراد. يتم تحديد هذا المعامل في الحمولة باسم subsidiaryId. انظر معاملات الحمولة أدناه.
• سيتم إلغاء تنشيط مفتاح API وحساب الخدمة بعد الفترة المتفق عليها أو اكتمال المعالجة.

القدرات المتاحة

القدرة	الوصف
التحقق من الهوية	يتحقق مما إذا كانت صورة السيلفي المقدمة تنتمي إلى المالك الفعلي للمعرّف.
تصنيف مخاطر الاحتيال	يتحقق من وجود سجل سلوك احتيالي مرتبط بهذا الوجه.
Facematch	يتحقق مما إذا كانت صورة الوثيقة تتطابق مع صورة السيلفي المقدمة.
CPF Match Brazil only	يتحقق مما إذا كان رقم CPF المقدم يتطابق مع رقم CPF المطبوع على الوثيقة. ملاحظة: لا تحتوي جميع وثائق RG على رقم CPF مطبوع.

متطلبات صورة السيلفي

• يجب تقديمها بتنسيق base64.
• يجب أن تتبع الصورة معيار ICAO (خلفية فاتحة، وجه في المنتصف، بدون إكسسوارات تعيق التعرف، إضاءة مناسبة).
• الأبعاد الموصى بها: 1080x1920 (عمودي) أو 1920x1080 (أفقي).
• الحجم الأقصى: 800 كيلوبايت (اضغط باستخدام JPEG 92 إذا لزم الأمر).
• الاتجاه: عمودي.

متطلبات الوثيقة

• أنواع الوثائق المدعومة: انظر التقاط الوثائق وإعادة الاستخدام — الوثائق المدعومة.
• يجب أن تشمل الصور كلاً من الوجه والظهر للوثيقة، مرئيَّين بالكامل دون قص.
• يجب أن تكون الوثيقة مقروءة — واضحة، جيدة الإضاءة، وخالية من العوائق.

اتفاقية TPS

• الحد الأقصى المتفق عليه لعدد المعاملات في الثانية لهذا المشروع هو 10 TPS.
• وزّع الطلبات بالتساوي على مدار الوقت بدلاً من إرسالها على شكل دفعات كبيرة.
• يجب عدم تجاوز هذا الحد دون موافقة رسمية من فريق Unico.
• قد يتم إسقاط أو حظر الطلبات التي تتجاوز الحد تلقائيًا.
• إذا كانت هناك حاجة لزيادة مؤقتة، يلزم اتفاق رسمي مسبق.

التكامل

نقاط النهاية

البيئة	عنوان URL الأساسي	الوصول	ملاحظات
Staging	https://api.id.uat.unico.app	مفتوح	إلزامي للاختبار
Production	https://api.id.unico.app	فقط بعد اعتماد الاعتماد	يتطلب تحكمًا صارمًا في TPS

الترويسات المطلوبة

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

معاملات الحمولة

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}

الحقل	النوع	مطلوب	الوصف
subject	object	نعم	بيانات تعريف المستخدم.
subject.duiType	integer	نعم	معرّف نوع الوثيقة. انظر قيم duiType أدناه.
subject.code	string	نعم	CPF أو معرّف مستخدم آخر.
subject.name	string	نعم	الاسم الكامل للمستخدم.
subject.email	string	لا	البريد الإلكتروني للمستخدم.
subject.phone	string	لا	رقم هاتف المستخدم.
subject.birthDate	string	لا	تاريخ ميلاد المستخدم (DD/MM/YYYY).
subject.gender	string	لا	جنس المستخدم (M أو F).
useCase	string	نعم	اسم حالة الاستخدام ("Reprocessamento" أو "Importação de base").
subsidiaryId	string	لا	معرّف UUID للفرع (يقدمه Unico).
imageBase64	base64	نعم	صورة سيلفي المستخدم محولة إلى base64.
document	object	لا	بيانات الوثيقة المرتبطة بالعملية.
document.purpose	string	لا	الغرض من الوثيقة (مثال: "Reprocessamento").
document.documentId	string	لا	معرّف الوثيقة.
document.files	array	لا	قائمة ملفات صور الوثيقة.
document.files[].data	base64	لا	صورة الوثيقة محولة إلى base64.
document.files[].faceDocumentMatch	boolean	لا	يشير إلى ما إذا كان الوجه في الوثيقة يتطابق مع صورة السيلفي المقدمة.

قيم duiType

الدولة	الرمز	الوصف
BR	1	CPF البرازيلي
BR	5	جواز سفر برازيلي
MX	2	CURP المكسيكي
AR	6	جواز سفر أرجنتيني
AR	7	DNI الأرجنتيني
US	4	SSN الأمريكي
US	11	جواز سفر أمريكي
US	18	رخصة قيادة أمريكية
ID	16	NIK الإندونيسي
NG	8	NIN النيجيري
CL	9	RUN التشيلي
EC	10	NI الإكوادوري
GT	12	CUI الغواتيمالي
UY	13	CI الأوروغوياني
ZZ	15	عنوان البريد الإلكتروني
ZZ	17	رقم الهاتف
MX	25	RFC المكسيكي (شخص طبيعي)
CO	26	NIT الكولومبي
PE	27	RUC البيروفي
CA	28	SIN الكندي
DK	29	CPR الدنماركي
GB	30	رقم التأمين الوطني البريطاني (NINO)
PL	31	PESEL البولندي
SE	32	الرقم الشخصي السويدي (PNR)
AT	34	الرقم الضريبي النمساوي (STNR)
FI	35	رمز الهوية الشخصية الفنلندي (HETU)
—	0	غير محدد
—	3	معرّف Unico الداخلي

ملاحظات مهمة

• يجب أن تتوافق صورة السيلفي مع معيار ICAO بجودة وإضاءة مناسبة.
• يجب أن تكون صورة السيلفي بتنسيق base64.
• تجنب الإرسال الجماعي بدون تحكم في TPS — قد يؤدي ذلك إلى تفعيل تحديد المعدل (انظر معالجة الأخطاء أدناه).
• اختبر البيانات والتكامل دائمًا في بيئة Staging أولاً.

الاستجابات

نجاح — 200 OK

بدون وثيقة

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}

الحقل	النوع	الوصف
id	string	معرّف العملية. احفظه للاستعلامات المستقبلية أو إذا قمت بتطبيق التحقق (1:1) لاحقًا.
status	integer	حالة المعاملة.
unicoId.result	string	استجابة قدرة التحقق من الهوية.
identityFraudsters.result	string	استجابة قدرة تصنيف مخاطر الاحتيال.

مع وثيقة (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "identityFraudsters": {
    "result": "yes"
  }
}

الحقل	النوع	الوصف
id	string	معرّف العملية. احفظه للاستعلامات المستقبلية أو إذا قمت بتطبيق التحقق (1:1) لاحقًا.
status	integer	حالة المعاملة.
score	number	نتيجة Facematch.
unicoId.result	string	استجابة قدرة التحقق من الهوية.
faceDocumentMatch.faceMatch	boolean	ما إذا كانت صورة الوثيقة تتطابق مع صورة السيلفي المقدمة.
identityFraudsters.result	string	استجابة قدرة تصنيف مخاطر الاحتيال.

خطأ في معالجة الصورة

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
}

الأخطاء الشائعة

تشير الرموز في نطاق 4xx إلى أخطاء في التحقق من البيانات المقدمة. تشير الرموز في نطاق 5xx إلى أعطال من جانب الخادم.

رمز HTTP	نوع الخطأ	السبب المحتمل	الإجراء الموصى به
400	Bad Request	حمولة غير صالحة	تحقق من البنية والمحتوى.
401	Unauthorized	رمز مميز منتهي الصلاحية أو غير صالح	أعد إنشاء الرمز المميز.
403	Forbidden	مفتاح API غير صحيح أو صلاحيات غير كافية	تحقق من بيانات الاعتماد.
429	Too Many Requests	تم تجاوز معدل الطلبات	انتظر والتزم بحد TPS.
500+	Internal Server Error	عطل داخلي	أعد المحاولة بعد بضع ثوانٍ؛ افتح تذكرة إذا استمرت المشكلة.

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

• يجب مراقبة حد المعدل (HTTP 429) بعناية. قد يؤدي التحميل الزائد للطلبات إلى حظر خط المعالجة.
• التزم دائمًا بمعدل TPS المتفق عليه مع Unico (انظر اتفاقية TPS).
• للأعطال المستمرة (5xx)، أعد المعالجة مع التحكم في إعادة المحاولة/التراجع.