توثيق الـ API

المصادقة

أنشئ مفتاح من الإعدادات وأرسله في الترويسة. المفتاح يظهر مرة وحدة، فاحفظه في مكان آمن وما تحطه في كود الواجهة.

Authorization: Bearer rabt_live_xxxxxxxxxxxxxxxx

POST /api/v1/invoices/create

curl -X POST https://YOUR-DOMAIN/api/v1/invoices/create \
  -H "Authorization: Bearer rabt_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10452" \
  -d '{
    "profile": "simplified",
    "customerName": "محمد العتيبي",
    "items": [
      { "name": "قهوة مختصة 250غ", "quantity": 2, "unitPrice": 45.00 },
      { "name": "كوب سيراميك",     "quantity": 1, "unitPrice": 30.00 }
    ]
  }'

منع التكرار: أرسل ترويسة Idempotency-Key برقم الطلب عندك. لو انعاد نفس الطلب بنرجّع نفس الفاتورة مع duplicate: true بدل ما نصدر وحدة ثانية.

الرد

HTTP/1.1 201 Created

{
  "invoice": {
    "id": "0d6f1a3e-…",
    "invoice_number": "INV-000128",
    "uuid": "8e6000cf-1a98-4174-b3e7-b5d5954bc10d",
    "icv": 128,
    "profile": "simplified",
    "kind": "invoice",
    "net_amount": 120,
    "vat_amount": 18,
    "total_amount": 138,
    "status": "zatca_accepted",
    "zatca_qr_base64": "AR/Zhdiq2KzYsSDYsdio2Lcg…",
    "zatca_hash": "f+0WCqnPkInI+eL9G3LAry12fTPf+toC9UX07F4fI+s=",
    "source": "api",
    "issued_at": "2026-01-15T10:30:00.000Z"
  },
  "duplicate": false,
  "zatca": { "status": "zatca_accepted", "zatcaStatus": "REPORTED", "warnings": [], "errors": [] }
}

• zatca_qr_base64: حوّله لصورة QR واطبعه على الفاتورة. يقرأه تطبيق هيئة الزكاة الرسمي.
• status: zatca_accepted مقبولة، zatca_rejected مرفوضة (السبب في zatca.errors)، draft انحفظت وما وصلها رد نهائي — تُعاد من لوحة التحكم.
• لو المنشأة ما ربطت مع الهيئة، الفاتورة ترجع draft برمز QR من خمس خانات.

الأخطاء

{ "error": "رسالة الخطأ", "details": ["…"] }