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

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

نقطة النهاية

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

الطلب

الترويسات

الترويسة	القيمة
`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.id.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.id.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` لإعادة استخدام المستند.

403 Forbidden

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

429 Too Many Requests

تم الوصول إلى حد معدل الطلبات. أعد المحاولة بعد الفترة الزمنية المحددة في رأس الاستجابة Retry-After. راجع حدود معدل الطلبات.

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

بمجرد حصولك على documentId، مرره في طلب عملية المستند لتخطي الالتقاط:

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

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

للاطلاع على مخطط طلب عملية المستند الكامل، راجع إنشاء عملية مستند.

رموز الخطأ

400 Bad Request
403 Forbidden
404 Not Found
500 Internal Server Error

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

الرمز	الرسالة	الوصف
`30017`	Jwt header is an invalid JSON.	رمز الوصول يحتوي على أحرف غير صالحة.
`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 لإعادة الاستخدام​

رموز الخطأ​