توثيق واجهة API

الاستيثاق

كل طلب يتطلب مفتاح API في ترويسة Authorization. ولّد مفتاحك من الإعدادات ← واجهة API — يظهر مرة واحدة فقط عند التوليد، وصلاحيته كاملة على فوترة منشأتك فعامله كسر: خزّنه في متغير بيئة ولا تضعه في الكود أو المستودع.

curl https://zatcatools.com/api/v1/account \
  -H "Authorization: Bearer ztk_live_..."

الأخطاء

كل الأخطاء ترجع بشكل موحّد:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Free-plan invoice quota exhausted. Contact us to upgrade."
  }
}

بيانات المنشأة، حالة الربط، والرصيد المتبقي من الباقة.

{
  "name": "مؤسسة النخبة",
  "vat_number": "310000000000003",
  "cr_number": "1010101010",
  "zatca": {
    "connected": true,
    "environment": "production",
    "certificate_expires_at": "2027-07-01"
  },
  "quota": { "used": 12, "limit": 50, "remaining": 38 }
}

يبني الفاتورة، يوقّعها رقميًا، ويرسلها إلى ZATCA في طلب واحد — تخليصًا (Clearance) للضريبية أو إبلاغًا (Reporting) للمبسطة. الفاتورة الضريبية standard تتطلب كائن customer كاملًا؛ المبسطة simplified لا تتطلبه. العملاء يُطابَقون تلقائيًا بالرقم الضريبي (أو يُنشأون إن لم يوجدوا).

curl -X POST https://zatcatools.com/api/v1/invoices \
  -H "Authorization: Bearer ztk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "customer": {
      "name": "شركة المثال للتجارة",
      "vat_number": "311111111101113",
      "cr_number": "1010101010",
      "street": "طريق الملك فهد",
      "building_number": "8228",
      "city": "الرياض",
      "postal_zone": "12244"
    },
    "lines": [
      { "name": "اشتراك سنوي", "quantity": 1, "unit_price": 1000 }
    ],
    "discount": 0,
    "issue_date": "2026-07-19"
  }'

{
  "type": "simplified",
  "lines": [
    { "name": "قهوة مختصة 250غ", "quantity": 2, "unit_price": 55 },
    { "name": "أدوات تحضير", "quantity": 1, "unit_price": 120 }
  ]
}

{
  "uuid": "8d9f6e0a-4b7c-4f2e-9a1d-3c5b7e9f1a2b",
  "number": "INV-2026-00042",
  "kind": "invoice",
  "type": "standard",
  "status": "accepted",
  "issue_date": "2026-07-19",
  "totals": {
    "lines": "1000.00", "discount": "0.00",
    "vat": "150.00", "grand": "1150.00", "currency": "SAR"
  },
  "customer": { "name": "شركة المثال للتجارة", "vat_number": "311111111101113" },
  "zatca": {
    "channel": "clearance",
    "icv": 42,
    "submitted_at": "2026-07-19T09:30:00+03:00",
    "warnings": []
  },
  "links": {
    "xml": "https://zatcatools.com/api/v1/invoices/{uuid}/xml",
    "pdf": "https://zatcatools.com/api/v1/invoices/{uuid}/pdf",
    "qr":  "https://zatcatools.com/api/v1/invoices/{uuid}/qr.svg"
  },
  "lines": [
    { "name": "اشتراك سنوي", "quantity": 1, "unit_price": 1000, "total": 1000 }
  ]
}

الأحدث أولًا. معاملات اختيارية: status (accepted | warnings | rejected | draft) · type (standard | simplified) · page · per_page (الأقصى 100).

{
  "data": [ { "uuid": "...", "number": "INV-2026-00042", "status": "accepted", ... } ],
  "meta": { "page": 1, "per_page": 25, "total": 128, "last_page": 6 }
}

التفاصيل الكاملة لفاتورة أو إشعار — نفس شكل استجابة الإصدار، شاملة البنود وأسباب الرفض إن وجدت.

الملفات — XML · PDF · QR

لكل مستند مُصدَر ثلاثة تنزيلات (بنفس ترويسة الاستيثاق):

إشعار دائن (credit) أو مدين (debit) مرتبط بفاتورة أصلية عبر invoice_uuid. السبب reason إلزامي (متطلب الهيئة BR-KSA-17)، وقيمة إشعار الدائن لا تتجاوز الرصيد المتبقي للفاتورة بعد الإشعارات السابقة (المادة 40).

{
  "kind": "credit",
  "invoice_uuid": "8d9f6e0a-4b7c-4f2e-9a1d-3c5b7e9f1a2b",
  "reason": "إرجاع جزئي للبضاعة",
  "lines": [
    { "name": "اشتراك سنوي", "quantity": 1, "unit_price": 500 }
  ]
}

حدود الاستخدام

• 60 طلبًا في الدقيقة لكل مفتاح — التجاوز يرجع 429.
• إصدار الفواتير يستهلك من رصيد باقتك — تابع المتبقي عبر GET /v1/account.
• مفتاح واحد فعّال لكل منشأة — إعادة التوليد تبطل المفتاح السابق فورًا.