واجهة الفواتير البرمجية

# Your gateway confirmed the payment: issue the invoice already paid.
curl -X POST https://fatoora.tw.sa/api/v1/invoices \
  -H "Authorization: Bearer wbk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "ORDER-1001",
    "issue_date": "2026-11-12",
    "customer": {"name": "Walk-in customer"},
    "items": [{"description": "Annual plan", "quantity": 1, "unit_price": 100}],
    "payment": {"method": "mada", "reference": "GW-TXN-55"}
  }'

// After your gateway's success callback, never before.
$response = $client->post('invoices', [
    'json' => [
        'external_reference' => $order->id,          // safe to retry
        'issue_date'         => date('Y-m-d'),
        'items'              => $order->lines,
        'payment'            => [
            'method'    => 'mada',                     // or visa_mastercard, apple_pay, stc_pay …
            'reference' => $gateway->transactionId,   // shown on the receipt
            // 'amount' defaults to the invoice total
        ],
    ],
    'http_errors' => false,
]);
$body = json_decode((string) $response->getBody(), true);
// $body['data']['invoice']['status'] === 'paid'

const res = await fetch("https://fatoora.tw.sa/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WONDERFATOORA_API_KEY}`,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  body: JSON.stringify({
    external_reference: order.id, // safe to retry
    issue_date: new Date().toISOString().slice(0, 10),
    items: order.items,
    payment: { method: "mada", reference: gatewayTxn.id }, // amount defaults to the total
  }),
});
const body = await res.json();
// body.data.invoice.status === "paid", body.data.payment.number is the receipt

res = requests.post(
    "https://fatoora.tw.sa/api/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['WONDERFATOORA_API_KEY']}",
             "Accept": "application/json"},
    json={
        "external_reference": order["id"],  # safe to retry
        "issue_date": order["date"],
        "items": order["items"],
        "payment": {"method": "mada", "reference": txn["id"]},  # amount defaults to the total
    },
    timeout=60,
)
body = res.json()
# body["data"]["invoice"]["status"] == "paid"

import os, time, uuid
import requests

API = "https://fatoora.tw.sa/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WONDERFATOORA_API_KEY']}",
           "Accept": "application/json"}

def create_invoice(order):
    payload = {
        # Your own order id: a retry after a timeout returns the invoice
        # the first attempt created instead of issuing a second one.
        "external_reference": order["id"],
        "issue_date": order["date"],
        "items": order["items"],
    }
    for attempt in range(5):
        try:
            res = requests.post(f"{API}/invoices", json=payload, headers=HEADERS, timeout=60)
        except requests.RequestException:
            time.sleep(2 ** attempt)          # network error: same payload, try again
            continue
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", "5")))
            continue
        if res.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        return res.json()                     # 200/201, or a 4xx to fix, not retry
    raise RuntimeError("WonderFatoora API unavailable, will retry later")

async function createInvoice(order) {
  const payload = {
    external_reference: order.id, // safe to retry
    issue_date: order.date,
    items: order.items,
  };
  for (let attempt = 0; attempt < 5; attempt++) {
    let res;
    try {
      res = await fetch("https://fatoora.tw.sa/api/v1/invoices", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.WONDERFATOORA_API_KEY}`,
          "Content-Type": "application/json",
          Accept: "application/json",
        },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(60_000),
      });
    } catch {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 5) * 1000));
      continue;
    }
    if (res.status >= 500) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    return res.json(); // 200/201, or a 4xx to fix rather than retry
  }
  throw new Error("WonderFatoora API unavailable, retry later");
}

{
  "issue_date": "2026-11-03",
  "currency": "USD",
  "exchange_rate": 3.75,
  "customer": { "name": "Example Inc.", "country": "US" },
  "items": [{
    "description": "Software licence (export of services)",
    "quantity": 1,
    "unit_price": 400,
    "vat_rate": 0,
    "vat_exemption_code": "VATEX-SA-33"
  }]
}