> ## 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 إلى أول فاتورة مُسلَّمة — أنشئ البيانات المرجعية، ونفّذ POST /invoices مع مثال JSON كامل، ثم أرسلها عبر Peppol.

ينقلك هذا الدليل من البداية إلى النهاية: احصل على مفتاح API، وتأكّد من وجود العميل
والأصناف، وأنشئ فاتورة عبر `POST /invoices`، ثم أرسلها للتسليم عبر Peppol.

<Steps>
  <Step title="احصل على مفتاح API">
    أنشئ مفتاحًا من **الإعدادات ← التكاملات ← مفاتيح API** وانسخ السرّ `fat_…`.
    راجع [المصادقة](/ar/developers/authentication). أرسله في ترويسة `X-Api-Key`
    في كل طلب.
  </Step>

  <Step title="أنشئ عميلًا وأصنافًا (عند الحاجة)">
    يمكنك الإشارة إلى المشتري والأصناف ضمن الفاتورة مباشرة، أو إنشاؤها أولًا
    كبيانات مرجعية لتصبح قابلة لإعادة الاستخدام. كل عملية إنشاء هي `POST` و**يجب**
    أن تحمل ترويسة `Idempotency-Key`:

    ```bash theme={null}
    curl https://integration.fatorly.com/v1/customers \
      -H "X-Api-Key: fat_your_key_here" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: customer-acme-001" \
      -d '{
        "code": "CUST-001",
        "name": "ACME Trading LLC",
        "vatTrn": "100123456700003",
        "participantId": "iso6523-actorid-upis::0235:100123456700003"
      }'
    ```
  </Step>

  <Step title="أنشئ الفاتورة">
    نفّذ `POST /invoices` بجسم `V1CreateInvoiceRequest`. يوضّح المثال أدناه فاتورة
    ضريبية بسطر واحد، إضافة إلى مواضع الحقول الاختيارية — `references`
    و`delivery` و`allowancesCharges` (على مستوى المستند والسطر) و`classifications`
    على مستوى السطر ومعرّفات الصنف وتفاصيل الدفع.

    ```bash theme={null}
    curl https://integration.fatorly.com/v1/invoices \
      -H "X-Api-Key: fat_your_key_here" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: invoice-2026-00042" \
      -d @invoice.json
    ```

    ```json invoice.json theme={null}
    {
      "documentType": "Invoice",
      "invoiceNumber": "INV-2026-00042",
      "issueDate": "2026-06-16",
      "currency": "AED",
      "seller": {
        "name": "Your Company LLC",
        "trn": "100987654300003"
      },
      "buyer": {
        "name": "ACME Trading LLC",
        "trn": "100123456700003",
        "participantId": "iso6523-actorid-upis::0235:100123456700003",
        "address": {
          "line1": "12 Sheikh Zayed Road",
          "city": "Dubai",
          "countrySubentity": "Dubai",
          "countryCode": "AE"
        }
      },
      "references": {
        "purchaseOrderId": "PO-9981",
        "buyerReference": "ACME-REF-77"
      },
      "delivery": {
        "actualDeliveryDate": "2026-06-15",
        "incoterms": "DAP",
        "streetName": "Warehouse 4, Al Quoz",
        "city": "Dubai",
        "countryCode": "AE"
      },
      "allowancesCharges": [
        {
          "isCharge": false,
          "amount": 50.00,
          "reasonCode": "95",
          "reason": "Loyalty discount",
          "vatCategory": "S",
          "vatRate": 5
        }
      ],
      "paymentMode": "30",
      "paymentBankAccount": "AE070331234567890123456",
      "lines": [
        {
          "description": "Steel bolts M8",
          "quantity": 100,
          "unitCode": "EA",
          "unitPrice": 2.50,
          "vatCategory": "S",
          "vatRate": 5,
          "sellersItemId": "BOLT-M8",
          "itemTypeCode": "G",
          "classifications": [
            { "code": "31161600", "listId": "UNSPSC" }
          ],
          "allowancesCharges": [
            { "isCharge": false, "amount": 10.00, "reason": "Bulk discount" }
          ]
        }
      ]
    }
    ```

    <Note>
      يقبل `documentType` القيم `Invoice` أو `CreditNote` أو `SelfBillingInvoice`
      أو `SelfBillingCreditNote`. كما يتطلّب إشعار الخصم (`CreditNote`) الحقل
      `precedingInvoiceNumber` (رقم الفاتورة التي يصحّحها). ويقبل `vatCategory`
      القيم `S` (النسبة الأساسية 5%) أو `Z` (نسبة صفرية) أو `E` (معفى) أو `O`
      (خارج النطاق) أو `AE` (الاحتساب العكسي) — وعلى أي سطر يكون فيه
      `vatCategory` بقيمة `E`، يكون `exemptionReasonCode` **مطلوبًا**.
    </Note>
  </Step>

  <Step title="اقرأ الاستجابة">
    تُعيد عملية الإنشاء الناجحة **201** والمستند بالحالة `Draft` — أي أنه محفوظ
    ومتحقَّق منه، لكنه **لم يُرسَل بعد إلى أي جهة**:

    ```json theme={null}
    {
      "id": "9f1c2b7e-…",
      "invoiceNumber": "INV-2026-00042",
      "status": "Draft",
      "participantDelivery": "NotApplicable",
      "createdAt": "2026-06-16T09:30:00Z",
      "links": { "self": "/v1/invoices/9f1c2b7e-…" }
    }
    ```

    إذا فشل الطلب، ستحصل على جسم خطأ بصيغة JSON ورمز حالة — راجع
    [الأخطاء](/ar/developers/errors).
  </Step>

  <Step title="أرسلها للتسليم عبر Peppol">
    اختياريًا تحقّق مسبقًا عبر `POST /invoices/{id}/validate` (ينفّذ قواعد
    PINT-AE دون إرسال)، ثم أرسل المستند:

    ```bash theme={null}
    curl -X POST https://integration.fatorly.com/v1/invoices/9f1c2b7e-…/submit \
      -H "X-Api-Key: fat_your_key_here" \
      -H "Idempotency-Key: submit-2026-00042"
    ```

    الإرسال غير متزامن: يُعيد الطلب **202** مع `status: "Pending"`. استعلم عبر
    `GET /invoices/{id}` حتى تستقر الحالة:

    | `status`         | المعنى                                                               |
    | ---------------- | -------------------------------------------------------------------- |
    | `Draft`          | أُنشئ ولم يُرسَل بعد                                                 |
    | `Pending`        | في قائمة الانتظار أو قيد التسليم عبر Peppol                          |
    | `Sent`           | تم التسليم                                                           |
    | `DeliveryFailed` | فشل الإرسال — راجع `submissionError`، وصحّح عبر `PUT` ثم أعد الإرسال |
    | `Received`       | مستند وارد (مشتريات)                                                 |
  </Step>
</Steps>

<Warning>
  **يجب** أن يتضمّن كل `POST` ترويسة `Idempotency-Key`. وبدونها يُرفَض الطلب برمز
  **400**. أعِد استخدام المفتاح نفسه عند إعادة المحاولة كي لا تُنشأ نسخة مكرّرة —
  راجع [معرّف عدم التكرار](/ar/developers/idempotency).
</Warning>