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

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

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

نقطة النهاية

البيئة	عنوان URL
الإنتاج	POST https://api.idcloud.unico.app/client/v1/process/{processId}/document
بيئة الاختبار	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 فقط.

رموز الخطأ

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 فقط.

500 Internal Server Error

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

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

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