لم تُترجم هذه الصفحة بعد
تعرض هذه الصفحة النص الإنجليزي حتى تصدر ترجمتها.
Worked example: key to cleared invoice¶
Steps 1 to 7, the simplified invoice and the credit note below were run on 2026-10-04 against the demo organisation on the sandbox, in this order. The bodies are what came back, with ids shortened. The demo organisation's VAT number is 300075588700003, ZATCA's sample number, which matches the one certificate the sandbox signs with. That is why its standard invoice clears. Steps 0 and 8 come from an earlier run, on 2026-09-27, with a throwaway key.
The Quickstart explains each step; this page shows the wire.
The interactive reference for every endpoint here is Swagger UI on the sandbox gateway, with an Authorize button that takes a clix_ key:
https://sandbox.api.goclix.ai/v1/api/integrations/docs Swagger UI
https://sandbox.api.goclix.ai/v1/api/integrations/openapi.json OpenAPI 3 document
Both are public. Point a client generator at the JSON; use the UI to try a call with your own key.
sequenceDiagram
participant Admin as Admin, in the app
participant App as Your system
participant Clix
participant ZATCA
Admin->>Clix: API Keys, Create key
Clix-->>Admin: key shown once
App->>Clix: 1 GET /api/usage/current/
App->>Clix: 2 GET reference data
App->>Clix: 3 GET /api/devices/, /api/buyers/, /api/items/
App->>Clix: 4 POST /api/invoices/preview/
Clix-->>App: 201 computed invoice
App->>Clix: 5 POST /api/invoices/
Clix-->>App: 202 location
Clix->>ZATCA: clearance
ZATCA-->>Clix: verdict
App->>Clix: 6 GET location (poll)
Clix-->>App: zatca_response_status
App->>Clix: 7 GET pdf-a3
Admin->>Clix: 8 Revoke
0. Create the key¶
From the 2026-09-27 run, with a throwaway key.
In the app, an Admin opens API Keys, clicks Create key, enters a Key name and an Access level (Create and view invoices is the default), and clicks Create key. The Copy your key now dialog shows the key once; I have stored it closes it. Steps with screenshots: API keys.
Every call below sends it as:
The 12-character prefix clix_CdHmGYM is the key's public name; it appears in listings and in the revoke dialog and is safe to log. The 2026-10-04 calls below used the demo organisation's key, written here as clix_….
1. Check the key and the plan¶
200, with these headers and body:
{
"month": "2026-10-01",
"subscribed_plan": "demo",
"invoices_used": 3,
"invoices_limit": 200,
"api_calls_used": 0,
"api_calls_limit": 0,
"public_api_validations_used": 0,
"public_api_validations_limit": -1,
"grace_used": false,
"grace_exceeded": false,
"invoices_allowed": true,
"plan_name": "Demo"
}
| Field | Type | Meaning |
|---|---|---|
month |
date | first day of the current month in Riyadh time (Asia/Riyadh) |
subscribed_plan, plan_name |
string | plan slug and display name |
invoices_used, invoices_limit |
int | invoices submitted this month, and the allowance; -1 is unlimited |
api_calls_used, api_calls_limit |
int | always 0; API calls are not metered |
public_api_validations_used, public_api_validations_limit |
int | calls to the public tools this month; -1 is unlimited |
grace_used, grace_exceeded |
bool | whether the 10 percent grace above the limit is in use or spent |
invoices_allowed |
bool | the one field to branch on before a create |
With a wrong or revoked key, the same call returns 401:
2. Read the codes¶
curl -s "$CLIX_API/api/invoices/vat-categories/" -H "Authorization: Bearer $CLIX_KEY"
curl -s "$CLIX_API/api/invoices/invoice-type-codes/" -H "Authorization: Bearer $CLIX_KEY"
Each is a map keyed by the enum name, never a list. The first entry of each, verbatim, and the other keys:
{"STANDARD_RATED": {"code": "S", "description": "Standard Rated", "description_ar": "خاضع للنسبة الأساسية"},
"ZERO_RATED": {…}, "EXEMPT_FROM_VAT": {…}, "NOT_SUBJECT_TO_VAT": {…}}
{"TAX_INVOICE": {"code": 388, "description": "Tax Invoice", "description_ar": "فاتورة ضريبية"},
"CREDIT_NOTE": {…}, "DEBIT_NOTE": {…}, "ADVANCE_PAYMENT_INVOICE": {…}}
code is a string for VAT categories and an integer for invoice types and payment means (/api/invoices/payment-means-types/). Full lists: Reference data.
3. Find the device, the buyer and an item¶
The three lists come back as an object with a named list inside, not as a bare array: devices, buyers, items.
{
"devices": [
{
"counter": 3,
"common_name": "Clix Demo till",
"serial_number": "1-AZMX|2-V1|3-6107f3ee-…",
"location": "Riyadh HQ",
"unit_name": "https://clix.azmx.sa",
"industry": "Design",
"invoice_type": "1100",
"business_type": "BOTH",
"seller_id": "4d735e52-…",
"device_id": "6107f3ee-…",
"created_at": "2026-10-04",
"updated_at": "2026-10-04",
"created_by": "[email protected]",
"CSIDCertificateData": {"not_valid_before": "2026-10-04T11:19:27Z", "not_valid_after": "2031-10-03T21:00:00Z", "days_until_expiry": 1825, "expiry_status": "valid"},
"PSIDCertificateData": {"not_valid_before": "2024-01-11T09:19:30Z", "not_valid_after": "2029-01-09T09:19:30Z", "days_until_expiry": 827, "expiry_status": "valid"},
"ccsid_status": "ISSUED",
"pcsid_status": "ISSUED",
"device_status": "pcsid_generated",
"branch_id": null,
"branch_name": null,
"is_branch_device": false,
"branch_link_status": "not_requested",
"pending_branch_id": null,
"pending_branch_name": null
}
],
"total": 1, "num_pages": 1, "current_page": 1,
"total_active_devices": 1, "total_ccsid_expired": 0, "total_pcsid_expired": 0,
"total_active": 1, "total_expiring_soon": 0, "total_expired": 0, "total_unknown": 0
}
| Field | Use it for |
|---|---|
device_id |
the device of the invoice; the field is not called uuid |
seller_id |
the seller of the invoice; same row, so one read gives both |
device_status |
pcsid_generated is the Active connection in the app; only such a device can issue |
invoice_type |
1000 standard only, 0100 simplified only, 1100 both |
counter |
the number of invoices this device has signed; a new device reads "No invoices generated yet." instead of 0 |
PSIDCertificateData.not_valid_after |
when the production certificate expires |
{
"buyers": [
{
"uuid": "a94027ce-…",
"buyer_name": "Al Noor Trading",
"buyer_name_arabic": "",
"is_from_saudi_arabia": true,
"is_vat_registered": true,
"is_active": true,
"vat_registration_number": "399999999900003",
"additional_buyer_id": [{"type_id": "CRN", "id_number": "1010010000"}],
"street": "King Fahd Road", "building_number": "1234", "district": "Al Olaya",
"city": "Riyadh", "postal_code": "12345", "province_state": "Riyadh", "country": "SA",
"business_type": {"uuid": "7d9e23b5-…", "code": "1000", "description": "B2B", "type_ar": "شركة إلى شركة"},
"industry": {"uuid": "0297f443-…", "name": "Design", "name_ar": "تصميم", "is_active": true},
"seller": "Clix Demo",
"created_at": "2026-10-04T11:43:58.547Z",
"…": "contact, phone, e-mail, logo, map and VAT-group fields, empty here"
}
],
"total": 1, "num_pages": 1, "current_page": 1
}
A standard invoice needs a buyer with a vat_registration_number; this one has it.
The demo organisation has no catalogue items, so the invoices below write their lines out with form_lines. Note the paging keys differ: items say page and page_size, devices and buyers say current_page.
4. Preview¶
The body, invoice.json, exactly as sent:
{
"device": "6107f3ee-…",
"seller": "4d735e52-…",
"buyer": "a94027ce-…",
"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": "Docs verification 1791114314"}],
"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": []
}
| Field | Type | Rule |
|---|---|---|
device, seller, buyer |
uuid strings | from step 3 |
type_code |
int | 388 here; 381 credit and 383 debit notes use this same endpoint |
transaction_code |
string | 0100000 standard, 0200000 simplified, 0100100 standard export; must suit the device's invoice_type |
issue_date, issue_time |
YYYY-MM-DD, HH:MM:SS |
set by the server, which discards what you send: this body carried 2026-10-01 and 10:00:00, and the preview came back 2026-10-04 15:39:40, Riyadh time. Required keys on release 0.108.7, optional after it |
supply_date, supply_end_date |
YYYY-MM-DD |
yours: when the goods or service were delivered |
currency, exchange_rate |
string, number | SAR and exactly 1 for a domestic sale |
payment_means_type_code |
string | "10" cash; "30" credit transfer also needs payment terms, which come from the reason in reason_id |
form_lines[] |
objects | the lines you write; lines stays []. Send one or the other, never both |
form_lines[].item_name |
string | 4 to 50 characters |
form_lines[].item_net_price |
string decimal | greater than zero, at most two decimals |
form_lines[].vat_category_code, vat_rate |
S/Z/E/O, number |
every category but S needs both vat_exemption_reason_code and vat_exemption_reason_text |
reason_id, original_invoice_reference, prepaid_invoices |
for credit and debit notes and advance payments; empty here |
is_sample_invoice and document_level_charges are not input fields; Clix sets both, and this body leaves them out. What each of these constants means and what else it may be: Codes and constants.
curl -s -X POST "$CLIX_API/api/invoices/preview/" -H "Authorization: Bearer $CLIX_KEY" \
-H "Content-Type: application/json" -d @invoice.json
201:
{
"message": "Invoice preview created successfully",
"invoice": {
"uuid": "61514d6c-…",
"ref_num": "161-4",
"counter": 4,
"device": "6107f3ee-…",
"buyer": "a94027ce-…",
"issue_date": "2026-10-04",
"issue_time": "15:39:40",
"invoice_total_amount_without_vat": "100.00",
"invoice_total_vat_amount": "15.00",
"invoice_payable_amount": "115.00",
"is_sample_invoice": false,
"…": "lines, vat_breakdown, qrcode, complete_invoice_xml, invoice_hash_bytes and the other fields of a full invoice"
}
}
ref_num is the number the next invoice will take, not a reservation: the simplified invoice created a minute later took 161-4. The preview uuid is not an invoice: GET /api/invoices/61514d6c-…/ answers 404 {"message": "Invoice not found"}.
A preview runs the same validation as a create. Two refusals, both 400, sent as previews of this body with one field changed:
{"message": ["invoice_schema_data: Value error, Missing required fields: device. Optional fields not provided: reason_id"]}
The first came from device: null; the second from payment_means_type_code: "30" with no reason_id. Payment terms are the description of the reason named in reason_id; a payment_terms key in the body is ignored.
5. Create¶
curl -s -X POST "$CLIX_API/api/invoices/" -H "Authorization: Bearer $CLIX_KEY" \
-H "Content-Type: application/json" -d @invoice.json
202, verbatim but for the task_id:
{
"message": "Tax Invoice creation request completed successfully, it will be cleared or reported to ZATCA soon",
"location": "/api/invoices/5722b9f8-…/",
"task_id": "…"
}
Keep location. task_id has no endpoint.
In the 2026-09-27 run, sending the identical body again inside five minutes answered 400:
{"message": "You just submitted an invoice with the exact same data. Please wait 295 seconds before retrying."}
6. Poll¶
200. The response carries every field of the invoice; these are the ones a poller reads:
{
"uuid": "5722b9f8-…",
"ref_num": "161-3",
"issue_date": "2026-10-04",
"issue_time": "14:45:15",
"zatca_submitted_at": "2026-10-04T11:45:16.233Z",
"zatca_response_received_at": "2026-10-04T11:45:16.801Z",
"zatca_response_status": "CLEARED",
"zatca_response_code": 200,
"zatca_response_data": {
"clearedInvoice": "PD94bWwgdmVyc2lvbj0i…",
"clearanceStatus": "CLEARED",
"validationResults": {
"status": "PASS",
"infoMessages": [
{"code": "XSD_ZATCA_VALID", "type": "INFO", "status": "PASS", "category": "XSD validation",
"message": "Complied with UBL 2.1 standards in line with ZATCA specifications"}
],
"errorMessages": [],
"warningMessages": []
}
},
"invoice_status": "CLEARED",
"payment_status": "Pending",
"invoice_pdf_url": "https://…/300075588700003_20261004T144515_161-3.pdf",
"qr_code": "…",
"share_link": null,
"invoice_total_amount_without_vat": "100.00",
"invoice_total_vat_amount": "15.00",
"invoice_payable_amount": "115.00",
"vat_breakdown": [ { "vat_category_code": "S", "vat_rate": 15.0, "vat_category_taxable_amount": "100.00", "vat_category_tax_amount": "15.00", "vat_exemption_reason_code": "", "vat_exemption_reason_text": "" } ],
"lines": [ { "invoice_line_id": "3fac3c63-…", "item_name": "Consulting", "invoiced_quantity": 1.0, "item_net_price": "100.00", "line_net_amount": "100.00", "vat_line_amount": "15.00", "…": "…" } ],
"balance": { "paid": "0.00", "credit_notes": "0.00", "debit_notes": "0.00", "debit_notes_paid": "0.00", "remaining": "115.00", "payment_status": "Pending" },
"buyer": { "uuid": "a94027ce-…", "buyer_name": "Al Noor Trading", "…": "…" },
"seller": "4d735e52-…",
"device": "6107f3ee-…"
}
| Field | Meaning |
|---|---|
zatca_response_status |
CLEARED, REPORTED, NOT_CLEARED, NOT_REPORTED; stop polling on any of them. No response means ZATCA gave no answer Clix recognises; the invoice is still undecided |
zatca_response_code |
ZATCA's HTTP status; 200 accepted, 202 accepted with warnings, 400 rejected |
zatca_response_data.validationResults.errorMessages[] |
why it was rejected, each with code, category, message; warningMessages[] are accepted-with-warnings; infoMessages[] are the checks that passed |
zatca_response_data.clearedInvoice |
the signed XML, base64, on a cleared invoice; null on rejection |
invoice_pdf_url |
set once the invoice is final |
payment_status |
Pending, Partially Paid, Paid; moved by the payments you record, not by ZATCA |
lines[].invoice_line_id |
the line a credit or debit note points at |
buyer, seller, device |
buyer comes back as an object; seller and device as uuid strings |
ZATCA answered 0.6 seconds after submission. A rejected invoice cannot be resubmitted: PATCH /api/invoices/{invoice_id}/clearance-reporting/ answers 409 once ZATCA has answered, rejection included. Fix the cause and create a new invoice.
With your own VAT number on the sandbox, expect NOT_CLEARED
The sandbox signs every invoice with one shared certificate, issued for ZATCA's sample VAT number. An organisation with any other VAT number gets NOT_CLEARED, zatca_response_code 400, and this error. The 2026-09-27 run got it:
{"code": "certificate-permissions",
"message": "User only allowed to use the vat number that exists in the authentication certificate"}
On app.goclix.ai the same body from an active device clears.
7. PDF¶
curl -s "$CLIX_API/api/invoices/5722b9f8-…/pdf-a3/" -H "Authorization: Bearer $CLIX_KEY" -o 161-3.pdf
200, with these headers, and 45,389 bytes of PDF that start %PDF-1.7, with the ZATCA XML embedded:
Content-Type: application/pdf
Content-Disposition: attachment; filename="300075588700003_20261004T144515_161-3.pdf"
Content-Length: 45389
Before the invoice is final, and on a rejected invoice, the same call answers 404. The 2026-09-27 run's rejected invoice got:
A simplified invoice¶
A simplified invoice, to a consumer, takes transaction_code "0200000" and no buyer. ZATCA reports it instead of clearing it. The body, simplified.json, exactly as sent; it leaves out issue_date and issue_time, which the server sets:
{
"device": "6107f3ee-…",
"seller": "4d735e52-…",
"type_code": 388,
"transaction_code": "0200000",
"supply_date": "2026-10-04",
"supply_end_date": "2026-10-04",
"currency": "SAR",
"exchange_rate": 1,
"payment_means_type_code": "10",
"add_prepaid_amount": false,
"reason_id": null,
"notes": [{"language_id": "en", "note": "Docs worked example, simplified"}],
"form_lines": [
{
"item_name": "Coffee, large",
"invoiced_quantity": 2,
"invoiced_quantity_unit_of_measure": "PCE",
"item_net_price": "10.00",
"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": []
}
curl -s -X POST "$CLIX_API/api/invoices/" -H "Authorization: Bearer $CLIX_KEY" \
-H "Content-Type: application/json" -d @simplified.json
202:
{
"message": "Tax Invoice creation request completed successfully, it will be cleared or reported to ZATCA soon",
"location": "/api/invoices/75d33fb8-…/",
"task_id": "…"
}
Ten seconds later, GET /api/invoices/75d33fb8-…/ answered 200:
{
"uuid": "75d33fb8-…",
"ref_num": "161-4",
"transaction_code": "0200000",
"issue_date": "2026-10-04",
"issue_time": "15:39:50",
"zatca_submitted_at": "2026-10-04T12:39:50.873Z",
"zatca_response_received_at": "2026-10-04T12:39:51.413Z",
"zatca_response_status": "REPORTED",
"zatca_response_code": 202,
"zatca_response_data": {
"reportingStatus": "REPORTED",
"validationResults": {
"status": "WARNING",
"infoMessages": [
{"code": "XSD_ZATCA_VALID", "type": "INFO", "status": "PASS", "category": "XSD validation",
"message": "Complied with UBL 2.1 standards in line with ZATCA specifications"}
],
"errorMessages": [],
"warningMessages": [
{"code": "certificate-issuer-name", "type": "WARNING", "status": "WARNING", "category": "CERTIFICATE_ERRORS",
"message": "X509Certificate (CCSID / PCSID) used for signing is not valid certificate (CCSID / PCSID) for this VAT Registration Number."},
{"code": "invalid-signing-certificate", "type": "WARNING", "status": "WARNING", "category": "CERTIFICATE_ERRORS",
"message": "X509Certificate (CCSID / PCSID) used for signing is not valid certificate (CCSID / PCSID) for this VAT Registration Number."}
]
}
},
"invoice_status": "REPORTED",
"invoice_pdf_url": "https://…/300075588700003_20261004T153950_161-4.pdf",
"invoice_total_amount_without_vat": "20.00",
"invoice_total_vat_amount": "3.00",
"invoice_payable_amount": "23.00",
"buyer": "",
"share_link": null,
"…": "lines, vat_breakdown, balance and the rest, as in step 6"
}
Three differences from the standard invoice:
zatca_response_datacarriesreportingStatusand noclearedInvoice. ZATCA reports a simplified invoice; it does not return a signed copy.zatca_response_code202withstatusWARNING: ZATCA accepted the invoice with two warnings, both about the signing certificate.REPORTEDis final; the warnings need no action on this invoice.buyeris an empty string, notnulland not an object.
invoices_used in GET /api/usage/current/ went from 3 to 4.
A credit note¶
A credit note is a POST /api/invoices/ with type_code 381, the original's uuid in original_invoice_reference, the original line's invoice_line_id on each line, and a reason_id. The note keeps the original's buyer, device, currency and transaction code.
First, the reason:
{
"reasons": [
{"uuid": "d95793fa-…", "description": "Additional charge after the original invoice",
"reason_type": {"code": 383, "value": "DEBIT_NOTE"}, "is_active": true},
{"uuid": "c4846817-…", "description": "Goods returned by the customer",
"reason_type": {"code": 381, "value": "CREDIT_NOTE"}, "is_active": true}
],
"total": 2, "num_pages": 1, "current_page": 1
}
Take the row whose reason_type.code is 381. Then the note, against 161-3:
{
"device": "6107f3ee-…",
"seller": "4d735e52-…",
"buyer": "a94027ce-…",
"type_code": 381,
"transaction_code": "0100000",
"supply_date": "2026-10-04",
"supply_end_date": "2026-10-04",
"currency": "SAR",
"exchange_rate": 1,
"payment_means_type_code": "10",
"add_prepaid_amount": false,
"reason_id": "c4846817-…",
"notes": [{"language_id": "en", "note": "Docs worked example, credit note"}],
"form_lines": [
{
"item_name": "Consulting",
"invoiced_quantity": 1,
"invoiced_quantity_unit_of_measure": "PCE",
"item_net_price": "100.00",
"vat_category_code": "S",
"vat_rate": 15.0,
"vat_exemption_reason_code": "",
"vat_exemption_reason_text": "",
"invoice_line_id": "3fac3c63-…"
}
],
"lines": [],
"original_invoice_reference": ["5722b9f8-…"],
"prepaid_invoices": [],
"document_level_allowances": []
}
POST /api/invoices/ answered 202:
{
"message": "Credit Note creation request completed successfully, it will be cleared or reported to ZATCA soon",
"location": "/api/invoices/4a20bee8-…/",
"task_id": "…"
}
The first poll, a second later:
{
"ref_num": "161-5",
"type_code": 381,
"payment_terms": "Goods returned by the customer",
"lines": [
{"invoice_line_id": "4bca88e7-…", "original_invoice_line_id": "3fac3c63-…",
"item_name": "Consulting", "invoiced_quantity": 1.0,
"item_net_price": "100.00", "line_net_amount": "100.00", "vat_line_amount": "15.00"}
],
"invoice_total_line_net_amount": "100.00",
"invoice_total_vat_amount": "15.00",
"invoice_payable_amount": "115.00",
"original_invoices": [{"ref_num": "161-3", "type_code": 388, "zatca_response_status": "CLEARED", "…": "…"}],
"zatca_response_code": 200,
"zatca_response_status": "CLEARED",
"zatca_response_data": {"clearedInvoice": "PD94bWwg…", "clearanceStatus": "CLEARED",
"validationResults": {"status": "PASS", "errorMessages": [], "warningMessages": []}}
}
A credit note line credits at most the original price
This run is a return: item_net_price equals the original line's 100.00. Send a lower price, above 0, and the line is a price correction: it credits invoiced_quantity × that price, the amount off per unit. Send the original line's vat_category_code and vat_rate. item_name and the unit of measure are copied from the original line, whatever you send.
Three limits, each a 400, checked to 2 decimals. Previews on the sandbox on 2026-10-05 answered:
-
A price above the original (120.00 against 100.00):
-
A different VAT category or rate (
vat_rate5 against 15): -
More money than is left on the original line. Returns and corrections on a line together may not exceed its value. After a 30.00 correction on 161-8 (1 × 100.00), a full return is refused when you create it:
{"message": "Amount for line <invoice_line_id> exceeds what is left to credit. Line value: 100.00, Already credited: 30.00, Left to credit: 70.00, Requested: 100.00."}The preview does not check this limit;
POST /api/invoices/does.
A correction uses up no quantity: the units can still be returned, up to the money left. It takes no share of the original's document discount. A debit note is different: it keeps the price you send (a preview of a 50.00 debit note against the same line came back 50.00).
On the demo organisation, 161-9 took 30.00 off 161-8's line (payable 34.50, CLEARED), and 161-10 took the remaining 70.00 (payable 80.50, CLEARED).
payment_terms carries the reason's description; that is the reason ZATCA reads. Without a reason_id, Clix refuses the note before it reaches ZATCA:
{"message": "Reason for issuance of credit / debit note as per the VAT Implementing Regulation is missing"}
A note line without invoice_line_id is refused too, for credit and debit notes alike:
{"message": ["invoice_schema_data: Value error, For CN/DN, 'invoice_line_id' is required in each line."]}
Where each field comes from:
| Field | Source |
|---|---|
reason_id |
uuid of an active row in GET /api/sellers/reasons/?is_active=true whose reason_type.code is 381 (383 for a debit note). An Admin sets reasons up under Invoices → Adjust Reasons; see Credit and debit notes |
original_invoice_reference |
["<uuid of the cleared or reported invoice>"], from its location |
form_lines[].invoice_line_id |
lines[].invoice_line_id of that invoice, from step 6. A line of any other invoice answers 400 "Referenced invoice line … does not exist in the original invoices." |
form_lines[].invoiced_quantity |
on a credit note, the units to return, or the units a price correction covers. A correction uses up no quantity |
form_lines[].item_net_price |
on a credit note, above 0 and at most the original line's price: equal for a return, lower for a price correction (the amount off per unit); on a debit note, the extra amount per unit |
form_lines[].vat_category_code, vat_rate |
on a credit note, exactly the original line's values; on a debit note, the VAT of the extra amount |
8. Revoke¶
From the 2026-09-27 run, with a throwaway key. Nothing was revoked on 2026-10-04.
In the app, API Keys, Revoke on the row, Revoke key in the Revoke this key? dialog. The very next call answered:
with status 401, within a second of the click.
What was not run¶
A created debit note (type_code 383; only previewed, see A credit note), invoice comments (POST /api/invoices/{invoice_id}/notes/), client creation (POST /api/onboarding/organizations/clients/), item creation (POST /api/items/) and resubmission (PATCH …/clearance-reporting/) are on the surface and in Swagger but were not exercised in this run. Their schemas are in the OpenAPI document above.
Related¶
- Quickstart, the same steps with the reasoning
- API reference, the full surface and the Swagger links
- Errors and rate limits
- Public tools, the VAT calculator example, also run live