إنشاء عملية

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

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

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

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

نقطة النهاية

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

الطلب

الترويسات

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

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

التأهيل

الحقل	النوع	مطلوب	الوصف
subject.code	string	نعم	رقم CPF (البرازيل) أو CURP (المكسيك).
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.
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.code	string	لا	رقم CPF (البرازيل) أو CURP (المكسيك).
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.

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

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

مثال

التأهيل — cURL

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": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

التأهيل — Node.js

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: {
      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

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

المعاملات — Node.js

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({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

الاستجابات

التأهيل

200 OK

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

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية. استخدمه مع الحصول على العملية لإعادة الاستعلام.
status	integer	1 (قيد المعالجة)، 3 (انتهت بنجاح)، 5 (خطأ). لجميع القيم الممكنة، راجع الحصول على العملية.
unicoId.result	string	yes، no، inconclusive — راجع التحقق من الهوية.
identityFraudsters.result	string	yes، inconclusive — راجع تصنيف مخاطر الاحتيال.
government.serpro	integer	درجة تشابه Serpro (0–100، -1، -2). راجع عائد تشابه Serpro.
liveness	integer	1 (نجح)، 2 (فشل) — راجع لايفنس.

معلومة

عندما تكون 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

تم الوصول إلى حد معدل الطلبات. أعد المحاولة بعد الفاصل الزمني المُشار إليه في ترويسة الاستجابة Retry-After. راجع حدود معدل الطلبات.

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
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 كيلوبايت؛ اضغطها بصيغة 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 غير صالح (رمز الاتصال الدولي + رمز المنطقة + الرقم، 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.

403 Forbidden

الرمز	الرسالة	الوصف
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 غير صالح أو غير موجود.

409 Conflict

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

500 Internal Server Error

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

ما التالي

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