{ "info": { "_postman_id": "edd2c83e-2c77-5f88-93ba-229175bce6ef", "name": "Clix Integration API (sandbox)", "description": "Every invoice scenario of the Clix Integration API, ready to send to the sandbox.\n\n1. Import this collection and the `Clix sandbox` environment, and select the environment.\n2. Paste your `clix_…` key into `apiKey` in the environment. A sandbox account on a plan with API access issues one under **API Keys**.\n3. Send the folders in order. Test scripts fill `deviceId`, `sellerId`, `businessTypeId`, `industryId`, `reasonId`, `buyerId`, `itemId` and `invoiceId` as you go.\n\nThe sandbox terminates TLS on a server outside Saudi Arabia. Send only test data. Production Clix keeps your data in the Kingdom.\n\nDo not use the Runner to retry invoice creation: poll the invoice before you send a create again.\n\nGuide: [https://docs.goclix.ai/developers/postman/](https://docs.goclix.ai/developers/postman/)", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// Today's date in Riyadh (UTC+3), for supply_date and supply_end_date.", "const riyadh = new Date(Date.now() + 3 * 60 * 60 * 1000);", "pm.collectionVariables.set('today', riyadh.toISOString().slice(0, 10));", "// A fresh test VAT number for each client you create: 15 digits, first and last '3'.", "// Test data only. It belongs to nobody; Clix refuses a second client with the same number.", "let middle = '';", "for (let i = 0; i < 13; i++) { middle += Math.floor(Math.random() * 10); }", "pm.collectionVariables.set('testVatNumber', '3' + middle + '3');" ] } } ], "variable": [ { "key": "baseUrl", "value": "https://sandbox.api.goclix.ai/v1", "type": "string", "description": "The sandbox gateway, including /v1. In production, the host that comes with your production key." }, { "key": "deviceId", "value": "", "type": "string", "description": "device_id of an Active device, from GET /api/devices/." }, { "key": "sellerId", "value": "", "type": "string", "description": "seller_id from the same device row." }, { "key": "buyerId", "value": "", "type": "string", "description": "uuid of a Saudi B2B client, from Create a client or GET /api/buyers/." }, { "key": "exportBuyerId", "value": "", "type": "string", "description": "uuid of a foreign client, from Create a foreign client." }, { "key": "itemId", "value": "", "type": "string", "description": "uuid of a catalogue item, from Create an item or GET /api/items/." }, { "key": "invoiceId", "value": "", "type": "string", "description": "Id of the last tax invoice you issued, saved from location." }, { "key": "invoiceLineId", "value": "", "type": "string", "description": "invoice_line_id of that invoice's first line, saved by Get the invoice." }, { "key": "noteId", "value": "", "type": "string", "description": "Id of the last credit or debit note you issued." }, { "key": "reasonId", "value": "", "type": "string", "description": "uuid of an active credit-note reason, from GET /api/sellers/reasons/." }, { "key": "debitReasonId", "value": "", "type": "string", "description": "uuid of an active debit-note reason, from GET /api/sellers/reasons/." }, { "key": "businessTypeId", "value": "", "type": "string", "description": "uuid of the B2B business type, from GET /api/business-types/." }, { "key": "industryId", "value": "", "type": "string", "description": "id of an industry, from GET /api/industries/." }, { "key": "today", "value": "", "type": "string", "description": "Set before every request: today's date in Riyadh." }, { "key": "testVatNumber", "value": "", "type": "string", "description": "Set before every request: a made-up 15-digit VAT number for a test client." } ], "item": [ { "id": "5008ee28-1d9c-5a8b-adf8-81e106ad9d1b", "name": "0 Check", "description": "Confirm the key works and find your signing device. Send these first.", "item": [ { "id": "2dd43980-a78a-5f19-afd1-b8ea542704e5", "name": "Usage this month", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/usage/current/", "host": [ "{{baseUrl}}" ], "path": [ "api", "usage", "current" ] }, "description": "Confirms the key, the plan and the organisation in one call.\n\nExpect `200` with your plan and invoice counters. Branch on `invoices_allowed` before you create anything. A `401` means the key is wrong or revoked; a `403` *API access is not included in your current plan* means the plan has no API access.\n\nDocs: [https://docs.goclix.ai/developers/quickstart/#1-check-the-key-works](https://docs.goclix.ai/developers/quickstart/#1-check-the-key-works)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "c7d131f3-eb54-58ed-98da-a5ac7b779da1", "name": "List devices", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/devices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "devices" ] }, "description": "Lists the organisation's ZATCA connections (devices). One row gives two ids: `device_id` for `device` and `seller_id` for `seller`.\n\nThe test script takes the first device whose `device_status` is `pcsid_generated` (the app's **Active**) and saves its ids to `deviceId` and `sellerId`, but only when those variables are empty. To use another device, paste its ids yourself.\n\nThe device's `invoice_type` decides what it may issue: `1000` standard only, `0100` simplified only, `1100` both.\n\nDocs: [https://docs.goclix.ai/developers/quickstart/#3-build-the-payload](https://docs.goclix.ai/developers/quickstart/#3-build-the-payload)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "const devices = (pm.response.json().devices || []);", "const active = devices.find(d => d.device_status === 'pcsid_generated');", "if (!active) {", " console.warn('No Active device (device_status pcsid_generated). Connect one to ZATCA in the app first.');", "} else {", " if (!pm.variables.get('deviceId')) { setVar('deviceId', active.device_id); console.log('deviceId = ' + active.device_id); }", " if (!pm.variables.get('sellerId')) { setVar('sellerId', active.seller_id); console.log('sellerId = ' + active.seller_id); }", "}" ] } } ] } ] }, { "id": "44cdcf53-e61a-5b50-aeaa-968aa9eee21f", "name": "1 Reference data", "description": "The code lists an invoice uses, and the ids a client, an item or a note needs.", "item": [ { "id": "9a2e16e1-92a8-5ddc-b989-617a84fc8097", "name": "VAT categories", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/vat-categories/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "vat-categories" ] }, "description": "`S`, `Z`, `E`, `O`, keyed by enum name.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "1acefff6-8d28-534f-9037-c17779b96190", "name": "VAT rates and reasons per category", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/vat/?vat_category_code=Z", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "vat" ], "query": [ { "key": "vat_category_code", "value": "Z", "description": "Optional. Leave out for all four." } ] }, "description": "What each category permits: its rates and its exemption reasons.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "1353ed0a-098c-584d-bb9c-cdb6ac224829", "name": "VAT exemption reasons", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/vat-exemption-reasons/?category=Z", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "vat-exemption-reasons" ], "query": [ { "key": "category", "value": "Z", "description": "Optional. Leave out for all sixteen." } ] }, "description": "The 16 `VATEX-SA-…` codes. Export lines use `VATEX-SA-32` (goods) or `VATEX-SA-33` (services).\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "9bd390b9-1d6f-56be-bb4f-a1df6ce669d3", "name": "Invoice type codes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/invoice-type-codes/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "invoice-type-codes" ] }, "description": "`388` tax invoice, `381` credit note, `383` debit note, `386` advance payment.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "2de32eca-2a0c-5c7c-a736-a639f524bbd4", "name": "Units of measure", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/units-of-measure/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "units-of-measure" ] }, "description": "41 units, such as `PCE`, `KGM`, `LTR`.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "45694bf4-7621-531d-8c8f-3a7ab787d0f2", "name": "Payment means", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/payment-means-types/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "payment-means-types" ] }, "description": "UN/CEFACT 4461 codes. `code` is an integer here; on an invoice send it as a string, `\"10\"`.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "195413d5-363d-5062-aab5-0d81356636ce", "name": "Charge reason codes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/invoice-charges-codes/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "invoice-charges-codes" ] }, "description": "UNTDID 7161 charge reasons. No Arabic field.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "72f98fcf-e6f9-5517-be26-8dd9dc300578", "name": "Allowance reason codes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/invoice-allowances-codes/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "invoice-allowances-codes" ] }, "description": "UNTDID 5189 allowance reasons.\n\nA static map, not a list. Safe to cache for a day.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#the-endpoints](https://docs.goclix.ai/developers/reference-data/#the-endpoints)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "3f188d1e-dd9e-5666-be88-ee05a4e2f175", "name": "Business types", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/business-types/", "host": [ "{{baseUrl}}" ], "path": [ "api", "business-types" ] }, "description": "The three business types, each with a `uuid`. A client's `business_type` and an item's `business_type_category_id` take one of these.\n\nThe test script saves the `uuid` of `B2B` (code `1000`) to `businessTypeId` when it is empty.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#business-types-industries-and-reasons](https://docs.goclix.ai/developers/reference-data/#business-types-industries-and-reasons)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "const b2b = (pm.response.json().business_types || []).find(t => t.code === '1000');", "if (b2b && !pm.variables.get('businessTypeId')) { setVar('businessTypeId', b2b.uuid); console.log('businessTypeId = ' + b2b.uuid); }" ] } } ] }, { "id": "4486272f-f842-5924-a03f-f74e4734b91e", "name": "Industries", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/industries/", "host": [ "{{baseUrl}}" ], "path": [ "api", "industries" ] }, "description": "Active industries. A client's `industry` takes an `id` from here (the field is `id`, not `uuid`).\n\nThe test script saves the first `id` to `industryId` when it is empty. Pick a better match by hand if you like.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#business-types-industries-and-reasons](https://docs.goclix.ai/developers/reference-data/#business-types-industries-and-reasons)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "const first = (pm.response.json().industries || [])[0];", "if (first && !pm.variables.get('industryId')) { setVar('industryId', first.id); console.log('industryId = ' + first.id); }" ] } } ] }, { "id": "cdf490f6-5b32-5a7a-95c5-a8ef9b3fb6d7", "name": "Credit and debit note reasons", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/sellers/reasons/?is_active=true", "host": [ "{{baseUrl}}" ], "path": [ "api", "sellers", "reasons" ], "query": [ { "key": "is_active", "value": "true", "description": "Only active reasons; a note accepts nothing else." } ] }, "description": "Your organisation's own reasons, set up in the app under **Invoices → Adjust Reasons**. The list starts empty.\n\nThe test script saves the first active credit-note reason (`381`) to `reasonId` and the first active debit-note reason (`383`) to `debitReasonId`, when they are empty. The reason's description becomes the note's reason on the ZATCA XML, so give it one.\n\nDocs: [https://docs.goclix.ai/developers/reference-data/#reasons](https://docs.goclix.ai/developers/reference-data/#reasons)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "const reasons = (pm.response.json().reasons || []).filter(r => r.is_active);", "const credit = reasons.find(r => r.reason_type && r.reason_type.code === 381);", "const debit = reasons.find(r => r.reason_type && r.reason_type.code === 383);", "if (credit && !pm.variables.get('reasonId')) { setVar('reasonId', credit.uuid); console.log('reasonId = ' + credit.uuid); }", "if (debit && !pm.variables.get('debitReasonId')) { setVar('debitReasonId', debit.uuid); console.log('debitReasonId = ' + debit.uuid); }", "if (!credit || !debit) { console.warn('Add an active credit-note and debit-note reason under Invoices > Adjust Reasons in the app.'); }" ] } } ] } ] }, { "id": "8a1b2c92-c852-5b19-acd1-5e6d5ce3b5d3", "name": "2 Clients and items", "description": "The buyer is an id, never inline data. Create each client once and keep its id.", "item": [ { "id": "40ec4f0f-db52-50fe-8ae4-eca025895c5e", "name": "Create a client (Saudi B2B, VAT registered)", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/api/onboarding/organizations/clients/", "host": [ "{{baseUrl}}" ], "path": [ "api", "onboarding", "organizations", "clients" ] }, "description": "Creates a standard B2B buyer: a Saudi business with a VAT number. On `201` the test script saves its id from `location` to `buyerId`.\n\nThe body is `multipart/form-data`: one field, `client_data`, holding the client as a JSON string. `{{testVatNumber}}` is a fresh made-up number on every send (15 digits, first and last `3`), because Clix refuses a second client with the same VAT number (`409`). It is test data; send it only to the sandbox.\n\nNeeds `businessTypeId` (the B2B one) and `industryId` from **1 Reference data**. A Saudi client needs a 4-digit building number, a 5-digit postal code, a district and `country` `SA`.\n\nDocs: [https://docs.goclix.ai/developers/api-reference/#clients](https://docs.goclix.ai/developers/api-reference/#clients)", "body": { "mode": "formdata", "formdata": [ { "key": "client_data", "type": "text", "value": "{\"buyer_name\": \"Postman Test Trading\", \"buyer_name_arabic\": \"\", \"business_type\": \"{{businessTypeId}}\", \"industry\": \"{{industryId}}\", \"is_from_saudi_arabia\": true, \"is_vat_registered\": true, \"vat_registration_number\": \"{{testVatNumber}}\", \"additional_buyer_id\": [{\"type_id\": \"CRN\", \"id_number\": \"1010101010\"}], \"street\": \"King Fahd Road\", \"building_number\": \"1234\", \"district\": \"Al Olaya\", \"city\": \"Riyadh\", \"postal_code\": \"12211\", \"province_state\": \"Riyadh\", \"country\": \"SA\"}" } ] } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 201', function () { pm.response.to.have.status(201); });", "if (pm.response.code === 201) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/buyers\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('buyerId', m[1]);", " console.log('buyerId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "f88bb66d-9646-5605-b581-53ed4d517817", "name": "Create a foreign client (for export)", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/api/onboarding/organizations/clients/", "host": [ "{{baseUrl}}" ], "path": [ "api", "onboarding", "organizations", "clients" ] }, "description": "Creates a buyer outside Saudi Arabia, for the export scenario. On `201` the test script saves its id to `exportBuyerId`.\n\nA foreign buyer is B2B, not VAT registered, has a `country` other than `SA`, and carries another ID: `GCC`, `PAS` or `OTH` only. Without that ID the client is refused (ZATCA BR-KSA-81).\n\nDocs: [Invoice types → Export invoices](https://docs.goclix.ai/concepts/invoice-types/#set-it-up-in-clix)", "body": { "mode": "formdata", "formdata": [ { "key": "client_data", "type": "text", "value": "{\"buyer_name\": \"Postman Test Gulf Design LLC\", \"business_type\": \"{{businessTypeId}}\", \"industry\": \"{{industryId}}\", \"is_from_saudi_arabia\": false, \"is_vat_registered\": false, \"additional_buyer_id\": [{\"type_id\": \"GCC\", \"id_number\": \"GCC{{$timestamp}}\"}], \"street\": \"Sheikh Zayed Road\", \"building_number\": \"12\", \"city\": \"Dubai\", \"province_state\": \"Dubai\", \"country\": \"AE\"}" } ] } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 201', function () { pm.response.to.have.status(201); });", "if (pm.response.code === 201) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/buyers\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('exportBuyerId', m[1]);", " console.log('exportBuyerId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "1b048673-cffc-582f-bd39-e8036fc455a7", "name": "List clients", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/buyers/", "host": [ "{{baseUrl}}" ], "path": [ "api", "buyers" ] }, "description": "Your clients, each with `uuid`, `buyer_name` and `vat_registration_number`. Use a `uuid` from here as `buyerId` instead of creating one.\n\nDocs: [https://docs.goclix.ai/developers/api-reference/#clients](https://docs.goclix.ai/developers/api-reference/#clients)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "1b3df62e-c682-5378-9c43-3213f8f7d32a", "name": "Create an item", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/api/items/", "host": [ "{{baseUrl}}" ], "path": [ "api", "items" ] }, "description": "Creates a catalogue item for the **From catalogue** scenario. On `201` the test script saves its id to `itemId`.\n\nThe body is `multipart/form-data`: one field, `item_data`, holding the item as a JSON string. `business_type_category_id` takes a business type `uuid`, here `businessTypeId`. `stock_keeping_unit` is the unit of measure. With `unlimited_stock` `true`, leave out `current_stock_quantity` and `alert_quantity`.\n\nDocs: [https://docs.goclix.ai/developers/api-reference/#items](https://docs.goclix.ai/developers/api-reference/#items)", "body": { "mode": "formdata", "formdata": [ { "key": "item_data", "type": "text", "value": "{\"item_name\": \"Postman test service\", \"cost_price\": \"150.00\", \"selling_price\": \"250.00\", \"vat_type\": \"S\", \"vat_rate\": 15.0, \"business_type_category_id\": \"{{businessTypeId}}\", \"stock_keeping_unit\": \"PCE\", \"unlimited_stock\": true}" } ] } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 201', function () { pm.response.to.have.status(201); });", "if (pm.response.code === 201) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/items\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('itemId', m[1]);", " console.log('itemId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "bdc6d151-cda2-52f3-88f3-8c8a0fcd2f70", "name": "List items", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/items/", "host": [ "{{baseUrl}}" ], "path": [ "api", "items" ] }, "description": "Your catalogue items, each with `uuid` and `item_name`. Use a `uuid` from here as `itemId` instead of creating one.\n\nDocs: [https://docs.goclix.ai/developers/quickstart/#two-ways-to-send-lines](https://docs.goclix.ai/developers/quickstart/#two-ways-to-send-lines)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] } ] }, { "id": "652a1437-1481-5a42-a310-bb9c38fa7150", "name": "3 Preview", "description": "One preview per scenario. A preview validates and calculates, and stores nothing. Run these before the matching request in 4 Issue.", "item": [ { "id": "d6c45fbb-5b9b-5b2b-bd10-1479df3459a9", "name": "Preview: Standard tax invoice (B2B)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "A standard tax invoice to a VAT-registered business: two hours of consulting at 100 SAR, 15% VAT, 230 SAR in all.\n\n**When:** You sell to a business in Saudi Arabia, or any sale is over SAR 1,000. ZATCA clears it before it is valid.\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Invoice types → Standard or simplified](https://docs.goclix.ai/concepts/invoice-types/#standard-or-simplified) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Consulting hours\",\n \"invoiced_quantity\": 2,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"100.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "fbe18bee-ea28-5919-8e9b-9104333e770a", "name": "Preview: Simplified tax invoice (B2C)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "A simplified tax invoice to a consumer, with no `buyer` key: two coffees at 10 SAR, 15% VAT, 23 SAR in all. `transaction_code` is `0200000`.\n\n**When:** You sell to a consumer. ZATCA receives a report after issue. Needs a device that may issue simplified invoices (`invoice_type` `0100` or `1100`).\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Invoice types → Standard or simplified](https://docs.goclix.ai/concepts/invoice-types/#standard-or-simplified) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0200000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Coffee, large\",\n \"invoiced_quantity\": 2,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"10.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "117b0c37-d938-55ed-8d0d-c2ae02395fa6", "name": "Preview: Export of services (zero-rated, USD)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "An export invoice: `transaction_code` `0100100`, a foreign buyer (`exportBuyerId`), every line zero-rated `Z` with `VATEX-SA-33` *Export of services*, in USD at 3.75 SAR. 2,000 USD, VAT 0.\n\nFor goods, use `VATEX-SA-32` *Export of goods* and keep the export evidence for 90 days.\n\n**When:** You sell services to a buyer with no residence in the GCC, or goods that leave Saudi Arabia. The buyer must not be Saudi or VAT registered.\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Invoice types → Export invoices](https://docs.goclix.ai/concepts/invoice-types/#export-invoices) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{exportBuyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100100\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"USD\",\n \"exchange_rate\": 3.75,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Design consulting package\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"2000.00\",\n \"vat_category_code\": \"Z\",\n \"vat_rate\": 0.0,\n \"vat_exemption_reason_code\": \"VATEX-SA-33\",\n \"vat_exemption_reason_text\": \"Export of services\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "08696742-887d-5383-b32b-a34cc1f581bb", "name": "Preview: Foreign-currency invoice (USD)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "A standard B2B invoice to the Saudi client, priced in USD: one line at 400 USD, 15% VAT, at 3.75 SAR to the dollar. VAT is reported to ZATCA in SAR.\n\n**When:** You bill a Saudi business in another currency. `exchange_rate` is that currency's rate to SAR, above zero and never `1`. With `SAR` it must be exactly `1`.\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Invoice types → What ZATCA requires on the invoice](https://docs.goclix.ai/concepts/invoice-types/#what-zatca-requires-on-the-invoice) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"USD\",\n \"exchange_rate\": 3.75,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Consulting hours\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"400.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "d44c66d0-1899-55e3-b054-d9041ce8a661", "name": "Preview: Standard invoice from the catalogue (lines)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "A standard B2B invoice billed from a catalogue item: `lines` carries `item_id` and `quantity`, and `form_lines` stays `[]`. Price, unit and VAT come from the item.\n\n**When:** The product or service is saved as an item in Clix. Send one of `lines` and `form_lines` with entries, never both.\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Quickstart → Two ways to send lines](https://docs.goclix.ai/developers/quickstart/#two-ways-to-send-lines) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [],\n \"lines\": [\n {\n \"item_id\": \"{{itemId}}\",\n \"quantity\": 1\n }\n ],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "6753330a-11d2-58ed-a0c1-4f43ebb5e62b", "name": "Preview: Credit note against invoiceId", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "A credit note (`type_code` `381`) for one of the two consulting hours on the invoice in `invoiceId`. `original_invoice_reference` lists that invoice; `reason_id` is a credit-note reason; each line names the original line in `invoice_line_id`.\n\nBefore you send it: issue **Standard tax invoice (B2B)**, then send **5 Follow up → Get the invoice (poll)** until it is final. That poll saves `invoiceLineId`. The note keeps the original's buyer, device, currency and transaction code, so leave those as they are. On `202` the test script saves the note's id to `noteId`, not `invoiceId`, so the debit note still points at the original.\n\n**When:** The buyer owes less: a return, a late discount, an overcharge, a cancellation. A credit note cannot take more than is left of the original.\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Invoice types → Credit and debit notes](https://docs.goclix.ai/concepts/invoice-types/#credit-and-debit-notes) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 381,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": \"{{reasonId}}\",\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Consulting hours\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"100.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\",\n \"invoice_line_id\": \"{{invoiceLineId}}\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [\n \"{{invoiceId}}\"\n ],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "3d5dfb38-62fa-5ece-adc2-2fc501783373", "name": "Preview: Debit note against invoiceId", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/preview/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "preview" ] }, "description": "A debit note (`type_code` `383`) adding a 50 SAR delivery fee to the invoice in `invoiceId`, with a debit-note reason in `reason_id` and the original line in `invoice_line_id`.\n\nSame preparation as the credit note. On `202` the test script saves the note's id to `noteId`.\n\n**When:** The buyer owes more: an undercharge, an extra service, a price rise.\n\nA preview runs the same validation and calculation as a create, returns the computed invoice with its totals, and stores nothing. It sends nothing to ZATCA and uses no invoice number. Expect `201` `{\"message\": \"Invoice preview created successfully\", \"invoice\": {…}}`. A `400` names the first rule that failed; fix it and preview again. A preview skips the monthly allowance, the five-minute duplicate guard and the credit-note limits.\n\nDocs: [Invoice types → Credit and debit notes](https://docs.goclix.ai/concepts/invoice-types/#credit-and-debit-notes) · [Quickstart → Preview](https://docs.goclix.ai/developers/quickstart/#4-preview-before-you-commit)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 383,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": \"{{debitReasonId}}\",\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Delivery fee\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"50.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\",\n \"invoice_line_id\": \"{{invoiceLineId}}\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [\n \"{{invoiceId}}\"\n ],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] } ] }, { "id": "258d05fb-5bcc-53d8-9fa9-dbdb575cbe86", "name": "4 Issue", "description": "One create per scenario. Each returns 202 and a location to poll. Issue the standard invoice first: the credit and debit notes correct it.", "item": [ { "id": "906d48cc-27ba-50b3-9840-268202d40c5e", "name": "Issue: Standard tax invoice (B2B)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "A standard tax invoice to a VAT-registered business: two hours of consulting at 100 SAR, 15% VAT, 230 SAR in all.\n\n**When:** You sell to a business in Saudi Arabia, or any sale is over SAR 1,000. ZATCA clears it before it is valid.\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `invoiceId`. Then poll it in **5 Follow up**. Final status `CLEARED`.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Invoice types → Standard or simplified](https://docs.goclix.ai/concepts/invoice-types/#standard-or-simplified) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Consulting hours\",\n \"invoiced_quantity\": 2,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"100.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('invoiceId', m[1]);", " console.log('invoiceId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "d5778431-526a-520b-991b-33a1b4463ba2", "name": "Issue: Simplified tax invoice (B2C)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "A simplified tax invoice to a consumer, with no `buyer` key: two coffees at 10 SAR, 15% VAT, 23 SAR in all. `transaction_code` is `0200000`.\n\n**When:** You sell to a consumer. ZATCA receives a report after issue. Needs a device that may issue simplified invoices (`invoice_type` `0100` or `1100`).\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `invoiceId`. Then poll it in **5 Follow up**. Final status `REPORTED`.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Invoice types → Standard or simplified](https://docs.goclix.ai/concepts/invoice-types/#standard-or-simplified) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0200000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Coffee, large\",\n \"invoiced_quantity\": 2,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"10.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('invoiceId', m[1]);", " console.log('invoiceId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "f5f10441-4d75-5275-a41b-39bb3bd42b1b", "name": "Issue: Export of services (zero-rated, USD)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "An export invoice: `transaction_code` `0100100`, a foreign buyer (`exportBuyerId`), every line zero-rated `Z` with `VATEX-SA-33` *Export of services*, in USD at 3.75 SAR. 2,000 USD, VAT 0.\n\nFor goods, use `VATEX-SA-32` *Export of goods* and keep the export evidence for 90 days.\n\n**When:** You sell services to a buyer with no residence in the GCC, or goods that leave Saudi Arabia. The buyer must not be Saudi or VAT registered.\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `invoiceId`. Then poll it in **5 Follow up**. Final status `CLEARED`.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Invoice types → Export invoices](https://docs.goclix.ai/concepts/invoice-types/#export-invoices) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{exportBuyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100100\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"USD\",\n \"exchange_rate\": 3.75,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Design consulting package\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"2000.00\",\n \"vat_category_code\": \"Z\",\n \"vat_rate\": 0.0,\n \"vat_exemption_reason_code\": \"VATEX-SA-33\",\n \"vat_exemption_reason_text\": \"Export of services\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('invoiceId', m[1]);", " console.log('invoiceId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "b0928a3b-fb83-5a70-88d2-fcb371270dd6", "name": "Issue: Foreign-currency invoice (USD)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "A standard B2B invoice to the Saudi client, priced in USD: one line at 400 USD, 15% VAT, at 3.75 SAR to the dollar. VAT is reported to ZATCA in SAR.\n\n**When:** You bill a Saudi business in another currency. `exchange_rate` is that currency's rate to SAR, above zero and never `1`. With `SAR` it must be exactly `1`.\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `invoiceId`. Then poll it in **5 Follow up**. Final status `CLEARED`.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Invoice types → What ZATCA requires on the invoice](https://docs.goclix.ai/concepts/invoice-types/#what-zatca-requires-on-the-invoice) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"USD\",\n \"exchange_rate\": 3.75,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Consulting hours\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"400.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('invoiceId', m[1]);", " console.log('invoiceId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "8cb5e661-32b2-56ea-acd3-6e05b29198e5", "name": "Issue: Standard invoice from the catalogue (lines)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "A standard B2B invoice billed from a catalogue item: `lines` carries `item_id` and `quantity`, and `form_lines` stays `[]`. Price, unit and VAT come from the item.\n\n**When:** The product or service is saved as an item in Clix. Send one of `lines` and `form_lines` with entries, never both.\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `invoiceId`. Then poll it in **5 Follow up**. Final status `CLEARED`.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Quickstart → Two ways to send lines](https://docs.goclix.ai/developers/quickstart/#two-ways-to-send-lines) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 388,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": null,\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [],\n \"lines\": [\n {\n \"item_id\": \"{{itemId}}\",\n \"quantity\": 1\n }\n ],\n \"original_invoice_reference\": [],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('invoiceId', m[1]);", " console.log('invoiceId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "74f41d3a-6c74-5584-9604-5a91ac0d85a2", "name": "Issue: Credit note against invoiceId", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "A credit note (`type_code` `381`) for one of the two consulting hours on the invoice in `invoiceId`. `original_invoice_reference` lists that invoice; `reason_id` is a credit-note reason; each line names the original line in `invoice_line_id`.\n\nBefore you send it: issue **Standard tax invoice (B2B)**, then send **5 Follow up → Get the invoice (poll)** until it is final. That poll saves `invoiceLineId`. The note keeps the original's buyer, device, currency and transaction code, so leave those as they are. On `202` the test script saves the note's id to `noteId`, not `invoiceId`, so the debit note still points at the original.\n\n**When:** The buyer owes less: a return, a late discount, an overcharge, a cancellation. A credit note cannot take more than is left of the original.\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `noteId`. Then poll it in **5 Follow up**. Same flow as the original: `CLEARED` for a standard invoice.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Invoice types → Credit and debit notes](https://docs.goclix.ai/concepts/invoice-types/#credit-and-debit-notes) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 381,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": \"{{reasonId}}\",\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Consulting hours\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"100.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\",\n \"invoice_line_id\": \"{{invoiceLineId}}\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [\n \"{{invoiceId}}\"\n ],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('noteId', m[1]);", " console.log('noteId = ' + m[1]);", " }", "}" ] } } ] }, { "id": "44296783-640d-50b2-84a6-2d5a6c627a12", "name": "Issue: Debit note against invoiceId", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices" ] }, "description": "A debit note (`type_code` `383`) adding a 50 SAR delivery fee to the invoice in `invoiceId`, with a debit-note reason in `reason_id` and the original line in `invoice_line_id`.\n\nSame preparation as the credit note. On `202` the test script saves the note's id to `noteId`.\n\n**When:** The buyer owes more: an undercharge, an extra service, a price rise.\n\nExpect `202 Accepted` with a `location`. The test script saves the id from `location` to `noteId`. Then poll it in **5 Follow up**. Same flow as the original: `CLEARED` for a standard invoice.\n\nThe note text carries `{{$timestamp}}`, so two sends are never identical and the five-minute duplicate guard does not refuse the second. Each send issues a real sandbox invoice and counts toward your monthly allowance.\n\nDocs: [Invoice types → Credit and debit notes](https://docs.goclix.ai/concepts/invoice-types/#credit-and-debit-notes) · [Quickstart → Create](https://docs.goclix.ai/developers/quickstart/#5-create-the-invoice)", "body": { "mode": "raw", "raw": "{\n \"device\": \"{{deviceId}}\",\n \"seller\": \"{{sellerId}}\",\n \"buyer\": \"{{buyerId}}\",\n \"type_code\": 383,\n \"transaction_code\": \"0100000\",\n \"supply_date\": \"{{today}}\",\n \"supply_end_date\": \"{{today}}\",\n \"currency\": \"SAR\",\n \"exchange_rate\": 1,\n \"payment_means_type_code\": \"10\",\n \"add_prepaid_amount\": false,\n \"reason_id\": \"{{debitReasonId}}\",\n \"notes\": [\n {\n \"language_id\": \"en\",\n \"note\": \"Postman test {{$timestamp}}\"\n }\n ],\n \"form_lines\": [\n {\n \"item_name\": \"Delivery fee\",\n \"invoiced_quantity\": 1,\n \"invoiced_quantity_unit_of_measure\": \"PCE\",\n \"item_net_price\": \"50.00\",\n \"vat_category_code\": \"S\",\n \"vat_rate\": 15.0,\n \"vat_exemption_reason_code\": \"\",\n \"vat_exemption_reason_text\": \"\",\n \"invoice_line_id\": \"{{invoiceLineId}}\"\n }\n ],\n \"lines\": [],\n \"original_invoice_reference\": [\n \"{{invoiceId}}\"\n ],\n \"prepaid_invoices\": [],\n \"document_level_allowances\": []\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 202', function () { pm.response.to.have.status(202); });", "if (pm.response.code === 202) {", " const body = pm.response.json();", " const m = (body.location || '').match(/\\/api\\/invoices\\/([0-9a-f-]{36})\\//);", " if (m) {", " setVar('noteId', m[1]);", " console.log('noteId = ' + m[1]);", " }", "}" ] } } ] } ] }, { "id": "1226ee59-eaab-51a9-954d-a0d82498e879", "name": "5 Follow up", "description": "Poll, read and annotate what you issued.", "item": [ { "id": "7d70c5bb-6224-5116-86f6-6b0a633d5aeb", "name": "Get the invoice (poll)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/{{invoiceId}}/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "{{invoiceId}}" ] }, "description": "Reads the invoice in `invoiceId`. Send it again every second or two until `zatca_response_status` is final: `CLEARED`, `REPORTED`, `NOT_CLEARED` or `NOT_REPORTED`. `No response` means ZATCA gave no answer Clix recognises; see **Retry ZATCA submission**.\n\nA rejection's reasons are in `zatca_response_data.validationResults.errorMessages[]`. For a tax invoice the test script also saves `lines[0].invoice_line_id` to `invoiceLineId`, which the credit and debit notes need.\n\nOn the sandbox, ZATCA signs with a shared test certificate, so an invoice from your own VAT number comes back `NOT_CLEARED` or `NOT_REPORTED` with `certificate-permissions`. That is the sandbox, not your invoice.\n\nDocs: [https://docs.goclix.ai/developers/quickstart/#6-poll-until-it-is-final](https://docs.goclix.ai/developers/quickstart/#6-poll-until-it-is-final)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "function setVar(k, v) {", " pm.collectionVariables.set(k, v);", " if (pm.environment && pm.environment.name) { pm.environment.set(k, v); }", "}", "pm.test('Status is 200', function () { pm.response.to.have.status(200); });", "const inv = pm.response.json();", "const status = inv.zatca_response_status;", "const final = ['CLEARED', 'REPORTED', 'NOT_CLEARED', 'NOT_REPORTED'];", "console.log('zatca_response_status = ' + status);", "pm.test('ZATCA status: ' + status, function () { pm.expect(status).to.be.a('string'); });", "if (!final.includes(status)) { console.log('Not final yet. Wait a second or two and send again.'); }", "if (Number(inv.type_code) === 388 && inv.lines && inv.lines.length) {", " setVar('invoiceLineId', inv.lines[0].invoice_line_id);", " console.log('invoiceLineId = ' + inv.lines[0].invoice_line_id);", "}" ] } } ] }, { "id": "d6ebfd35-0a2f-5c16-8789-956f09610c4d", "name": "Get the note (poll)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/{{noteId}}/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "{{noteId}}" ] }, "description": "Reads the credit or debit note in `noteId`, the last one you issued. Poll it as you poll an invoice.\n\nDocs: [https://docs.goclix.ai/developers/quickstart/#6-poll-until-it-is-final](https://docs.goclix.ai/developers/quickstart/#6-poll-until-it-is-final)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "f2fc3f5c-c178-55db-9512-2e85e9abca05", "name": "Comments on the invoice", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/{{invoiceId}}/notes/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "{{invoiceId}}", "notes" ] }, "description": "Lists the comments kept against the invoice. These are annotations for your own audit trail, not credit or debit notes. They have no VAT effect and never reach ZATCA.\n\nDocs: [https://docs.goclix.ai/developers/api-reference/#notes-on-an-invoice](https://docs.goclix.ai/developers/api-reference/#notes-on-an-invoice)" }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200', function () { pm.response.to.have.status(200); });" ] } } ] }, { "id": "13ef88c8-4f0b-56f1-9af0-4f6075203746", "name": "Add a comment to the invoice", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/api/invoices/{{invoiceId}}/notes/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "{{invoiceId}}", "notes" ] }, "description": "Adds a comment, `{\"title\": \"…\", \"details\": \"…\"}`, to the invoice. Expect `201`. To correct an invoice, issue a credit or debit note instead.\n\nDocs: [https://docs.goclix.ai/developers/api-reference/#notes-on-an-invoice](https://docs.goclix.ai/developers/api-reference/#notes-on-an-invoice)", "body": { "mode": "raw", "raw": "{\n \"title\": \"Postman test\",\n \"details\": \"Delivered and signed for. {{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 201', function () { pm.response.to.have.status(201); });" ] } } ] }, { "id": "821872f1-b37d-53e5-ad1d-614c08d4fe57", "name": "Download the PDF/A-3", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/{{invoiceId}}/pdf-a3/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "{{invoiceId}}", "pdf-a3" ] }, "description": "The invoice PDF with the ZATCA XML embedded. Before the invoice is final, and for a rejected invoice, it answers `404` `{\"message\": \"Invoice PDF not found\"}`. In Postman, use **Send and Download** to save the file.\n\nDocs: [https://docs.goclix.ai/developers/quickstart/#7-fetch-the-pdf](https://docs.goclix.ai/developers/quickstart/#7-fetch-the-pdf)" }, "response": [] }, { "id": "18c710c2-8b20-576a-bd77-de17523b0eee", "name": "Retry ZATCA submission", "request": { "method": "PATCH", "header": [], "url": { "raw": "{{baseUrl}}/api/invoices/{{invoiceId}}/clearance-reporting/", "host": [ "{{baseUrl}}" ], "path": [ "api", "invoices", "{{invoiceId}}", "clearance-reporting" ] }, "description": "Sends the invoice to ZATCA again. Use it only for an invoice with no ZATCA answer yet: after a `202` that said *…the submission to ZATCA failed. Please retry submission.*, or a status of `No response`. Expect `202` and a `location` to poll.\n\n**`409`** means there is nothing to retry: ZATCA has already answered (cleared, reported or rejected), or a retry is already in flight. Do not retry a `409`. A rejected invoice is final; fix the cause and issue a new one. This call never changes the invoice; to correct one, issue a credit or debit note.\n\nDocs: [https://docs.goclix.ai/developers/api-reference/#invoices](https://docs.goclix.ai/developers/api-reference/#invoices) · [Errors → Status codes](https://docs.goclix.ai/developers/errors/#status-codes)" }, "response": [] } ] } ] }