الحصول على الوثائق القابلة لإعادة الاستخدام
استخدم هذه النقطة النهائية للتحقق مما إذا كان المستخدم يمتلك بالفعل وثيقة متاحة لإعادة الاستخدام قبل بدء تدفق التقاط وثيقة (Document) جديد. إذا تم العثور على وثيقة، يمكن تمرير documentId الخاص بها مباشرة إلى POST /processes/v1 (من نوع Document) لتخطي خطوة الالتقاط.
النقطة النهائية
| البيئة | الرابط |
|---|---|
| الإنتاج | GET https://api.idcloud.unico.app/documents/v1 |
| Sandbox | GET https://api.idcloud.uat.unico.app/documents/v1 |
الطلب
| 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
الاستجابات
{
"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. | لم يتم العثور على وثيقة للمعاملات المقدَّمة. |
تم الوصول إلى حد المعدل. عندما يتلقى نظامك خطأ HTTP 429، يجب عليك تطبيق آليات لمنع حالات الفشل المتتالية وتجنب تفاقم القيود.
أفضل الممارسات:
- فترة التهدئة (backoff): أوقف أو قلل الطلبات اللاحقة من نظامك فورًا. لا تعد محاولة الطلبات الفاشلة باستمرار في حلقة متكررة سريعة.
- الطابور والتحكم بمعدل الإرسال (Queueing & throttling): قم بتخزين الطلبات الصادرة مؤقتًا أو وضعها في طابور من جانبك للتحكم في تدفق حركة المرور قبل إعادة إرسالها.
- التراجع الأسي مع التذبذب العشوائي (Exponential backoff with jitter): عند إعادة المحاولة، قم بزيادة وقت الانتظار بشكل أسي بين المحاولات (مثال: 1 ثانية، 2 ثانية، 4 ثوانٍ، 8 ثوانٍ) وأضف تأخيرًا عشوائيًا صغيرًا ("jitter") لمنع تأثير القطيع حيث تعيد جميع الطلبات المنتظرة المحاولة في نفس الميلي ثانية بالضبط.
الاستمرار في إرسال الطلبات إلى نقطة نهاية محدودة المعدل دون تراجع يمكن أن يُطيل فترة التقييد ويؤثر بشكل كبير على معدل النقل التشغيلي لنظامك. التحكم السليم في معدل الطلبات من جانبك يضمن تكاملاً أكثر سلاسة ومرونة.
للاطلاع على الحدود الافتراضية وزيادة الطلبات والتفاصيل الإضافية، راجع حدود المعدل.
| الرمز | الرسالة | الوصف |
|---|---|---|
99999 | Internal failure! Try again later. | خطأ في المعالجة من جانب الخادم. |