إنشاء عملية

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

• التأهيل - يتحقق من هوية المستخدم عن طريق مقارنة وجهه مع قاعدة هويات Unico (مطلوب subject.duiType + subject.code).
• المعاملات - يتحقق من أنه نفس الشخص من عملية سابقة عن طريق مقارنة وجه بوجه (مطلوب referenceProcessId أو مصفوفة references مع صورة سيلفي / معرّف عملية).
• Cardholder Verification - يؤكد أن البطاقة تخص حاملها المُعلَن، دون أي التقاط لصورة سيلفي (مطلوب subject.code + card). يمكن اختيارياً إعادة استخدام عملية تم التحقق منها مسبقاً عبر referenceProcessId لتشغيل بوابة إعادة الاستخدام؛ بدونها، تُعيد الاستجابة تلقائياً النتيجة unsure. انظر إمكانية Cardholder Verification.

يتم تحديد المنتج النشط بواسطة 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.
subject.clientReference	string	مشروط	المعرّف الفريد للمستخدم في نظامك. مطلوب لقدرة حسابات متعددة. فريد في قاعدتك، بحد أقصى 256 حرفاً وبدون مسافات.
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.

Cardholder Verification

الحقل	النوع	مطلوب	الوصف
subject.duiType	integer	نعم	معرّف نوع الوثيقة. انظر قيم duiType أدناه. حالياً DUI_TYPE_BR_CPF فقط.
subject.code	string	نعم	CPF حامل البطاقة الجاري التحقق منه. بدون نقاط أو شرطات.
card.bin	string	مشروط	أول 6 أو 8 أرقام من البطاقة (BIN). مطلوب مع card.last4.
card.last4	string	مشروط	آخر 4 أرقام من البطاقة. مطلوب مع card.bin.
card.name	string	لا	اسم حامل البطاقة كما هو مطبوع عليها.
referenceProcessId	string (UUID)	لا	معرّف عملية تم التحقق منها مسبقاً لإعادة استخدامها — عملية بها نتيجة معتمدة للتحقق من الهوية أو لايفنس لنفس CPF. النسخة الحالية من هذه القدرة تعتمد على إعادة الاستخدام: بدون هذا الحقل، لا يتم تشغيل البوابة أبداً وتُعيد الاستجابة تلقائياً النتيجة القياسية unsure — ولا يفشل الطلب نفسه أبداً.
useCase	string	لا	سياق العملية، مثلاً CardholderVerification.
subsidiaryId	string	لا	معرف الفرع — مطلوب فقط إذا كانت هناك فروع متعددة.

معلومة

لا يتم إرسال imageBase64 لهذا المنتج — يعمل Cardholder Verification بالكامل على الخادم (back-end)، دون أي خطوة لالتقاط صورة سيلفي.

قيم duiType

الدولة	الرمز	الوصف
BR	1	CPF البرازيلي
MX	2	CURP المكسيكي
US	4	SSN الأمريكي
BR	5	جواز سفر برازيلي
AR	6	جواز سفر أرجنتيني
AR	7	DNI الأرجنتيني
NG	8	NIN النيجيري
CL	9	RUN التشيلي
EC	10	NI الإكوادوري
US	11	جواز سفر أمريكي
GT	12	CUI الغواتيمالي
UY	13	CI الأوروغوياني
BR	14	CNPJ البرازيلي
ZZ	15	عنوان البريد الإلكتروني
ID	16	NIK الإندونيسي
ZZ	17	رقم الهاتف
US	18	رخصة قيادة أمريكية
NG	20	رقم التحقق المصرفي النيجيري (BVN)
US	21	بطاقة جواز سفر أمريكية
US	22	جواز سفر أمريكي مصنوع من البولي كاربونات
US	23	بطاقة هوية أمريكية
TR	24	رقم الهوية التركي (TCKN)
MX	25	RFC المكسيكي (شخص طبيعي)
CO	26	NIT الكولومبي
PE	27	RUC البيروفي
CA	28	SIN الكندي
DK	29	CPR الدنماركي
GB	30	رقم التأمين الوطني البريطاني (NINO)
PL	31	PESEL البولندي
SE	32	الرقم الشخصي السويدي (PNR)
CH	33	رقم AHV/AVS السويسري
AT	34	الرقم الضريبي النمساوي (STNR)
FI	35	رمز الهوية الشخصية الفنلندي (HETU)
BE	36	الرقم الوطني البلجيكي (NN)
IT	37	Codice Fiscale الإيطالي (CF)
SE	38	الرقم التنسيقي السويدي (Samordningsnummer)
NO	39	رقم الهوية الوطني النرويجي (Fødselsnummer)
PE	40	DNI البيروفي
DE	41	رقم التعريف الضريبي الألماني (IdNr)
NL	42	رقم خدمة المواطن الهولندي (BSN)
NG	43	رمز BVN النيجيري (مُجزّأ)
NG	44	رمز NIN النيجيري (مُجزّأ)
PT	45	رقم التعريف الضريبي البرتغالي (NIF)
FR	46	الرقم الضريبي المرجعي الفرنسي (SPI)
IE	47	رقم الخدمة العامة الشخصي الأيرلندي (PPSN)
LU	48	رقم الهوية الوطني اللوكسمبورغي (Matricule)
AR	49	رخصة القيادة الأرجنتينية (Licencia Nacional de Conducir)
ES	50	رقم هوية الأجانب الإسباني (NIE)
ES	51	وثيقة الهوية الوطنية الإسبانية (DNI)
CL	52	جواز سفر تشيلي
CO	53	جواز سفر كولومبي
PE	54	جواز سفر بيروفي
CO	55	رخصة القيادة الكولومبية (Licencia de Conducción)
CO	56	بطاقة المواطنة الكولومبية (Cédula de Ciudadanía)
CL	57	رخصة القيادة التشيلية (Licencia de Conducir)
MX	58	رخصة القيادة المكسيكية (Licencia de Conducir)
—	0	غير محدد
—	3	معرّف Unico الداخلي

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

• الدقة الدنيا: 640 × 480 (معيار HD)
• الحجم الأقصى للملف: 800 KB (يُنصح بضغط 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": {
      "duiType": 1,
      "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: {
      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

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..."
  }'

المعاملات - 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({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification - 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": {
      "duiType": 1,
      "code": "12345678909"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification - 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: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

الاستجابات

التأهيل

200 OK

التعاقد فريد — يحمل الحقل idCloud.result الحكم الموحّد للإمكانيات المستخدمة.

توحّد Unico نتائج الإمكانيات المنفّذة في idCloud.result واحد، جاهز لتحديد الخطوة التالية في تدفقك — دون الحاجة إلى تنسيق النتائج الفردية.

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

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية. استخدمه مع الحصول على العملية لإعادة الاستعلام.
status	integer	1 (قيد المعالجة)، 3 (انتهت بنجاح)، 5 (خطأ).

قيم النتيجة المحتملة

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

تعتمد القيم المُرجعة على الوصفة المكوّنة في APIKey الخاص بك. انظر التدفقات لمعرفة قيم النتيجة التي يمكن أن ترجعها كل وصفة.

قد يتلقى العملاء في البرازيل الاستجابة حسب الإمكانية

يظل الهيكل العام للاستجابة كما هو — النتيجة الواحدة هي الافتراضية.

قد تتلقى عمليات التكامل في البرازيل النتائج المفتوحة لكل إمكانية على حدة. تضيف كل إمكانية مفعّلة في APIKey كتلتها الخاصة إلى الاستجابة — يتم حذف الحقول الخاصة بالإمكانيات غير المفعّلة.

{
  "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 لتفعيل الإمكانيات أو تعديلها.

الحقل	النوع	الوصف
unicoId.result	string	yes، no، inconclusive - انظر التحقق من الهوية.
riskLevel.result	string	approved، reproved، risk-critical، risk-high، inconclusive — انظر القيم المحتملة أدناه أو تصنيف مخاطر الاحتيال.
idFace.result	string	FOUND — انظر معرّف الوجه.
idFace.personId	string	معرّف مستقر وغير شفاف للوجه، يُعاد جنبًا إلى جنب مع idFace.result = FOUND. عندما يتعذّر التعرف على أي وجه في الصورة، يفشل الطلب بالخطأ 20532 بدلاً من إعادة كتلة idFace.
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

التعاقد فريد — يحمل الحقل idCloud.result الحكم الموحّد للإمكانيات المستخدمة.

توحّد Unico نتائج الإمكانيات المنفّذة في idCloud.result واحد، جاهز لتحديد الخطوة التالية في تدفقك — دون الحاجة إلى تنسيق النتائج الفردية.

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

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية.
status	integer	3 (انتهت بنجاح)، 5 (خطأ). لجميع القيم الممكنة، انظر الحصول على العملية.

قيم النتيجة المحتملة

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

تعتمد القيم المُرجعة على الوصفة المكوّنة في APIKey الخاص بك. انظر التدفقات لمعرفة قيم النتيجة التي يمكن أن ترجعها كل وصفة.

قد يتلقى العملاء في البرازيل الاستجابة حسب الإمكانية

يظل الهيكل العام للاستجابة كما هو — النتيجة الواحدة هي الافتراضية.

قد تتلقى عمليات التكامل في البرازيل النتائج المفتوحة لكل إمكانية على حدة. تضيف كل إمكانية مفعّلة في APIKey كتلتها الخاصة إلى الاستجابة — يتم حذف الحقول الخاصة بالإمكانيات غير المفعّلة.

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

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

Cardholder Verification

200 OK

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

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية.
status	integer	1 (قيد المعالجة)، 3 (انتهت بنجاح)، 5 (خطأ). لجميع القيم، انظر الحصول على العملية.
cardholderVerification.result	string	approved — تنتمي CPF والبطاقة إلى نفس الشخص. unsure — إما أن بوابة إعادة الاستخدام لم تُستوفَ، أو أن التحقق نفسه كان غير قاطع. غائب أثناء عدم بلوغ status قيمة 3 بعد. انظر Cardholder Verification.

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	تم رفض تدفق إعادة الاستخدام (referenceProcessId/bioTokenId، بدون صورة) لأن إعادة استخدام العملية غير مفعّلة لهذا مفتاح API.
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.	دقة الصورة المرفوعة منخفضة جداً.
20532	No face detected in image.	تعذّر اكتشاف أي وجه في الصورة المرسلة.
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 كبديل. لا ينطبق على Cardholder Verification — لا يتم أبداً التحقق من referenceProcessId فيها كحقل مطلوب؛ بوابة إعادة استخدام غير مستوفاة تُجيب بـ unsure عوضاً عن ذلك.
20533	The card field is missing.	Cardholder Verification: لم يتم تقديم كائن card.
20534	The card.bin field is missing.	Cardholder Verification: لم يتم تقديم card.bin.
20535	The card.last4 field is missing.	Cardholder Verification: لم يتم تقديم card.last4.
20536	The card data is invalid.	Cardholder Verification: تم رفض بيانات البطاقة باعتبارها غير صالحة.
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.

403 Forbidden

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

الرمز	الرسالة	الوصف
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 المقدم موجود بالفعل لهذا المستأجر.

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

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

ما التالي

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