Every request must include your API key. Two authentication modes are supported:

1) HMAC-SHA256 (recommended)

Sign each request and send these headers:

X-API-Key:     zk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Secret:  zs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Timestamp:   1737000000          # unix seconds, server allows ±300s
X-Signature:   hex(HMAC_SHA256(secret, "METHOD\nPATH\nTIMESTAMP\nBODY"))

2) Header API Key + Secret (simpler)

X-API-Key:    zk_...
X-API-Secret: zs_...

Keys are issued from Dashboard → API Keys. The secret is shown only once.

Submit a new invoice. The service signs the XML, generates the QR code and hash, then submits it to ZATCA for clearance (standard) or reporting (simplified).

Request body:

{
  "invoice_number": "INV-1001",
  "issue_date": "2026-05-17",
  "issue_time": "10:30:00",
  "type": "standard",         // "standard" | "simplified"
  "document": "tax",          // "tax" | "debit" | "credit" | "prepayment"
  "currency": "SAR",
  "seller": {
    "name": "ACME LLC",
    "vat_number": "399999999900003",
    "cr": "1010203020",
    "address": "King Fahd Rd, Riyadh",
    "country": "SA", "city": "Riyadh", "postal_zone": "12345",
    "street": "King Fahd Rd", "building_number": "1234",
    "plot": "PLOT-001", "subdivision": "Olaya"
  },
  "buyer": {
    "name": "Customer Co",
    "vat_number": "300000000000003",
    "address": "Jeddah", "country": "SA", "city": "Jeddah", "postal_zone": "54321",
    "street": "Tahlia", "building_number": "4567"
  },
  "lines": [
    { "name": "Product 1", "quantity": 2, "unit_price": 100.00, "tax_percent": 15 },
    { "name": "Service",   "quantity": 1, "unit_price": 50.00,  "tax_percent": 15 }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": 42,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "document_id": "INV-1001",
    "invoice_hash": "...",
    "qr_code": "AQ...base64...",
    "status": "cleared",     // cleared | reported | rejected | failed
    "response": { /* raw ZATCA response */ }
  }
}

Retrieve a previously submitted invoice including its signed XML and ZATCA response.

Generate a CSR + private key for this account (uses the values saved in Settings).

Request the compliance certificate from ZATCA. Body: { "otp": "123456" }.

Upgrade the compliance certificate into a production certificate.

{
  "success": false,
  "error": { "code": "invalid_signature", "message": "Unauthorized: invalid_signature" }
}

Common codes: missing_api_key, invalid_api_key, invalid_secret, invalid_signature, timestamp_out_of_window, ip_not_allowed.