تعيين وثيقة العمليةPOST

أنشئ عملية بدون وثيقة، ودع المستخدم يُكمل الالتقاط، ثم أرسل الوثيقة من الواجهة الخلفية (back-end) الخاصة بك. تنتهي العملية بعد ذلك.

MarkdownChatGPTClaude

دورة الحياة

1. الواجهة الخلفية (back-end) الخاصة بك تُنشئ العملية باستخدام إنشاء عملية، بدون person.duiType وperson.duiValue. يجب أن يسمح التدفق بوثيقة اختيارية. تبدأ العملية بالحالة PROCESS_STATE_CREATED.
2. المستخدم يُجري الرحلة ويُنفّذ الالتقاط.
3. Unico API تنقل العملية إلى AWAITING_FOR_DOCUMENT، وهي الحالة التي تُعيدها الحصول على العملية بينما تنتظر العملية الوثيقة. يمكنك بالفعل قراءة النتائج الجزئية للإمكانيات التي لا تعتمد على duiValue.
4. الواجهة الخلفية (back-end) الخاصة بك تستدعي هذه النقطة النهائية مع معرّف العملية في عنوان URL والوثيقة في متن الطلب. ثم تُنهي Unico API العملية، وتنتقل إلى PROCESS_STATE_FINISHED.

الاستجابة لا تحمل النتيجة النهائية

اقرأ الحالة والنتيجة النهائيتين باستخدام الحصول على العملية، أو انتظر webhook.

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

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

الطلب

Headers

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

تحتاج بيانات الاعتماد إلى الصلاحية نفسها المستخدَمة لاستدعاء إنشاء عملية.

معاملات المسار

المعامل	النوع	مطلوب	الوصف
processId	string (UUID)	نعم	معرّف العملية الذي أعادته إنشاء عملية.

معاملات المتن

الحقل	النوع	مطلوب	الوصف
duiType	enum	نعم	نوع الوثيقة. تُرفض القيمة DUI_TYPE_UNSPECIFIED. راجع قيم duiType أدناه.
duiValue	string	نعم	رقم الوثيقة، بدون تنسيق. حتى 320 حرفًا.

قيم 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	رقم الهاتف

متى يُقبل الاستدعاء

• العملية في الحالة AWAITING_FOR_DOCUMENT: أكمل المستخدم الالتقاط بالفعل.
• لم تنتهِ صلاحية العملية.
• يسمح التدفق بوثيقة اختيارية.

الوثيقة غير قابلة للتغيير. يفشل الاستدعاء الثاني، لأن العملية لم تعد في انتظار وثيقة.

مثال

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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/${processId}/document`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    }),
  }
);
const { processId: id, duiType, duiValue } = await res.json();

الاستجابات

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

الحقل	النوع	الوصف
processId	string (UUID)	معرّف العملية.
duiType	enum	نوع الوثيقة المسجّل للعملية.
duiValue	string	رقم الوثيقة المسجّل للعملية.

قيم المثال هي قيم توضيحية.

رموز الأخطاء

400 Bad Request

الرمز	الوصف
3	processId مفقود أو غير صالح، أو duiType غير محدد، أو duiValue فارغ أو أطول من 320 حرفًا.
9	العملية ليست في انتظار وثيقة (ويشمل ذلك وثيقة تم تعيينها مسبقًا)، أو انتهت صلاحيتها أو انتهت، أو أن التدفق لا يسمح بوثيقة اختيارية.

401 Unauthorized

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

403 Forbidden

الرمز	الوصف
7	تفتقر بيانات الاعتماد إلى الصلاحية التي تتطلبها إنشاء عملية.

404 Not Found

الرمز	الوصف
5	العملية غير موجودة، أو لا تنتمي إلى شركتك.

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

الرمز	الوصف
13	تعذّر حفظ الوثيقة.

ملاحظة

تُسجَّل الوثيقة لدى خدمة الهوية قبل تخزينها. إذا فشل هذا التسجيل، يُعيد الاستدعاء حالة ذلك الفشل.

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

• لقراءة الحالة والنتيجة النهائيتين، راجع الحصول على العملية.
• لتلقّي إشعار عند انتهاء العملية، راجع Webhooks and Events.