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

استخدم نقطة النهاية هذه للتحقق مما إذا كان لدى المستخدم مستند متاح لإعادة الاستخدام قبل بدء تدفق التقاط مستند جديد. إذا تم العثور على مستند، يمكن تمرير 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

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

Node.js

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 لإعادة استخدام المستند.

استخدام 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

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

403 Forbidden

رمز 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 مفقود أو غير موجود.

404 Not Found

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

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

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