لم تُترجم هذه الصفحة بعد

تعرض هذه الصفحة النص الإنجليزي حتى تصدر ترجمتها.

Try the API¶

Send an invoice as JSON and watch ZATCA clear it, all in your browser. It takes about five minutes. You don't need an account or an API key of your own.

A shared demo on the ZATCA sandbox

Every visitor uses the same demo organisation. Anyone can see the invoices you create. Use made-up data only.
The invoices are not legally valid. They go to ZATCA's sandbox, not to ZATCA production.
The key may change. If it stops working, reload this page for the current one.
The demo creates up to 200 invoices a month in total. Once they're used up, creating is refused until the next month. Reading still works.
This sandbox demo terminates TLS on a server outside Saudi Arabia. Production Clix keeps your data in the Kingdom.

The demo key¶

clix_fxC9tzt_I7fiKMpvTQbU5CNiL647PQu9ssvE3C4jAlPyw3sf3hY

It has the CreateInvoice role. It can read and create invoices, clients and items. It cannot manage users, devices, billing or keys. See Authentication.

What you will do¶

flowchart LR
    A["1. Authorize<br/>paste the key"] --> B["2. POST /api/invoices/<br/>202 + location"]
    B --> C["3. GET the invoice<br/>CLEARED"]
    C --> D["4. GET …/pdf-a3/<br/>the PDF"]

1. Open Swagger UI and authorize¶

Open Swagger UI on the sandbox.
Click Authorize.
Paste the demo key as it is, starting with clix_. Don't type Bearer in front: Swagger UI adds it.
Click Authorize, then Close.

To check that the key works, open GET /api/usage/current/, click Try it out, then Execute. A 200 shows the demo plan and how many invoices it has used this month.

2. Create an invoice¶

Open POST /api/invoices/ and click Try it out. Replace the request body with this:

{
  "device": "6107f3ee-938d-4fa0-adc9-420e7bc2b404",
  "seller": "4d735e52-b7b6-4a3d-b5df-a34acdc84d2b",
  "buyer": "a94027ce-551e-4bda-81c7-927ea5e0db28",
  "type_code": 388,
  "transaction_code": "0100000",
  "issue_date": "2026-10-01",
  "issue_time": "10:00:00",
  "supply_date": "2026-10-01",
  "supply_end_date": "2026-10-01",
  "currency": "SAR",
  "exchange_rate": 1,
  "payment_means_type_code": "10",
  "add_prepaid_amount": false,
  "reason_id": null,
  "notes": [{ "language_id": "en", "note": "Demo by YOUR-NAME" }],
  "form_lines": [
    { "item_name": "Consulting", "invoiced_quantity": 1,
      "invoiced_quantity_unit_of_measure": "PCE", "item_net_price": "100",
      "vat_category_code": "S", "vat_rate": 15.0,
      "vat_exemption_reason_code": "", "vat_exemption_reason_text": "" }
  ],
  "lines": [], "original_invoice_reference": [], "prepaid_invoices": [],
  "document_level_allowances": []
}

Change the note (Demo by YOUR-NAME) to anything you like before you click Execute. Clix refuses an invoice identical to one sent in the last five minutes, and other visitors may have just sent this exact body.

This is a standard tax invoice (388, 0100000) for one line: 100 SAR of consulting at 15% VAT, sold to the demo client, Al Noor Trading. You don't need to change the dates. Clix stamps the issue date and time from its own clock. Quickstart → Build the payload explains every field.

Expect 202 Accepted:

{
  "message": "Tax Invoice creation request completed successfully, it will be cleared or reported to ZATCA soon",
  "task_id": "…",
  "location": "/api/invoices/8f3c…/"
}

Copy the invoice id from location. That's the part between /api/invoices/ and the last /.

3. Watch ZATCA clear it¶

Open GET /api/invoices/{invoice_id}/, click Try it out, paste the id, and click Execute.

Look at zatca_response_status. It reaches CLEARED within a few seconds. Click Execute again until it does.

In the same response:

Field	What it shows
`zatca_response_status`	ZATCA's decision: `CLEARED`
`zatca_response_data`	ZATCA's full answer, including any warnings
`invoice_total_line_net_amount`, `invoice_total_vat_amount`, `invoice_payable_amount`	Net, VAT and the amount payable, calculated by Clix
`invoice_pdf_url`	Set once the PDF is ready

4. Download the PDF¶

Open GET /api/invoices/{invoice_id}/pdf-a3/, paste the same id, and click Execute. Then click Download file.

The file is a PDF/A-3 with the ZATCA QR code printed on it and the signed UBL XML embedded inside. That's the archive copy ZATCA requires.

What just happened¶

Your one POST did all of this:

Clix checked the invoice against ZATCA's business rules.
It calculated the line, VAT and invoice totals.
It built the UBL 2.1 XML.
It signed the XML with the demo organisation's ZATCA certificate and added the QR code.
It sent the invoice to ZATCA for clearance, and kept ZATCA's answer.
It produced the PDF/A-3 and stored everything.

Your own system only sends JSON and reads back the status.

If something goes wrong¶

Response	Cause	What to do
`400` "You just submitted an invoice with the exact same data"	Someone sent the same body in the last five minutes	Change the note and send again
`400` with another message	A field in the body is wrong	Paste the body above again, change only the note
`401` "Invalid or revoked API key"	The key has changed	Reload this page and authorize with the new key
`403` about the invoice limit	This month's 200 demo invoices are used up	Try again next month, or get your own key
`429`	More than 200 requests a minute on the demo key	Wait the seconds in `Retry-After`
`NOT_CLEARED` in step 3	ZATCA rejected the invoice	`zatca_response_data.validationResults.errorMessages` says why

Try it with curl instead¶

The same four steps from a terminal

export CLIX_API="https://sandbox.api.goclix.ai/v1"
export CLIX_KEY="clix_fxC9tzt_I7fiKMpvTQbU5CNiL647PQu9ssvE3C4jAlPyw3sf3hY"

# Save the body from step 2 as invoice.json, with your own note, then:
curl -s -X POST "$CLIX_API/api/invoices/" \
  -H "Authorization: Bearer $CLIX_KEY" \
  -H "Content-Type: application/json" \
  -d @invoice.json

# Use the location from the 202:
curl -s "$CLIX_API/api/invoices/8f3c…/" -H "Authorization: Bearer $CLIX_KEY"
curl -s "$CLIX_API/api/invoices/8f3c…/pdf-a3/" -H "Authorization: Bearer $CLIX_KEY" -o invoice.pdf

Without any key¶

The public tools need no key at all. They validate an invoice against every ZATCA rule, calculate VAT, decode a ZATCA QR code, and render an invoice as UBL XML or PDF.

Use the API for real¶

The demo key is for trying the API. To connect your own systems:

Choose a plan with API access.
Register your ZATCA device in Clix.
Create one API key for each system that calls Clix.

Then follow the Quickstart. The Worked example shows every request and response from one full run.