إنشاء عملية

تتعامل نقطة النهاية هذه مع حالتي استخدام تشتركان في نفس المسار لكنهما تختلفان في معاملات الجسم والإمكانيات وحقول الاستجابة:

التأهيل - يتحقق من هوية المستخدم عن طريق مقارنة وجهه مع قاعدة هويات Unico (مطلوب subject.duiType + subject.code).
المعاملات - يتحقق من أنه نفس الشخص من عملية سابقة عن طريق مقارنة وجه بوجه (مطلوب referenceProcessId أو مصفوفة references مع صورة سيلفي / معرّف عملية).

يتم تحديد حالة الاستخدام النشطة بواسطة APIKEY المرسل في ترويسة الطلب.

للاطلاع على تدفق التكامل الكامل، انظر نظرة عامة على API.

نقطة النهاية

البيئة	الرابط
الإنتاج	`POST https://api.id.unico.app/processes/v1`
Sandbox	`POST https://api.id.uat.unico.app/processes/v1`

الطلب

الترويسات

الترويسة	القيمة
`Authorization`	`Bearer <access_token>` (انظر المصادقة)
`APIKEY`	مفتاح API المخصص - يحدد حالة الاستخدام النشطة والإمكانيات المفعّلة.
`Content-Type`	`application/json`

معاملات الجسم

التأهيل
المعاملات

الحقل	النوع	مطلوب	الوصف
`subject.duiType`	integer	نعم	معرّف نوع الوثيقة. انظر قيم `duiType` أدناه.
`subject.code`	string	نعم	قيمة المعرف كما هو محدد بواسطة `subject.duiType`. بدون نقاط أو شرطات.
`subject.name`	string	لا	الاسم الكامل.
`subject.gender`	string	لا	`M` أو `F`.
`subject.birthDate`	string (ISO 8601)	لا	تاريخ الميلاد (`YYYY-MM-DD`).
`subject.email`	string	لا	عنوان البريد الإلكتروني.
`subject.phone`	string	لا	رقم هاتف E.164.
`useCase`	string	لا	سياق العملية، مثلاً `Onboarding`.
`subsidiaryId`	string	لا	معرف الفرع — مطلوب فقط إذا كانت هناك فروع متعددة.
`imageBase64`	string	نعم	صورة سيلفي ملتقطة بواسطة واجهتك الأمامية، بتنسيق base64.

الحقل	النوع	مطلوب	الوصف
`references`	array	مشروط	مدخلات مرجعية لتدفقات التحقق 1:1. كل عنصر يحتوي على `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` أو `REFERENCE_TYPE_PROCESS_ID`) و`referenceContent` (صورة مشفرة بـ base64 أو UUID عملية).
`referenceProcessId`	string	مشروط	مهمل. استخدم `references` بدلاً منه. معرّف عملية التأهيل المرجعية للمقارنة معها. إذا كان المرجع عملية by-Unico، استخدم `authenticationInfo.authenticationId`.
`imageBase64`	string	نعم	صورة سيلفي ملتقطة بواسطة واجهتك الأمامية، بتنسيق base64.
`subject`	object	لا	حاوية معلومات المستخدم.
`subject.duiType`	string	لا	نوع المعرف. القيم المحتملة: `DUI_TYPE_BR_CPF`، `DUI_TYPE_MX_CURP`، `DUI_TYPE_US_SSN`، `DUI_TYPE_NG_NIN`، `DUI_TYPE_AR_DNI`، `DUI_TYPE_ID_NIK`.
`subject.code`	string	لا	قيمة المعرف كما هو محدد بواسطة `subject.duiType`. بدون نقاط أو شرطات.
`subject.name`	string	لا	الاسم الكامل للمستخدم.
`subject.gender`	string	لا	`M` أو `F`.
`subject.birthDate`	string (ISO 8601)	لا	تاريخ الميلاد (`YYYY-MM-DD`).
`subject.email`	string	لا	عنوان البريد الإلكتروني.
`subject.phone`	string	لا	رقم هاتف E.164.
`useCase`	string	لا	سياق العملية، مثلاً `Transactional`.
`subsidiaryId`	string	لا	معرّف الفرع - مطلوب فقط إذا كانت هناك فروع متعددة.

معلومة

لحالة الاستخدام هذه، لا يمكن التنسيق مع درجة المخاطر. يتم دائماً إرجاع النتيجة بشكل متزامن في استجابة POST.

قيم 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 الداخلي

متطلبات الصورة

الدقة الدنيا: 640 × 480 (معيار HD)
الحجم الأقصى للملف: 800 KB (يُنصح بضغط JPEG92)
التنسيقات المقبولة: PNG، JPEG، WebP
رموز JWT من SDK تنتهي صلاحيتها بعد 10 دقائق ويمكن استخدامها مرة واحدة فقط

مثال

التأهيل - cURL
التأهيل - Node.js
المعاملات - cURL
المعاملات - Node.js

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

الاستجابات

التأهيل
المعاملات

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}

تعتمد حقول الاستجابة على مفتاح APIKey الخاص بك

يعرض المثال أعلاه جميع حقول الإمكانيات الممكنة. ستتضمن استجابتك الفعلية فقط الحقول المتعلقة بالإمكانيات المفعّلة في إعدادات APIKey الخاصة بك — يتم حذف الحقول المتعلقة بالإمكانيات غير المفعّلة كلياً. تواصل مع مدير مشروع Unico لتفعيل الإمكانيات أو تعديلها.

الحقل	النوع	الوصف
`id`	string (UUID)	معرّف العملية. استخدمه مع الحصول على العملية لإعادة الاستعلام.
`status`	integer	`1` (قيد المعالجة)، `3` (انتهت بنجاح)، `5` (خطأ).
`unicoId.result`	string	`yes`، `no`، `inconclusive` - انظر التحقق من الهوية.
`riskLevel.result`	string	`approved`، `reproved`، `risk-critical`، `risk-high`، `inconclusive` — انظر القيم المحتملة أدناه أو تصنيف مخاطر الاحتيال.
`idFace.result`	string	`FOUND`, `NOT_FOUND` — انظر معرّف الوجه.
`idFace.personId`	string	معرّف مستقر وغير شفاف للوجه. يظهر فقط عندما تكون `idFace.result = FOUND`.
`identityFraudsters.result`	string	مهجور. استخدم `riskLevel` بدلاً منه. يمكن للعملاء الذين لديهم عمليات تكامل جارية الاستمرار في استخدامه أثناء تنسيق الترحيل مع الفريق المسؤول عن المشروع.
`government.serpro`	integer	درجة تشابه Serpro (0-100، -1، -2). متاح في البرازيل فقط. انظر عائد تشابه Serpro.
`liveness`	integer	`1` (نجح)، `2` (فشل) - انظر لايفنس.

riskLevel.result — القيم المحتملة

القيمة	المعنى
`approved`	هذا هو وجه صاحب الهوية، ولم يتم العثور على أي دليل يتعلق بالاحتيال.
`reproved`	يُوصى بالرفض، إذ تم اكتشاف مؤشرات احتيال متعددة.
`risk-critical`	يُوصى بالرفض، غير أن القرار النهائي يعود إلى تقديركم. تشير المخاطرة الحرجة إلى وجود ما لا يقل عن دليلين قويين على الاحتيال.
`risk-high`	يُوصى بالرفض أيضاً، لكن القرار يبقى بيدكم. تشير المخاطرة العالية إلى وجود دليل قوي واحد على الأقل على الاحتيال.
`inconclusive`	لم يتم العثور على أدلة قوية على الاحتيال، وبالتالي لا يمكن استنتاج ما إذا كانت هناك مخاطرة ذات صلة أم لا.

معلومة

عندما يكون unicoId.result = inconclusive وتنسيق درجة المخاطر نشط، قد تُرجع العملية status: 1 (قيد المعالجة). استعلم عبر الحصول على العملية أو استخدم webhooks لاسترداد النتيجة النهائية.

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

الحقل	النوع	الوصف
`id`	string (UUID)	معرّف العملية.
`status`	integer	`3` (انتهت بنجاح)، `5` (خطأ). لجميع القيم الممكنة، انظر الحصول على العملية.
`biometryToken.result`	boolean	`true` إذا تطابق الوجه المقدم مع العملية المرجعية؛ `false` خلاف ذلك.
`liveness`	integer	`1` (نجح)، `2` (فشل) - انظر لايفنس.

400 Bad Request

الحمولة غير صحيحة، أو الصورة غير صالحة، أو الحقول المطلوبة مفقودة. انظر رموز الخطأ أدناه.

403 Forbidden

رمز Bearer أو APIKEY مفقود أو منتهي الصلاحية أو غير صالح. انظر المصادقة.

409 Conflict

processId المقدم موجود بالفعل لهذا المستأجر. انظر رموز الخطأ أدناه.

429 Too Many Requests

تم الوصول إلى حد المعدل. عندما يتلقى نظامك خطأ HTTP 429، يجب عليك تنفيذ آليات لمنع الأعطال المتتالية وتجنب تفاقم القيود.

أفضل الممارسات:

فترة التهدئة (backoff): أوقف أو قلل الطلبات اللاحقة من نظامك فوراً. لا تعيد محاولة الطلبات الفاشلة باستمرار في حلقة ضيقة.
التخزين المؤقت وتنظيم المعدل: قم بتخزين الطلبات الصادرة مؤقتاً أو وضعها في قائمة انتظار للتحكم في تدفق حركة المرور قبل إعادة إرسالها.
التراجع الأسي مع التشتيت: عند إعادة المحاولة، قم بزيادة وقت الانتظار بشكل أسي بين المحاولات (مثلاً 1 ث، 2 ث، 4 ث، 8 ث) وأضف تأخيراً عشوائياً صغيراً ("تشتيت") لمنع تأثير القطيع حيث تعيد جميع الطلبات المؤجلة المحاولة في نفس الميلي ثانية بالضبط.

تحذير

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

للحدود الافتراضية وزيادة الطلبات والتفاصيل الإضافية، انظر حدود المعدل.

رموز الخطأ

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

الرمز	الرسالة	الوصف
`20900`	O base64 informado não é válido.	معامل base64 غير صالح. الأسباب المحتملة: ليس صورة أو محاولة حقن.
`20807`	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	دقة الصورة المرفوعة منخفضة جداً.
`20513`	The referenced process was not found.	يشير `referenceProcessId` إلى عملية غير موجودة أو لم تعد متاحة.
`20512`	The referenced process is not available for reuse.	العملية المرجعية موجودة لكنها غير متاحة لإعادة الاستخدام.
`20509`	The subject.name field is invalid.	يحتوي `subject.name` على أحرف غير صالحة.
`20508`	The subject.gender field is invalid.	يجب أن يكون `subject.gender` هو `M` أو `F`.
`20507`	O parâmetro subject.code é inválido.	CPF غير قياسي أو غير موجود.
`20506`	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	حجم الصورة يتجاوز 800 KB؛ اضغط إلى JPEG92.
`20505`	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	تنسيق base64 غير صالح أو غير مدعوم.
`20065`	The referenceProcessId field is invalid.	`referenceProcessId` ليس UUID صالحاً.
`20062`	The useCase field is invalid.	قيمة غير معروفة في حقل `useCase`.
`20024`	The referenceProcessId field is missing.	لم يتم تقديم معامل `referenceProcessId` ولم يتم إرسال `references` كبديل.
`20021`	The subject.phone field is invalid.	تنسيق `subject.phone` غير صالح (IDD + رمز المنطقة + الرقم، 13 حرف).
`20019`	The subject.birthDate field is invalid.	`subject.birthDate` خارج تنسيق ISO 8601 (`YYYY-MM-DD`).
`20009`	O parâmetro imagebase64 não foi informado.	معامل صورة السيلفي مفقود.
`20008`	The subject.email field is invalid.	تنسيق بريد إلكتروني غير صالح في `subject.email`.
`20006`	O parâmetro subject.name não foi informado.	معامل subject.name مفقود.
`20005`	O parâmetro subject.code não foi informado.	معامل subject.code مفقود.
`20004`	O parâmetro subject não foi informado.	معامل subject مفقود.
`20003`	The request body is missing or invalid.	حمولة فارغة أو غير صالحة.
`20002`	O parâmetro APIKey não foi informado.	معامل APIKEY مفقود من ترويسة الطلب.
`20001`	O parâmetro authtoken não foi informado.	معامل رمز التكامل مفقود من ترويسة الطلب.
`10508`	The JWT with the captured face has already been used.	يمكن استخدام JWT مرة واحدة فقط.
`10507`	The JWT with the captured face is expired.	انتهت صلاحية JWT؛ يجب إرساله خلال 10 دقائق.
`10506`	The imageBase64 field is not a valid JWT from SDK.	`imageBase64` ليس JWT صالحاً تم إنشاؤه بواسطة SDK.

الرمز	الرسالة	الوصف
`30017`	User does not have permission to perform this action.	JWT غير صحيح أو مستخدم بدون صلاحية لتنفيذ هذه العملية.
`10502`	O token informado está expirado.	انتهت صلاحية رمز الوصول.
`10501`	O token informado é inválido.	رمز المصادقة غير صالح.
`10201`	O AppKey informado é inválido.	APIKEY غير صالح أو غير موجود.

الرمز	الرسالة	الوصف
`20073`	The processID already exists.	`processId` المقدم موجود بالفعل لهذا المستأجر.

الرمز	الرسالة	الوصف
`99999`	Internal failure! Try again later	عند حدوث خطأ داخلي.

ما التالي

للاستعلام عن نتيجة عملية التأهيل، انظر الحصول على العملية.
لعمليات المستندات والتحقق من العمر، انظر الصفحات المعنية في هذا القسم.

نقطة النهاية​

الطلب​

مثال​

الاستجابات​

رموز الخطأ​

ما التالي​