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

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

نقطة النهاية

البيئة	الرابط
الإنتاج	`GET https://api.id.unico.app/documents/v1`
Sandbox	`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

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

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

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

تحذير

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

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

استخدام 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.	ترويسة رمز المصادقة مفقودة.

الرمز	الرسالة	الوصف
`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 لإعادة الاستخدام​

رموز الخطأ​