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

# مرجع API

> مرجع تفاعلي لكل نقاط نهاية واجهة Fatorly Integration API.

هذا القسم مرجعٌ تفاعليٌّ كامل لواجهة **Fatorly Integration API** (الإصدار v1).
تُدرَج كل نقطة نهاية في الشريط الجانبي ضمن **API Reference**، مع مُعاملاتها
ومخطّطات الطلب والاستجابة، إضافةً إلى **ساحة تجريب** داخل الصفحة لإرسال طلبات
حيّة ومشاهدة الاستجابات الفعلية.

<Note>
  هل أنت جديد على الواجهة؟ ابدأ بأدلة [نظرة عامة](/ar/developers/overview)
  و[المصادقة](/ar/developers/authentication) و[البدء السريع](/ar/developers/quickstart)،
  ثم استخدم هذا المرجع للاطّلاع على تفاصيل نقاط النهاية كاملةً. صفحات نقاط النهاية
  المولّدة متاحة بالإنجليزية فقط.
</Note>

## عنوان الأساس (Base URL)

| البيئة               | العنوان الأساسي                           |
| -------------------- | ----------------------------------------- |
| الإنتاج (Production) | `https://integration.fatorly.com`         |
| الاختبار (Sandbox)   | `https://integration.sandbox.fatorly.com` |

جميع نقاط النهاية مُصدَّرة تحت `/v1` (مثل `POST /v1/invoices`). تستخدم الأمثلة في هذا
المرجع الإنتاج؛ بدّل المضيف للاختبار.

## القيم المسموح بها

تقبل الحقول ذات المفردات المغلقة هذه القيم حصرًا (وهي مُعلنة أيضًا كـ enum في
مخطّط كل نقطة نهاية أدناه، مع مثال مُعبّأ مسبقًا في ساحة التجريب):

| الحقل                 | القيم                                                                                                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `documentType`        | `Invoice` أو `CreditNote` أو `SelfBillingInvoice` أو `SelfBillingCreditNote` — إصدارات `SelfBilling*` يُصدرها المشتري نيابةً عن المورّد                                       |
| `vatCategory`         | `S` (النسبة الأساسية 5%) أو `Z` (نسبة صفرية) أو `E` (معفى — يتطلّب `exemptionReasonCode`) أو `O` (خارج النطاق) أو `AE` (الاحتساب العكسي — يتطلّب `goodsNatureCode` على السطر) |
| `status`              | `Draft` أو `Pending` أو `Sent` أو `DeliveryFailed` أو `Received`                                                                                                              |
| `participantDelivery` | `Pending` أو `Failed` أو `NotApplicable`                                                                                                                                      |
| `direction`           | `Outbound` (مبيعات) أو `Inbound` (مشتريات)                                                                                                                                    |
| `itemTypeCode`        | `G` (سلع) أو `S` (خدمات) أو `B` (كلاهما — تتطلّب `S` و`B` الحقل `serviceAccountingCode`)                                                                                      |
| `paymentMode`         | أي رمز UNCL4461 (‏`10` نقدًا، `20` شيك، `30` تحويل مصرفي، `48` بطاقة مصرفية، `49` خصم مباشر، …) أو الأسماء `cash` و`cheque` و`card` و`debit`؛ القيمة الافتراضية `30`          |

## المصادقة

يتطلّب كل طلب مفتاح API الخاص بك في ترويسة `X-Api-Key`.

<Steps>
  <Step title="أنشئ مفتاح API">
    من المنصّة، انتقل إلى **الإعدادات ← مفاتيح API** وأنشئ مفتاحًا. يبدو المفتاح
    بالشكل `fat_…` ويُعرَض **مرّة واحدة فقط** — انسخه فورًا. راجع
    [مفاتيح API](/ar/settings/api-keys).
  </Step>

  <Step title="أضِفه إلى ساحة التجريب">
    في أي صفحة نقطة نهاية أدناه، افتح لوحة **Authorization** والصق مفتاحك في حقل
    **`X-Api-Key`**.
  </Step>

  <Step title="أرسل طلبًا">
    عبّئ المُعاملات واختر **Send** لاستدعاء واجهة Integration API الحيّة.
  </Step>
</Steps>

<Warning>
  عامِل مفتاح API كأنّه كلمة مرور. تعمل الاستدعاءات على بيانات شركتك الفعلية. إذا
  فُقد المفتاح أو تسرّب، فألغِه من **الإعدادات ← مفاتيح API** وأنشئ مفتاحًا جديدًا.
</Warning>