البدء السريع

احصل على مفتاح 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

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

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

تُعيد عملية الإنشاء الناجحة 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} حتى تستقر الحالة: