> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahlfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# كيف تترابط الاستدعاءات

> extract وverify وassess وeID: ما يأخذه كل استدعاء، وما يعيده، وما تمرّره إلى الخطوة التالية.

تؤدي واجهة Partner API أربع مهام وتضم ستّ نقاط نهاية. كل استدعاء دالة لما ترسله. ولا تحفظ Sahl أي شيء في مساحة عملك ما لم يحمل الاستدعاء `reference`.

| المهمة | نقطة النهاية | النطاق | يستهلك قراءة |
| - | - | - | - |
| قراءة الوثائق إلى حقول | `POST /v1/kyc/extract` | `kyc:extract` | نعم، واحدة لكل ملف |
| التحقق من ملف تعريف ووثائقه | `POST /v1/kyc/verify` | `kyc:verify` | لا |
| التحقق ثم تقييم المخاطر | `POST /v1/kyc/assess` | `kyc:verify` | لا |
| فحص عميل كندي عن بُعد | `POST /v1/kyc/eid`، `GET /v1/kyc/eid/{key}`، `GET /v1/kyc/eid/{key}/report` | `kyc:eid` | لا |

`/extract` وحده يستدعي نموذج الرؤية، لذا فهو الوحيد الذي يُحتسب استهلاكه. ويُفحص الرصيد المسموح قبل قراءة أي ملف.

## المسار الرئيسي

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Your server
    participant API as Sahl Partner API
    participant Console as Sahl console
    App->>API: POST /v1/kyc/extract (files, doc_type, reference)
    API-->>App: fields, documents[], checks[], case_id
    App->>API: POST /v1/kyc/extract (next document)
    API-->>App: fields, documents[], checks[]
    Note over App: Merge the fields you hold into values.<br/>Keep the documents[] entries unchanged.
    App->>API: POST /v1/kyc/verify (reference, values, documents[])
    API-->>App: passed, checks[], flags[], completeness, case_id
    App->>API: POST /v1/kyc/assess (same body)
    API-->>App: verification, assessment, case_id
    API-->>Console: case, documents and verdict filed under reference
```

ما تمرّره من استدعاء إلى آخر:

| من | إلى | ماذا |
| - | - | - |
| `documents[]` في إجابة `/extract` | `documents` في طلب `/verify` و`/assess` | كل عنصر دون تغيير، بما في ذلك `step_key` و`document_id`. |
| `fields` في إجابة `/extract` | نموذجك أو قاعدة بياناتك | تعبئة مسبقة. أنت من يقرر أي قيم تدخل في `values`. |
| بياناتك الخاصة | `values` في طلب `/verify` و`/assess` | الأسماء والتواريخ والعنوان والدخل وإجابات الملاءمة. |
| `reference` نفسه | كل استدعاء | يربط الاستدعاءات بحالة واحدة. |

يأخذ `/assess` الجسم نفسه الذي يأخذه `/verify` ويجري التحقق نفسه أولاً. إذا أردت الإجابتين معاً، فاستدعِ `/assess` فقط: يحتوي مفتاح `verification` فيه على الحكم الكامل.

## لماذا تُعاد العناصر

لا يقرأ `/verify` الملفات. بل يفحص عناصر `documents[]` التي ترسلها، لذا يحتاج إلى ما رآه `/extract`: نوع الوثيقة والحقول وتواريخ الملف و`step_key`. فبدون `step_key` قد تجتاز الوثيقة نفسها فحص النوع في `/extract` وتخفق فيه في `/verify`. ولهذا السبب تضع الواجهة `step_key` على كل عنصر.

إذا عدّلت عنصراً، فإنك تتحقق من تعديلك لا من الوثيقة.

## مسار eID

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Your server
    participant API as Sahl Partner API
    participant Provider as eID provider
    participant Client as Your client
    App->>API: POST /v1/kyc/eid (reference, name, email, country=CA)
    API->>Provider: create request
    Provider-->>Client: email with PIN and link
    API-->>App: 201 key, reference
    Client->>Provider: scans ID, takes selfie
    loop until complete is true
        App->>API: GET /v1/kyc/eid/{key}
        API->>Provider: read request
        API-->>App: complete, passed, checks[]
    end
    App->>API: GET /v1/kyc/eid/{key}/report
    API-->>App: PDF
    App->>API: POST /v1/kyc/verify (same reference and environment)
    API-->>App: verdict that meets the policy eID requirement
```

لا يوجد استدعاء راجع من المزوّد. أنت تستطلع، وترسل Sahl webhook `kyc.eid_completed` عند أول استطلاع يرى حالة الانتهاء. التفاصيل في [التحقق عبر eID](/ar/guides/eid). في هذا الإصدار تقتصر خاصية eID على العملاء الكنديين، لذا يستخدم الطلب النموذجي `country=CA`؛ أما كل استدعاء آخر في هذه الصفحة فيقبل أي بلد، مثل `MA`.

## دورة حياة الحالة

توجد الحالة مرة واحدة لكل مساحة عمل وبيئة و`reference`. وكل استدعاء بهذا المرجع يحدّثها.

```mermaid theme={null}
flowchart LR
    A[First call with a reference] --> B[Case created]
    B --> C[extract: documents filed]
    C --> D[verify or assess: verdict filed]
    D --> E[eID: result recorded when polled]
    D --> F[Staff review in the console]
    F --> G[approved or refused]
```

لا تُلغي إعادة التحقق أبداً حالةً حددها شخص: تبقى `approved` و`refused`.

## اختيار الاستدعاءات

| ما تريده | الاستدعاء |
| - | - |
| نص الوثيقة وحقولها فقط | `/extract` |
| إجابة بنعم أو لا على ملف تملك بياناته أصلاً | `/verify` مع `documents: []` و`require_documents: false` (يعمل عندما لا تقفل سياستك التحقق من الهوية) |
| فحوص الوثائق مع الفحوص المتقاطعة بينها | `/extract` لكل وثيقة، ثم `/verify` |
| تصنيف مخاطر للملف | `/assess` |
| إثبات أن العميل عن بُعد هو صاحب وثيقة الهوية | `/eid` |

<Note>
  لا تتضمن الواجهة مفتاح idempotency ولا نقطة نهاية للدفعات. فإرسال الاستدعاء نفسه مرتين يقرأ الملفات مرتين ويحتسب قراءتين، ويحفظ مجموعة وثائق ثانية في الحالة. راجع [الأخطاء وإعادة المحاولة](/ar/errors).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.