دليل المستخدم للمطور

تطبيقك يتحدث مع إي بريدج فقط. إي بريدج يوقّع ويرسل إلى زاتكا. لا تستدعِ فاتورة ولا هذا الموقع العام للفواتير.

تطبيقك → إي بريدج (بيئة العميل / IIS) → زاتكا → النتيجة إلى تطبيقك

المضيف

بعد التثبيت، التاجر يرسل لك عنوان إي بريدج في بيئته (مثال أدناه). ليس ebridge.rkcoders.com.

http://CLIENT-HOST:PORT

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

التاجر يفتح الشركة في بوابة إي بريدج ويُصدر مفتاحاً يبدأ بـ eb_. ضع هذا المفتاح فقط في تطبيقك — ليس كلمة مرور الدخول ولا مفتاح المشغّل.

X-Api-Key: eb_your_key

2. تحقق من المفتاح

GET http://CLIENT-HOST:PORT/api/v1/whoami
X-Api-Key: eb_your_key

HTTP 200 مع اسم الشركة يعني المفتاح صحيح. HTTP 401 يعني المفتاح خطأ.

3. أرسل فاتورة مبسّطة (B2C)

POST http://CLIENT-HOST:PORT/api/v1/invoices/submit
Content-Type: application/json
X-Api-Key: eb_your_key
Idempotency-Key: ticket-1001

{
  "egsUnitId": "paste-unit-id-if-you-have-more-than-one",
  "invoiceNumber": "1001",
  "invoiceKind": "Simplified",
  "documentKind": "Invoice",
  "issueDateTime": "2026-09-16T12:00:00Z",
  "currency": "SAR",
  "buyer": { "name": "Cash Customer" },
  "lines": [{
    "name": "Item",
    "quantity": 1,
    "unitCode": "PCE",
    "netAmount": 100.00,
    "vatCategory": "S",
    "vatRate": 15
  }],
  "totals": {
    "lineExtensionAmount": 100.00,
    "taxExclusiveAmount": 100.00,
    "taxAmount": 15.00,
    "taxInclusiveAmount": 115.00,
    "payableAmount": 115.00,
    "allowanceTotalAmount": 0
  }
}

B2B: invoiceKind = Standard مع رقم ضريبة المشتري والعنوان. إشعار دائن: documentKind = CreditNote مع uuid الأصلي والتجزئة والسبب.

4. احفظ الرد

احفظ uuid و invoiceHash و qrCode و status. HTTP 200 يعني أن إي بريدج عالج الطلب — اقرأ status. نفس invoiceNumber أو Idempotency-Key أو uuid يعيد النتيجة المخزّنة ولا يستدعي زاتكا مرة ثانية (alreadySubmitted = true). HTTP 400 = صحّح JSON. HTTP 502 = أعد بنفس الرقم.

{
  "ebridgeInvoiceId": "…",
  "uuid": "…",
  "invoiceHash": "…",
  "qrCode": "…",
  "status": "Reported",
  "alreadySubmitted": false,
  "zatca": { }
}

الاستعلام: GET http://CLIENT-HOST:PORT/api/v1/invoices/{id} أو /api/v1/invoices/by-uuid/{uuid}

ما لا تفعله

إعداد التاجر (ليس للمطور المتصل)