إنشاء عملية

MarkdownChatGPTClaude

هذه هي نقطة الدخول لكل عملية تكامل مع Unico API. يستدعيها الخادم الخلفي (back-end) الخاص بك لإنشاء عملية؛ ويستخدم الواجهة الأمامية (front-end) الرموز المُعادة لعرض iFrame، أو إعادة توجيه المستخدم، أو تهيئة SDK أصلي.

للتعرف على تدفق التكامل الكامل، راجع التدفقات.

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

البيئة	الرابط
الإنتاج	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

الطلب

Headers

Header	القيمة
Authorization	Bearer <access_token> (راجع المصادقة)
Content-Type	application/json

معاملات الطلب (Body)

متطلبات الحقول تعتمد على التدفق

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

الحقل	النوع	الوصف
callbackUri	string	عنوان URL الذي يُعاد توجيه المستخدم إليه بعد انتهاء الرحلة. استخدم / لتدفقات SDK الأصلي حيث يتم التعامل مع الاستدعاء داخل التطبيق.
flow	string	معرّف التدفق — يحدد الإمكانيات التي تعمل. أمثلة: idunicodocs، idunicosign، idchecktrust، idtoken، idsmart. راجع التدفقات المتاحة.
purpose	string	الغرض التجاري. القيم المقبولة: creditprocess، biometryonboarding، carpurchase، ageverification.
person.duiType	enum	نوع الوثيقة. راجع قيم duiType أدناه.
person.duiValue	string	رقم الوثيقة، بدون تنسيق.
person.friendlyName	string	اسم العرض للمستخدم الظاهر في واجهة الرحلة. الحد الأقصى 50 حرفًا.
person.phone	string	رقم الهاتف بصيغة رمز الدولة + رمز المنطقة + الرقم، بدون فواصل. مطلوب عند إرسال الإشعارات عبر SMS أو WhatsApp.
person.email	string	عنوان البريد الإلكتروني. مطلوب للتدفقات التي تتضمن التوقيع الإلكتروني.
person.​notifications	array	قنوات الإشعارات لإرسال رابط الرحلة. يحتوي كل عنصر على notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP، NOTIFICATION_CHANNEL_SMS، أو NOTIFICATION_CHANNEL_EMAIL.
references	array	مدخلات مرجعية لتدفقات التحقق 1:1 وإعادة التحقق الذكية. يحتوي كل عنصر على referenceType (‏REFERENCE_TYPE_IMAGE_BASE64 أو REFERENCE_TYPE_PROCESS_ID) وreferenceContent (صورة مُرمَّزة بـ base64 أو UUID للعملية). أرسل عنصرًا واحدًا كحد أقصى — تُرفض مصفوفة أطول برمز 400، ويجب ألا يكون referenceContent فارغًا.
useCase	string	سيناريو إعادة التحقق الذكية. مطلوب لـ 🇧🇷 idsmart، idsmart_r2، idsmart_tp1. أمثلة: USE_CASE_LOGIN، USE_CASE_FIN_TRANSACTIONS.
clientReference	string	معرّف فريد للمستخدم في نظامك. مطلوب لإمكانية حسابات متعددة. فريد في قاعدتك، بحد أقصى 256 حرفًا، بدون مسافات.
companyBranchId	string (UUID)	معرّف الفرع. مطلوب فقط إذا كان حساب الخدمة مرتبطًا بأكثر من فرع واحد.
expiresIn	string	نافذة صلاحية العملية من الإنشاء. الصيغة: "3600s". القيمة الافتراضية 7 أيام إذا لم تُحدَّد.
flowConfig	object	تجاوزات التهيئة الخاصة بكل تدفق.
flowConfig.​biometryCapture.​enabledBackCamera	boolean	استخدام الكاميرا الخلفية للجهاز. غير متوافق مع تدفقات التقاط الوثائق أو التوقيع الإلكتروني.
contextualization	object	سياق المعاملة المعروض للمستخدم خلال الرحلة لتوضيح الالتقاط. متاح للعملاء في أي منطقة — لا يقتصر على بلد معين.
contextualization.​company_name	string	اسم الشركة المعروض خلال الرحلة. الحد الأقصى 20 حرفًا.
contextualization.​currency	string	رمز العملة المعروض للمستخدم. القيم المقبولة: BRL، MXN، USD.
contextualization.​price	number	مبلغ المعاملة المعروض للمستخدم.
contextualization.​locale	object	النص المُترجَم المعروض خلال الرحلة. المفاتيح: ptBr، enUs، esMx — وهذه هي اللغات الوحيدة المدعومة للنص، بغض النظر عن منطقة العميل.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	سبب مختصر للالتقاط، يُعرض خلال الرحلة. الحد الأقصى 50 حرفًا.
contextualization.locale.{ptBr|enUs|esMx}.title	string	عنوان إشعار العميل المعروض خلال الرحلة. الحد الأقصى 100 حرف. يجب تقديمه مع text. تُحذف علامات HTML.
contextualization.locale.{ptBr|enUs|esMx}.text	string	نص إشعار العميل المعروض خلال الرحلة. الحد الأقصى 210 حرفًا. يجب تقديمه مع title. تُحذف علامات HTML.
imageBase64	string	الصورة الشخصية، مُرسَلة مباشرة. تقبل JWT الالتقاط الخاص بـ SDK.
document.purpose	enum	الغرض من الوثيقة. مفردات ثابتة: DOCUMENT_PURPOSE_ONBOARDING، DOCUMENT_PURPOSE_CREDIT_PROCESS، DOCUMENT_PURPOSE_CAR_PURCHASE، DOCUMENT_PURPOSE_PAY_BY_PAYCHECK، DOCUMENT_PURPOSE_FGTS. تُستخدم فقط مع تدفقات Face Document Match.
document.​files[].​data	bytes	التقاط وثيقة جديدة، مُرمَّز بـ base64. متاح عالميًا، وليس مقتصرًا على البرازيل. متعارض مع document.documentId.
document.documentId	string (UUID)	يعيد استخدام وثيقة تم التقاطها مسبقًا لنفس الشخص، بدلًا من التقاط جديد. متعارض مع document.files[].
expectedResult	object	يحاكي نتيجة إمكانية في بيئات الاختبار/sandbox ويضع علامة simulated: true على الاستجابة. راجع محاكاة النتائج (Test Mock).

قيم duiType

الدولة	القيمة	الوصف
AR	DUI_TYPE_AR_PASSPORT	جواز سفر أرجنتيني
AR	DUI_TYPE_AR_DNI	DNI الأرجنتيني
AR	DUI_TYPE_AR_LNC	رخصة القيادة الأرجنتينية (Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	الرقم الضريبي النمساوي (STNR)
BE	DUI_TYPE_BE_NN	الرقم الوطني البلجيكي (NN)
BR	DUI_TYPE_BR_CPF	CPF البرازيلي
BR	DUI_TYPE_BR_PASSPORT	جواز سفر برازيلي
BR	DUI_TYPE_BR_CNPJ	CNPJ البرازيلي
CA	DUI_TYPE_CA_SIN	SIN الكندي
CH	DUI_TYPE_CH_AHV	رقم AHV/AVS السويسري
CL	DUI_TYPE_CL_RUN	RUN التشيلي
CL	DUI_TYPE_CL_PASSPORT	جواز سفر تشيلي
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	رخصة القيادة التشيلية (Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	NIT الكولومبي
CO	DUI_TYPE_CO_PASSPORT	جواز سفر كولومبي
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	رخصة القيادة الكولومبية (Licencia de Conducción)
CO	DUI_TYPE_CO_CC	بطاقة المواطنة الكولومبية (Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	رقم التعريف الضريبي الألماني (IdNr)
DK	DUI_TYPE_DK_CPR	CPR الدنماركي
EC	DUI_TYPE_EC_NI	NI الإكوادوري
ES	DUI_TYPE_ES_NIE	رقم هوية الأجانب الإسباني (NIE)
ES	DUI_TYPE_ES_DNI	وثيقة الهوية الوطنية الإسبانية (DNI)
FI	DUI_TYPE_FI_HETU	رمز الهوية الشخصية الفنلندي (HETU)
FR	DUI_TYPE_FR_SPI	الرقم الضريبي المرجعي الفرنسي (SPI)
GB	DUI_TYPE_GB_NINO	رقم التأمين الوطني البريطاني (NINO)
GT	DUI_TYPE_GT_CUI	CUI الغواتيمالي
ID	DUI_TYPE_ID_NIK	NIK الإندونيسي
IE	DUI_TYPE_IE_PPSN	رقم الخدمة العامة الشخصي الأيرلندي (PPSN)
IT	DUI_TYPE_IT_CF	Codice Fiscale الإيطالي (CF)
LK	DUI_TYPE_LK_NIC	NIC سريلانكي
LU	DUI_TYPE_LU_MATRICULE	رقم الهوية الوطني اللوكسمبورغي (Matricule)
MX	DUI_TYPE_MX_CURP	CURP المكسيكي
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	RFC المكسيكي (شخص طبيعي)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	رخصة القيادة المكسيكية (Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	NIN النيجيري
NG	DUI_TYPE_NG_BVN	رقم التحقق المصرفي النيجيري (BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	رمز BVN النيجيري (مُجزّأ)
NG	DUI_TYPE_NG_NIN_TOKEN	رمز NIN النيجيري (مُجزّأ)
NL	DUI_TYPE_NL_BSN	رقم خدمة المواطن الهولندي (BSN)
NO	DUI_TYPE_NO_FNR	رقم الهوية الوطني النرويجي (Fødselsnummer)
PE	DUI_TYPE_PE_RUC	RUC البيروفي
PE	DUI_TYPE_PE_DNI	DNI البيروفي
PE	DUI_TYPE_PE_PASSPORT	جواز سفر بيروفي
PL	DUI_TYPE_PL_PESEL	PESEL البولندي
PT	DUI_TYPE_PT_NIF	رقم التعريف الضريبي البرتغالي (NIF)
SE	DUI_TYPE_SE_PNR	الرقم الشخصي السويدي (PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	الرقم التنسيقي السويدي (Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	رقم الهوية التركي (TCKN)
US	DUI_TYPE_US_SSN	SSN الأمريكي
US	DUI_TYPE_US_PASSPORT	جواز سفر أمريكي
US	DUI_TYPE_US_DRIVER_LICENSE	رخصة قيادة أمريكية
US	DUI_TYPE_US_PASSPORT_CARD	بطاقة جواز سفر أمريكية
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	جواز سفر أمريكي مصنوع من البولي كاربونات
US	DUI_TYPE_US_ID_CARD	بطاقة هوية أمريكية
UY	DUI_TYPE_UY_CI	CI الأوروغوياني
ZZ	DUI_TYPE_ZZ_EMAIL	عنوان البريد الإلكتروني
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	رقم الهاتف

إنشاء عملية بدون وثيقة

عندما يسمح التدفق بوثيقة اختيارية، يمكنك حذف person.duiType وperson.duiValue. بعد الالتقاط، تنتظر العملية في الحالة AWAITING_FOR_DOCUMENT حتى ترسل الواجهة الخلفية (back-end) الخاصة بك الوثيقة باستخدام تعيين وثيقة العملية.

مثال

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "idunicodocs_r2",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flow: 'idunicodocs_r2',
    purpose: 'biometryonboarding',
    clientReference: 'pedido-88216',
    callbackUri: 'https://your-app.example.com/onboarding/callback',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    },
  }),
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

الاستجابات

200 OK

{
  "process": {
    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "flow": "idunicodocs_r2",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDLIVE",
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDDOCS"
    ],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "companyData": {
      "branchId": "",
      "countryCode": "BRA"
    },
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
    "simulated": false
  }
}

الحقل	النوع	الوصف
process.id	string (UUID)	معرّف العملية. استخدمه لجلب النتيجة عبر الحصول على العملية.
process.state	enum	PROCESS_STATE_CREATED — تم إنشاء العملية، ولم تبدأ الرحلة بعد. PROCESS_STATE_FAILED — فشل إنشاء العملية.
process.result	enum	نتيجة التحقق. موجودة فقط عندما تكون state = PROCESS_STATE_FINISHED — راجع التدفقات لمعرفة قيم النتائج التي يمكن أن يُعيدها تدفق معيّن.
process.flow	string	معرّف التدفق المرسَل عند الإنشاء.
process.purpose	string	الغرض التجاري المرسَل عند الإنشاء.
process.callbackUri	string	عنوان URI لإعادة الاتصال المرسَل عند الإنشاء.
process.​clientReference	string	معرّفك الداخلي المرسَل عند الإنشاء. موجود فقط إذا قُدِّم في الطلب.
process.​companyBranchId	string (UUID)	معرّف الفرع. موجود فقط إذا قُدِّم في الطلب.
process.​userRedirectUrl	string	عنوان URL لإعادة توجيه المستخدم إليه (تكاملات Web Redirect وiFrame). لا تُعدّل هذا العنوان.
process.token	string	JWT لتهيئة Web SDK iFrame.
process.webAppToken	string	JWT لتهيئة SDKs الأصلية (Android وiOS وFlutter).
process.createdAt	string (date-time)	الطابع الزمني لوقت إنشاء العملية.
process.expiresAt	string (date-time)	الطابع الزمني الذي بعده تنتهي صلاحية العملية ولا يمكن إكمالها.
process.capacities	array	الإمكانيات المُهيّأة لهذه العملية.
process.​authenticationInfo	object	معلومات المصادقة للعملية (فارغة عند الإنشاء).
process.person	object	نسخة من كائن person المرسَل عند الإنشاء.
process.​companyData.​branchId	string (UUID)	معرّف الفرع المرتبط بالعملية.
process.​companyData.​countryCode	string	رمز الدولة المرتبط بالفرع (مثل BR، MX).

رموز الأخطاء

400 Bad Request

الرمز	الرسالة	الوصف
3	invalid flow	عندما لا يكون التدفق المحدد موجودًا.
3	invalid person: friendly name exceeds 50 characters.	عندما يتجاوز الاسم الودّي 50 حرفًا.
3	invalid purpose	عندما يكون الغرض المقدَّم غير صالح.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	عندما يكون callbackUri المقدَّم غير صالح.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	عندما يكون البريد الإلكتروني المقدَّم غير صالح ويكون إشعار البريد الإلكتروني مُهيَّأً.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	عندما يكون رقم الهاتف المقدَّم غير صالح ويكون إشعار SMS أو WhatsApp مُهيَّأً.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	عندما يكون المعرّف المقدَّم (duiValue) غير صالح.
3	invalid expiresIn argument	عندما تكون قيمة expiresIn غير صالحة.
3	invalid company_name argument in process contextualization, max length is 20	عندما يتجاوز contextualization.​company_name 20 حرفًا.
3	title and text must be provided together in process contexts	عندما يُقدَّم فقط أحد title أو text في لغة معيّنة.
3	invalid title argument in process contexts, max length is 100	عندما يتجاوز title الخاص بلغة معيّنة 100 حرف.
3	invalid text argument in process contexts, max length is 210	عندما يتجاوز text الخاص بلغة معيّنة 210 حرفًا.
3	invalid reason argument in process contexts, max length is 50	عندما يتجاوز reason الخاص بلغة معيّنة 50 حرفًا.
3	The references array must contain at most one element.	عندما يُرسَل أكثر من عنصر واحد في references.
3	The references[].referenceContent field is missing.	عندما يكون referenceContent فارغًا.
3	The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.	عندما لا يكون referenceType أحد القيم المدعومة.
3	A reference is required for this flow.	عندما يتطلب التدفق مرجعًا ولم يُرسَل أي مرجع. أرسل references[0] مع referenceType بقيمة PROCESS_ID أو IMAGE_BASE64.
9	The referenceProcessId field is invalid.	عندما لا تكون العملية المرجعية موجودة أو لا يمكن إعادة استخدامها. يذكر الحقل الذي أرسلته — bioTokenId إذا كان هذا هو الحقل الذي أرسلته.
3	INVALID_IMAGE	عندما تكون الصورة بصيغة base64 غير صالحة، أو تبدو كمحاولة حقن.
3	INVALID_DUI	عندما يكون رقم الوثيقة غير قياسي أو غير موجود.
3	IMAGE_TOO_LARGE	عندما تتجاوز الصورة الحد الأقصى للحجم البالغ 800 كيلوبايت.
3	UNSUPPORTED_IMAGE_FORMAT	عندما لا تكون صيغة الصورة PNG أو JPEG أو WebP.
3	MISSING_IMAGE	عندما تكون الصورة مطلوبة لهذا التدفق ولم تُرسَل.
3	MISSING_NAME	عندما يكون الاسم مطلوبًا لهذا التدفق ولم يُرسَل.
3	MISSING_DUI	عندما يكون رقم الوثيقة مطلوبًا لهذا التدفق ولم يُرسَل.
3	MISSING_PERSON	عندما يكون كائن person مطلوبًا لهذا التدفق ولم يُرسَل.
3	INVALID_REQUEST	عندما يكون نص الطلب فارغًا (null) أو لا يمكن تفسيره.
3	TOKEN_ALREADY_USED	عندما يكون رمز الالتقاط قد استُخدم من قبل. فهو للاستخدام مرة واحدة.
3	TOKEN_EXPIRED	عندما تنتهي صلاحية رمز الالتقاط. يجب استخدامه في غضون 10 دقائق.
3	INVALID_BUNDLE	عندما لا يستوفي الطلب متطلبات الأمان.
3	INVALID_NAME	عندما يكون الاسم أطول من الحد الأقصى المسموح به.
3	INVALID_EMAIL	عندما يكون عنوان البريد الإلكتروني مشوّهًا أو طويلًا جدًا.
3	INVALID_PHONE	عندما يكون رقم الهاتف أطول من 20 حرفًا.
3	INVALID_DUI_TYPE	عندما لا يكون نوع الوثيقة أحد القيم المدعومة.
3	INVALID_CLIENT_REFERENCE	عندما يكون clientReference طويلًا جدًا، أو يحتوي على مسافة أو #.
3	INVALID_CONSENT_TYPE	عندما لا تكون consentType هي NONE أو DIRECT أو INDIRECT.
3	INVALID_USE_CASE	عندما لا يكون useCase معروفًا، أو يكون طويلًا جدًا.
3	INVALID_DEVICE_TRUST_TOKEN	عندما يكون رمز device-trust غير صالح أو تم استخدامه من قبل.
3	TOO_MANY_REFERENCES	عندما يُرسَل أكثر من عنصر واحد في references.
3	INVALID_REFERENCE_TYPE	عندما لا يكون referenceType هو IMAGE_BASE64 أو PROCESS_ID.
3	INVALID_REFERENCE_PROCESS	عندما لا يكون معرّف العملية المرجعية معرّفًا صالحًا.
3	REFERENCE_PROCESS_NOT_FOUND	عندما لا تكون العملية المُشار إليها موجودة.
3	REFERENCE_PROCESS_NOT_READY	عندما لا تحتوي العملية المُشار إليها على نتيجة قابلة لإعادة الاستخدام، أو تم استخدامها من قبل.
3	REFERENCE_SELFIE_NOT_FOUND	عندما لا تحمل العملية المُشار إليها صورة شخصية لإعادة استخدامها.
3	INVALID_CAPTURE_TOKEN	عندما لا تكون الصورة المُلتقَطة رمزًا صالحًا نتج عن SDK التقاط.
3	INVALID_CAPTURE_SIGNATURE	عندما لا يتحقق توقيع رمز الالتقاط.
3	PRIOR_CAPTURE_NOT_FOUND	عندما لا يمكن تحديد الالتقاط السابق الذي يبني عليه هذا الطلب. أعد بدء العملية.
3	PRIOR_CAPTURE_IN_PROGRESS	عندما لا يكون الالتقاط السابق قد انتهى بعد. أعد المحاولة بعد قليل.
3	PRIOR_CAPTURE_FAILED	عندما لا يمكن إكمال الالتقاط السابق. أعد بدء العملية.
3	INVALID_DOCUMENT	عندما يكون ملف الوثيقة غير قابل للقراءة، أو محميًا بكلمة مرور، أو بصيغة غير مدعومة.
3	INVALID_AUTH_PROCESS	عندما يكون document.authProcessId غير صالح، أو منتهي الصلاحية، أو يخص شخصًا آخر.
3	INVALID_DOCUMENT_PURPOSE	عندما لا يكون document.purpose أحد القيم المدعومة.
3	PROCESS_REUSE_NOT_ENABLED	عندما لا يسمح التدفق بإعادة استخدام عملية سابقة بدون صورة. أرسل صورة بدلًا من ذلك.
9	PROCESS_FAILED	عندما تصل العملية إلى فشل نهائي خلال الإنشاء.
9	Tenant API key is not configured	عندما لا يكون مفتاح API مُهيَّأً بشكل صحيح.

401 Unauthorized

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

الرسالة	الوصف
Jwt header is an invalid JSON	عندما يحتوي رمز الوصول المستخدَم على أحرف غير صحيحة.
Jwt is expired	عندما تنتهي صلاحية رمز الوصول المستخدَم.

403 Forbidden

الرمز	الرسالة	الوصف
7	INVALID_API_KEY	عندما يكون مفتاح API غير صالح أو مفقودًا.
7	INVALID_AUTH_TOKEN	عندما يكون رمز المصادقة غير صالح.
7	PERMISSION_DENIED	عندما تكون بيانات الاعتماد صالحة ولكن غير مخوَّلة لهذا الإجراء.
7	TOKEN_TENANT_MISMATCH	عندما يكون رمز الالتقاط قد صدر لمستأجر مختلف.
7	MISSING_ACCESS_TOKEN	عندما يكون رأس التفويض (authorization header) مفقودًا.

404 Not Found

الرمز	الرسالة	الوصف
5	NO_RESULTS_FOUND	عندما لا يمكن العثور على وثيقة أشار إليها الطلب.

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

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

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

• بعد أن ينهي المستخدم الرحلة، استدعِ الحصول على العملية لجلب النتيجة، أو انتظر webhook.
• لعرض جميع تركيبات الوصفات وقيم نتائجها الممكنة، راجع التدفقات.
• لاختبار نتيجة بدون التقاط بيومتري حقيقي، راجع محاكاة النتائج (Test Mock).