الحصول على الوثائق القابلة لإعادة الاستخدام

Markdown ChatGPT Claude

استخدم هذه النقطة النهائية للتحقق مما إذا كان المستخدم يمتلك بالفعل وثيقة متاحة لإعادة الاستخدام قبل بدء تدفق التقاط وثيقة (Document) جديد. إذا تم العثور على وثيقة، يمكن تمرير documentId الخاص بها مباشرة إلى POST /processes/v1 (من نوع Document) لتخطي خطوة الالتقاط.

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

البيئة	الرابط
الإنتاج	`GET https://api.idcloud.unico.app/documents/v1`
Sandbox	`GET https://api.idcloud.uat.unico.app/documents/v1`

الطلب

Headers

Header	القيمة
`Authorization`	`Bearer <access_token>` (راجع المصادقة)
`APIKEY`	مفتاح API مُهيّأ مع تفعيل التقاط الوثائق وإعادة الاستخدام.

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

المعامل	النوع	مطلوب	الوصف
`code`	string	نعم	معرّف المستخدم (CPF أو CURP، بدون تنسيق).
`type`	string	نعم	نوع الوثيقة المطلوب الاستعلام عنها. القيم المقبولة: `BR_RG`، `BR_CNH`، `BR_CIN`، `BR_PASSPORT`.

ملاحظة

القيم الخاصة بـ type أعلاه مخصصة لهذه النقطة النهائية فقط. لا تخلط بينها وبين:

subject.duiType في طلبات POST — يستخدم البادئة DUI_TYPE_* ويحدد الشخص، وليس نوع الوثيقة (مثال: DUI_TYPE_BR_CPF).
documentType في الاستجابة — يستخدم مسار السجل الكامل (مثال: unico.moja.dictionary.br.cnh.v2.Cnh).

مثال

cURL
Node.js

curl -X GET "https://api.idcloud.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.idcloud.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

الاستجابات

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

الحقل	النوع	الوصف
`items`	array	قائمة الوثائق القابلة لإعادة الاستخدام التي تم العثور عليها للمستخدم. مصفوفة فارغة إذا لم يتم العثور على وثيقة قابلة لإعادة الاستخدام للـ `code` و`type` المحددين.
`items[].documentType`	string	معرّف نوع الوثيقة. القيم الممكنة: `unico.moja.dictionary.br.rg.v2.Rg`، `unico.moja.dictionary.br.cnh.v2.Cnh`، `unico.moja.dictionary.br.cin.v1.Cin`، `unico.moja.dictionary.br.passaporte.v1.Passaporte`.
`items[].documentId`	string	معرّف الوثيقة. مرّر هذه القيمة في `document.documentId` عند استدعاء `POST /processes/v1` لإعادة استخدام الوثيقة.

استخدام documentId لإعادة الاستخدام

بعد الحصول على documentId، مرّره في طلب عملية Document لتخطي الالتقاط:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

الحقل	الوصف
`document.purpose`	الغرض التجاري لعملية الوثيقة هذه. القيم المقبولة: `creditprocess`، `carpurchase`، `paybypaycheck`، `onboarding`، `fgts`. هذه القيم خاصة بـ Document API وتختلف عن تعداد `purpose` في SDK البيومتري.
`document.authProcessId`	معرّف العملية البيومترية التي تم إنشاؤها مسبقًا لهذا المستخدم (من `POST /processes/v1`).
`document.documentId`	معرّف الوثيقة الذي تم الحصول عليه من استجابة هذه النقطة النهائية. عند تقديمه، يمكن حذف `document.files` — تسترجع المنصة الوثيقة التي تم التقاطها مسبقًا تلقائيًا.

رموز الأخطاء

400 Bad Request
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error

الرمز	الرسالة	الوصف
`20507`	O parâmetro subject.code é inválido.	قيمة معرّف مشوّهة أو غير موجودة (CPF أو CURP).
`20002`	O parâmetro APIKey não foi informado.	Header الخاص بـ APIKEY مفقود.
`20001`	O parâmetro authtoken não foi informado.	Header الخاص برمز المصادقة مفقود.

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

الرمز	الرسالة	الوصف
`30020`	The provided authorization token does not have permission to perform this action.	لا يملك الرمز الإذن للوصول إلى صورة الوثيقة الشخصية.
`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 مفقود أو غير موجود.

الرمز	الرسالة	الوصف
`99987`	Attachment not found.	لم يتم العثور على المرفق المرتبط بالوثيقة.
`50001`	The process is not found.	لم يتم العثور على وثيقة للمعاملات المقدَّمة.

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

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

الطلب​

مثال​

الاستجابات​

استخدام documentId لإعادة الاستخدام​

رموز الأخطاء​