Developer user guide

Your application talks to EBridge only. EBridge signs and sends the invoice to ZATCA. You never call Fatoora, and you never send invoices to this public website.

Your app → EBridge (client environment / IIS) → ZATCA → result back to your app

Host

After install, the merchant emails you the EBridge URL in their environment (example below). It is not ebridge.rkcoders.com.

http://CLIENT-HOST:PORT

1. Get an API key

The merchant opens a company in the EBridge portal and issues a key that starts with eb_. Put only that key in your application — not the portal password and not the operator key.

X-Api-Key: eb_your_key

2. Check the key

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

HTTP 200 with the company name means the key is good. HTTP 401 means the key is wrong.

3. Submit a simplified (B2C) invoice

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 plus buyer VAT and address. Credit note: documentKind CreditNote plus original uuid, hash, and reason.

4. Store the reply

Save uuid, invoiceHash, qrCode, and status. HTTP 200 means EBridge handled the request — still read status. The same invoiceNumber (or Idempotency-Key / uuid) returns the stored result and does not call ZATCA again (alreadySubmitted is true). HTTP 400 = fix the JSON. HTTP 502 = retry with the same invoice number.

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

Lookup: GET http://CLIENT-HOST:PORT/api/v1/invoices/{id} or /api/v1/invoices/by-uuid/{uuid}

Do not

Do not sign in to the merchant portal from the app.
Do not put the operator password, Fatoora OTP, or CSR/CSID in the app.
Do not call ZATCA directly.
Do not post invoices to ebridge.rkcoders.com — that site is registration and download only.

Merchant setup (not for the connecting app)