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

للاطلاع على تدفق التكامل الكامل، راجع نظرة عامة على 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 كيلوبايت (يُوصى بضغط 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

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

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

الخطوات التالية

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