> ## 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`)، وهما من المهام التي تؤديها Sahl للمقرضين والبنوك. أما الربط البنكي وحساب النقاط فيتمان من وحدة التحكم. هذا هو التدفق الفعلي في الإصدار v0.2.0. لمثال أطول انظر [الشرح التطبيقي](/ar/guides/walkthrough)، ولتجربة الاستدعاءات دون كتابة شيفرة انظر [الاختبار في بيئة الاختبار](/ar/test-in-sandbox).

## قبل البدء

1. فعّل واجهة الشركاء البرمجية في مساحة العمل الخاصة بك. تُفعَّل لكل مساحة عمل من قِبل Sahl ولا يمكن تفعيلها ذاتيًا: [اطلب الوصول إلى بيئة الاختبار](https://sahlfinancial.com/contact?type=demo).
2. في وحدة التحكم افتح **Settings**، ثم **API Keys**، ثم **New key**. حدّد `kyc:extract` و`kyc:verify`. انسخ السر مرة واحدة. احتفظ به على خادمك.

عيّنه في المتغير `SAHL_API_KEY`. تستخدم جميع الأمثلة `https://app.sahlfinancial.com/api` و`environment=sandbox` وبيانات وهمية. استخدم صورة وهمية خاصة بك لبطاقة التعريف الوطنية المغربية (CIN).

## 1. قراءة مستند

أرسل من 1 إلى 5 ملفات (JPEG أو PNG أو WebP أو TIFF أو PDF، بحد أقصى 30 MB لكل ملف). أضف `reference` (معرّفك الخاص للعميل) لحفظ النتيجة في ملف قضية.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.sahlfinancial.com/api/v1/kyc/extract \
    -H "Authorization: Bearer $SAHL_API_KEY" \
    -F "files=@cin-test.jpg" \
    -F "doc_type=national_id" \
    -F "reference=client-0001" \
    -F "environment=sandbox" > extracted.json
  ```

  ```javascript JavaScript theme={null}
  import { readFile } from "node:fs/promises";

  const form = new FormData();
  form.append("files", new Blob([await readFile("cin-test.jpg")], { type: "image/jpeg" }), "cin-test.jpg");
  form.append("doc_type", "national_id");
  form.append("reference", "client-0001");
  form.append("environment", "sandbox");

  const res = await fetch("https://app.sahlfinancial.com/api/v1/kyc/extract", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.SAHL_API_KEY}` },
    body: form,
  });
  const extracted = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  with open("cin-test.jpg", "rb") as f:
      res = requests.post(
          "https://app.sahlfinancial.com/api/v1/kyc/extract",
          headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
          files=[("files", ("cin-test.jpg", f, "image/jpeg"))],
          data={"doc_type": "national_id", "reference": "client-0001", "environment": "sandbox"},
      )
  extracted = res.json()
  ```
</CodeGroup>

تتضمن الاستجابة `fields` و`documents` و`field_count` و`checks` و`reader_unavailable` و`policy`. وعند وجود `reference` تتضمن أيضًا `case_id` و`document_ids`. انظر [قراءة المستندات](/ar/guides/ocr-documents).

## 2. التحقق من الملف

أعد إرسال عناصر `documents` كما وردت، مع الحقول التي تملكها.

<CodeGroup>
  ```bash cURL theme={null}
  jq '{reference: "client-0001", environment: "sandbox", subject: "Test Client", kind: "individual",
       values: {first_name: "Test", last_name: "Client"}, documents: .documents}' extracted.json |
  curl -X POST https://app.sahlfinancial.com/api/v1/kyc/verify \
    -H "Authorization: Bearer $SAHL_API_KEY" \
    -H "Content-Type: application/json" \
    -d @-
  ```

  ```javascript JavaScript theme={null}
  const verdict = await fetch("https://app.sahlfinancial.com/api/v1/kyc/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SAHL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reference: "client-0001",
      environment: "sandbox",
      subject: "Test Client",
      kind: "individual",
      values: { first_name: "Test", last_name: "Client" },
      documents: extracted.documents,
    }),
  }).then((r) => r.json());
  console.log(verdict.passed, verdict.flags);
  ```

  ```python Python theme={null}
  verdict = requests.post(
      "https://app.sahlfinancial.com/api/v1/kyc/verify",
      headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
      json={
          "reference": "client-0001",
          "environment": "sandbox",
          "subject": "Test Client",
          "kind": "individual",
          "values": {"first_name": "Test", "last_name": "Client"},
          "documents": extracted["documents"],
      },
  ).json()
  print(verdict["passed"], verdict["flags"])
  ```
</CodeGroup>

## 3. قراءة الحكم

تكون قيمة `passed` صحيحة (true) عندما لا يفشل أي فحص حرج. وتسرد `critical_failures` و`flags` ما يحتاج إلى مراجعة شخص. الملف الذي لا تتضمن مستنداته هوية بصورة يفشل بالمعرّف `required:photo_id`، لذا أرسل العناصر الناتجة من الخطوة 1. ويقبل `/v1/kyc/assess` الجسم نفسه ويضيف تقييم المخاطر.

بفضل `reference` تُحفظ القضية ومستنداتها والحكم في مساحة عملك، حيث يراها موظفوك ضمن Cases وDocuments.

## التالي

<CardGroup cols={2}>
  <Card title="التحقق من ملف" icon="shield-check" href="/ar/guides/verification">كل فحص، وما يعيده، وكيفية قراءة passed وflags.</Card>
  <Card title="الأخطاء" icon="triangle-exclamation" href="/ar/errors">كل حالة وكل رمز، مع الحل.</Card>
</CardGroup>


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