التحقق من العمر

للاطلاع على تدفق التكامل الكامل، انظر نظرة عامة على 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	object	نعم	حاوية معلومات المستخدم.
subject.code	string	مشروط	CPF (BR) أو CURP (MX)، بدون تنسيق. مطلوب عندما يتضمن التدفق لايفنس أو التحقق من الهوية (انظر إمكانية التحقق من العمر)؛ غير مطلوب لتدفقات التحقق من العمر فقط.
subject.name	string	لا	الاسم الكامل للمستخدم.
subject.gender	string	لا	M للذكر أو F للأنثى.
subject.birthDate	string (ISO 8601)	لا	تاريخ الميلاد (YYYY-MM-DD).
subject.email	string	لا	عنوان البريد الإلكتروني للمستخدم.
subject.phone	string	لا	رقم الهاتف: رمز الدولة + رمز المنطقة + الرقم، بدون فواصل (مثلاً 5519725570707).
useCase	string	لا	معرّف حالة الاستخدام للعملية.
subsidiaryId	string	لا	معرّف الفرع - مطلوب فقط إذا كانت هناك فروع متعددة.
imageBase64	string	نعم	مخرجات SDK المشفرة أو صورة base64 (PNG، JPEG، WebP).

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

• الدقة الدنيا: 640 × 480 (معيار HD)
• الحجم الأقصى للملف: 800 KB (يُنصح بضغط JPEG92)
• رموز 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",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "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',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

الاستجابات

200 OK

تعتمد حقول الاستجابة المُرجعة على الإمكانيات المفعّلة لمفتاح APIKEY الخاص بك.

التحقق من العمر فقط (بدون لايفنس، بدون التحقق من الهوية):

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

التحقق من العمر + لايفنس + التحقق من الهوية:

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

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية. استخدمه مع الحصول على العملية لإعادة الاستعلام.
status	integer	3 (انتهت بنجاح)، 5 (خطأ). استخدم فقط status = 3 لقرارات الأعمال. لجميع القيم الممكنة، انظر الحصول على العملية.
idAge.result	string	yes، no، inconclusive - نتيجة التحقق من العمر. موجودة في جميع الاستجابات.
unicoId.result	string	yes، no، inconclusive - موجودة فقط عند تفعيل التحقق من الهوية.
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 ث) وأضف تأخيراً عشوائياً صغيراً ("تشتيت") لمنع تأثير القطيع حيث تعيد جميع الطلبات المؤجلة المحاولة في نفس الميلي ثانية بالضبط.

تحذير

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

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

500 Internal Server Error

خطأ غير متوقع في الخادم.

رموز الخطأ

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.	دقة الصورة أقل من الحد الأدنى المطلوب.
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.	قيمة معرّف غير صحيحة أو غير موجودة. يُطلق فقط عندما يتضمن التدفق لايفنس أو التحقق من الهوية - غير مطلوب لتدفقات التحقق من العمر فقط.
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 غير صالحة.
20062	The useCase field is invalid.	قيمة غير معروفة في حقل useCase.
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.
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 غير صحيح أو مستخدم بدون صلاحية لتنفيذ هذه العملية.
30017	Jwt header is an invalid JSON.	يحتوي رمز الوصول على أحرف غير صالحة.
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.	خطأ في المعالجة من جانب الخادم.

ما التالي

• للاستعلام عن عملية موجودة، انظر الحصول على العملية.