> ## 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.

# الاختبار في sandbox

> أنشئ مفتاحاً، ونفّذ ستة طلبات من هذا الموقع، وتحقق من النتيجة في وحدة التحكم. نحو 15 دقيقة.

يمكنك تشغيل كل نقاط النهاية من هذه الوثائق. يرسل API playground الطلب من متصفحك مباشرة إلى `https://app.sahlfinancial.com/api` بمفتاحك الخاص. لا يمرر هذا الموقع الطلب عبر وسيط ولا يخزّن مفتاحك.

<Warning>
  استخدم عملاء ومستندات وهمية فقط. لا ترفع أبداً مستند عميل حقيقي.
</Warning>

## ما تحتاج إليه

| العنصر | مصدره |
| - | - |
| مساحة عمل مفعّلة لـ partner KYC API | ليس بالخدمة الذاتية: [اطلب الوصول إلى sandbox](https://sahlfinancial.com/contact?type=demo). بدونها لا يعرض نموذج المفتاح أي نطاق `kyc:` وتعيد المكالمات 403 `kyc_scope_not_allowed`. |
| مستخدم في وحدة التحكم يستطيع إدارة المفاتيح | دور tenant admin أو API manager، مع بريد إلكتروني موثق. |
| مفتاح API بالنطاقات التي تختبرها | يُنشأ في وحدة التحكم، بالخطوات أدناه. |
| ملف اختبار وهمي (اختياري، لـ `/extract`) | أي ملف JPEG أو PNG أو WebP أو TIFF أو PDF أعددته بنفسك، حتى 30 MB. |

## الخطوة 1. أنشئ مفتاح sandbox

لا يوجد مفتاح sandbox منفصل. يعمل المفتاح في البيئتين، وتختار كل مكالمة إحداهما عبر الحقل `environment` (القيمة الافتراضية `sandbox`). و"مفتاح sandbox" هو مفتاح لا تستخدمه إلا مع ضبط `environment` على `sandbox`.

1. سجّل الدخول عبر [app.sahlfinancial.com](https://app.sahlfinancial.com).
2. افتح **Settings** ثم تبويب **API Keys**.
3. انقر **New key**. سمّه `sandbox-test`.
4. حدد النطاقات التي تريد اختبارها: `kyc:extract` و`kyc:verify` و`kyc:eid`. اترك **Bound service account** فارغاً. إذا ملأته فيجب أن ترسل كل مكالمة أيضاً رمز هوية Google في `X-Partner-Identity`، وهو ما لا يستطيع playground فعله.
5. انقر **Create API Key**. يظهر السر مرة واحدة، بصيغة `sk_` يتبعها 8 أحرف ثم شرطة سفلية و64 حرفاً. انسخه الآن. لا تستطيع وحدة التحكم عرضه مرة أخرى.

إذا فقدت السر، أنشئ مفتاحاً آخر وألغِ القديم. راجع [المصادقة](/ar/authentication) للاطلاع على التدوير.

## الخطوة 2. افتح playground

1. افتح تبويب **API reference** في هذا الموقع، ثم **Verify a profile**.
2. انقر **Try it** في أعلى يمين الصفحة.
3. في الحقل **Authorization** الصق مفتاحك. الصق المفتاح وحده. يضيف playground الكلمة `Bearer`.
4. اترك الخادم على `https://app.sahlfinancial.com/api`.

جسم الطلب معبأ مسبقاً بعميل وهمي. اختر المثال المسمى **Minimal profile, no documents** إذا عرض playground خياراً.

<Note>
  يستدعي playground الـ API مباشرة من متصفحك. إذا فشل طلب بخطأ شبكة قبل ظهور أي رمز حالة، فقد حجبه متصفحك (CORS). نفّذ الطلب نفسه بـ cURL من نموذج الشيفرة في الصفحة، أو استخدم [مجموعة Postman](/postman).
</Note>

## الخطوة 3. نفّذ الطلبات الستة

نفّذها بهذا الترتيب. كل طلب بضع نقرات.

### 3.1 تحقق من ملف تعريفي

أرسل المثال الأدنى كما هو.

```json theme={"dark"}
{
  "reference": "client-0001",
  "environment": "sandbox",
  "subject": "Test Client",
  "kind": "individual",
  "values": { "first_name": "Test", "last_name": "Client" },
  "documents": [],
  "require_documents": false
}
```

المتوقع: HTTP 200 وجسم بالشكل التالي.

```json theme={"dark"}
{
  "passed": true,
  "checks": [
    { "id": "screening", "label": "Sanctions screening — no matches; PEP not list-screened", "severity": "info", "passed": true, "detail": "screened against 23000 sanctions entries. The bundle carries no PEP list, so politically-exposed status rests on the client's declaration, not on a list check." },
    { "id": "completeness", "label": "KYC/KYB data completeness (7%)", "severity": "warning", "passed": false, "detail": "missing 26 required data point(s): date_of_birth, citizenship, id_type, id_number, id_expiry, street1, city, province" }
  ],
  "critical_failures": [],
  "flags": [ { "id": "completeness", "severity": "warning", "passed": false } ],
  "completeness": { "required": 28, "present": 2, "percent": 7 },
  "policy": { "id": null, "version": 0, "source": "legacy", "regime": "none", "regulator": null, "purpose": "onboarding", "overrides_refused": [] },
  "registry": null,
  "case_id": "00000000-0000-4000-8000-000000000001"
}
```

تختلف القيم في استجابتك: `case_id` معرّف حقيقي، وعدد الإدخالات في تفصيل الفحص (screening) هو حجم القائمة المحمّلة، وقد تضيف سياسة مساحة عملك فحوصاً. القيمة `passed: true` مع تحذير اكتمال هي النتيجة العادية هنا. اختُصر `flags` و`completeness.missing` أعلاه.

### 3.2 اجعله يفشل عمداً

اضبط `require_documents` على `true` وأرسل مرة أخرى. إذا سمحت سياسة مساحة عملك بذلك، فستحمل الاستجابة الآن `passed: false` وفحصاً حرجاً `required:photo_id` بالتفصيل `no readable government photo ID among the uploads`. يبين هذا شكل الملف المحظور.

### 3.3 اقرأ مستنداً

1. افتح **Read documents**.
2. اضبط `files` على قسيمة الراتب الوهمية. واضبط `doc_type` على `payslip`، و`reference` على `client-0001`، و`environment` على `sandbox`، و`kind` على `individual`.
3. أرسل.

المتوقع: HTTP 200 مع `fields` و`documents` و`field_count` و`checks` و`reader_unavailable` و`policy` و`case_id` و`document_ids`. قسيمة الراتب لا تعطي `checks`. وتتوقف الحقول العائدة على ما هو مطبوع في ملفك؛ راجع [أنواع المستندات وحقولها](/ar/guides/document-types).

تُحتسب كل قراءة من حصتك الشهرية (2,000 قراءة افتراضياً).

### 3.4 قيّم المخاطر

افتح **Verify and assess risk** واختر المثال **Profile with the suitability answers**. أرسل.

المتوقع: `verification` و`assessment` و`registry`. وبقيم المثال يكون التقييم: ملف المخاطر 58 `Balanced`، والقدرة 20 `Low`، ومخاطر الامتثال `Low` أو `Medium` (بحسب سياستك وقائمة الفحص) وسلسلة `suitability`. راجع [تقييم المخاطر](/ar/guides/risk-assessment) لمعرفة كيفية بناء كل رقم.

### 3.5 اختياري: ابدأ فحص eID

<Warning>
  هذه المكالمة حقيقية في sandbox أيضاً. يراسل مزود eID العميل بالبريد بـ PIN ورابط فور إنشاء الطلب. استخدم عنواناً تتحكم فيه. في هذا الإصدار يجب أن يكون العميل كندياً (`CA` أو `CAN`)، وهو البلد الوحيد الذي يقبله المحرك، وتحتاج مساحة عملك إلى حساب مزود eID خاص بها، وإلا أعادت المكالمة 404 `identity verification is not set up for this tenant`.
</Warning>

افتح **Start an eID check**، واضبط بريدك الإلكتروني، وأرسل. تحصل على HTTP 201 و`key`. ثم افتح **Get an eID check**، وأدخل `key` وأرسل حتى تصبح `complete` تساوي `true`. راجع [فحص eID](/ar/guides/eid).

## الخطوة 4. اطلع على النتيجة في وحدة التحكم

لأن كل طلب حمل `reference`، فقد حفظت المكالمة حالة في مساحة عملك.

| المكان في وحدة التحكم | ما تراه |
| - | - |
| **Cases** | حالة واحدة لكل بيئة ومرجع: `client-0001` في `sandbox`. |
| **Documents** | الملفات التي أرسلتها، والحقول المقروءة، وفحوص كل مستند. |
| **Developers, Call log** | كل مكالمة API مع حالتها وزمن استجابتها و`X-Request-ID`. |

تبدّل شارة البيئة في الشريط العلوي لوحدة التحكم ما تعرضه القوائم. التبديل إلى production يعمل في كل الخطط، ضمن حدود الخطة: تتضمن الخطة Free عشر (10) حالات Production في الشهر وتتطلب بريداً إلكترونياً مهنياً موثقاً (وليس Gmail أو Yahoo)، وSandbox غير محدود في كل الخطط.

## عند الفشل

| ما تراه | السبب | الحل |
| - | - | - |
| 401 `Missing API key` | حقل Authorization فارغ. | الصق المفتاح. |
| 401 `Invalid or revoked API key` | خطأ مطبعي، أو مفتاح ملغى، أو مفتاح من مساحة عمل أخرى. | أنشئ مفتاحاً جديداً. |
| 403 `API key lacks the kyc:verify scope` | أُنشئ المفتاح بدون هذا النطاق. | أنشئ مفتاحاً يحمل النطاق. |
| 403 `kyc_scope_not_allowed` | مساحة العمل غير مفعّلة لـ partner API. | [اطلب الوصول إلى sandbox](https://sahlfinancial.com/contact?type=demo). |
| 422 مع قائمة `loc` | حقل لا يطابق المخطط. | اقرأ `detail[].loc` و`msg`. |
| 429 `kyc_extract_cap_reached` | استُنفدت حصة القراءة الشهرية. | اطلب من Sahl رفعها. |

جميع أجسام الأخطاء موجودة في [فهرس الأخطاء](/ar/errors).

## التالي

<CardGroup cols={2}>
  <Card title="Postman" icon="paper-plane" href="/postman">نفّذ الطلبات نفسها بمجموعة وسكربت اختبار.</Card>
  <Card title="الدليل الشامل" icon="route" href="/ar/guides/walkthrough">من قسيمة راتب وبطاقة تعريف وطنية مغربية إلى تقييم المخاطر، مع cURL وJavaScript وPython.</Card>
</CardGroup>


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