---
title: الحصول على المستندات القابلة لإعادة الاستخدام
description: تحقق مما إذا كان لدى المستخدم مستند قابل لإعادة الاستخدام مسجل بالفعل قبل بدء تدفق التقاط جديد.
canonical: https://developer.unico.io/ar/dual-api/developers/api-reference/api/get-document
locale: ar
generated_by: markdown-export
---

استخدم نقطة النهاية هذه للتحقق مما إذا كان لدى المستخدم مستند متاح لإعادة الاستخدام قبل بدء تدفق التقاط مستند جديد. إذا تم العثور على مستند، يمكن تمرير `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>` (انظر [المصادقة](../authentication))|
| `APIKEY` | مفتاح API المخصص مع تفعيل التقاط الوثائق وإعادة الاستخدام. |

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

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

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

### مثال

### cURL

```bash
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

```javascript
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

```json
{
  "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`، مرره في طلب عملية المستند لتخطي الالتقاط:

```json
{
  "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` - تقوم المنصة باسترداد المستند الذي تم التقاطه مسبقاً تلقائياً. |

للاطلاع على مخطط طلب عملية المستند الكامل، انظر [إنشاء عملية مستند](./post-processes-document).

### رموز الخطأ

### 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 ث) وأضف تأخيراً عشوائياً صغيراً ("تشتيت") لمنع تأثير القطيع حيث تعيد جميع الطلبات المؤجلة المحاولة في نفس الميلي ثانية بالضبط.

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

للحدود الافتراضية وزيادة الطلبات والتفاصيل الإضافية، انظر [حدود المعدل](../rate-limits).

### 500 Internal Server Error

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