تعيين مستند العملية

يُعيّن مستند التعريف (CPF، CURP، SSN أو أي duiType آخر) على عملية تم إنشاؤها بدون مستند. بمجرد التعيين، يصبح المستند غير قابل للتغيير.

متاح فقط للعمليات التي يسمح تدفقها المخصص بالإنشاء بدون مستند - أي العمليات في حالة AWAITING_FOR_DOCUMENT.

نقطة النهاية

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

الطلب

الترويسات

الترويسة	القيمة
Authorization	Bearer <access_token> (انظر المصادقة)
Content-Type	application/json

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

الحقل	النوع	مطلوب	الوصف
processId	string	نعم	معرّف العملية الذي تم إرجاعه في process.id عند الإنشاء.

معاملات الجسم

الحقل	النوع	مطلوب	الوصف
duiType	enum	نعم	نوع المستند. القيم: DUI_TYPE_BR_CPF، DUI_TYPE_MX_CURP، DUI_TYPE_US_SSN. تدعم نقطة النهاية هذه مجموعة فرعية من أنواع المستندات المقبولة بواسطة إنشاء عملية - التدفقات المخصصة التي تسمح بإنشاء مستند اختياري يتم التحقق منها حالياً مقابل هذه القائمة الأضيق.
duiValue	string	نعم	رقم المستند، بدون تنسيق. الحد الأقصى 320 حرفاً (يستوعب المعرّفات المشفرة أو المركبة؛ أرقام المستندات القياسية مثل CPF أو CURP أقصر بكثير).

مثال

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/abc-123/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678901"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  'https://api.idcloud.unico.app/client/v1/process/abc-123/document',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678901',
    }),
  }
);

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

الاستجابات

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

الحقل	النوع	الوصف
process.id	string	معرّف العملية.
process.person.duiType	string	نوع المستند المعيّن على العملية.
process.person.duiValue	string	قيمة المستند المعيّنة على العملية.

400 Bad Request

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

401 Unauthorized

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

404 Not Found

العملية غير موجودة.

429 Too Many Requests

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

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

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

تحذير

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

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

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
3	process id is invalid	عندما يكون معرّف العملية غير صالح.
3	dui_type is required	عندما لا يتم تقديم نوع المستند.
3	dui_value is required	عندما لا يتم تقديم رقم المستند.
3	dui_value exceeds maximum length	عندما يتجاوز رقم المستند الحد الأقصى للأحرف.
9	process is not awaiting for document	عندما لا تقبل العملية المحددة تقديم المستند.
9	process expired	عندما تكون العملية المحددة قد انتهت صلاحيتها.
9	document already set, cannot be modified	عندما تكون العملية لديها بالفعل مستند مرتبط.
9	process already finished	عندما تكون العملية قد اكتملت بالفعل.
9	flow does not allow optional document	عندما يكون المستند إلزامياً للتدفق الذي تنفذه العملية.

401 Unauthorized

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

404 Not Found

الرمز	الرسالة	الوصف
5	error getting process: rpc error: code = NotFound desc = process not found	عندما لا يتم العثور على معرّف العملية.

429 Too Many Requests

لا يتم توفير رمز خطأ مفصل لهذه الحالة — حالة HTTP فقط. انظر قسم 429 Too Many Requests أعلاه لأفضل الممارسات.

500 Internal Server Error

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

ما التالي

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