البدء السريع

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

احصل على مفتاح API

أنشئ مفتاحًا من الإعدادات ← التكاملات ← مفاتيح API وانسخ السرّ fat_…. راجع المصادقة. أرسله في ترويسة X-Api-Key في كل طلب.

أنشئ عميلًا وأصنافًا (عند الحاجة)

يمكنك الإشارة إلى المشتري والأصناف ضمن الفاتورة مباشرة، أو إنشاؤها أولًا كبيانات مرجعية لتصبح قابلة لإعادة الاستخدام. كل عملية إنشاء هي POST ويجب أن تحمل ترويسة Idempotency-Key:

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"
  }'

أنشئ الفاتورة

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

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

invoice.json

{
  "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" }
      ]
    }
  ]
}

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

اقرأ الاستجابة

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

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

إذا فشل الطلب، ستحصل على جسم خطأ بصيغة JSON ورمز حالة — راجع الأخطاء.

أرسلها للتسليم عبر Peppol

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

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`	مستند وارد (مشتريات)

يجب أن يتضمّن كل POST ترويسة Idempotency-Key. وبدونها يُرفَض الطلب برمز 400. أعِد استخدام المفتاح نفسه عند إعادة المحاولة كي لا تُنشأ نسخة مكرّرة — راجع معرّف عدم التكرار.

ابدأ من هنا

الرئيسية

المبيعات

المشتريات

الفوترة الذاتية

محرّر الفواتير

التقارير

البيانات الأساسية

إعدادات الشركة

الحساب

تعدّد الشركات

المدقق

المطوّرون

API Reference

البدء السريع