{ "openapi": "3.1.0", "info": { "title": "WonderFatoora API", "version": "1.4.0", "summary": "Saudi e-invoicing for your company, programmatically.", "description": "Create customers and invoices, issue them as ZATCA-compliant tax invoices,\nfollow their ZATCA status and download the PDF and the legal XML.\n\nEvery call is made with a credential of one company and acts for that\ncompany only; no request can name another. Two kinds of credential:\nan API key of the company, or an OAuth 2.1 access token of an app the\ncompany connected. Either can do what it was granted (its scopes) and\nwhat the person behind it may do, never more.\n\nSuccessful responses are `{\"ok\": true, \"data\": {...}, \"meta\": {...}}`.\nErrors are `{\"ok\": false, \"error\": {\"code\", \"message\", \"details\"}}`,\nwith `code` from a fixed list (see the `Error` schema).\n\nMessages (`error.message`, field errors) are in Arabic unless the\nrequest's `Accept-Language` prefers English (`en`, `en-US`, ...); any\nother value, or none, gives Arabic. Every response names its language\nin `Content-Language`. Codes, field names and data never change with\nthe language.\n\nThe version is part of the path: `/api/v1`. A path that names any other\nversion (`/api/v2/…`, `/api/V1/…`, `/api/v1.1/…`) answers\n`400 unsupported_api_version`, with `details.supported_versions`.\n\nA refused credential answers `401 unauthorized` (an API key) or\n`401 invalid_token` (an OAuth token), whatever the reason, with one\nexception: an API key that is fine except that it expired answers\n`401 token_expired`, with `details.expired_at` and `details.renew_url`\n(where the company creates or rotates its keys).\n\nAmounts are JSON numbers rounded to 2 decimals. Dates are `YYYY-MM-DD`\non the seller's business calendar; timestamps are ISO 8601.\n\nLists are newest first and paged with an opaque `cursor`.\n\nWrite calls accept an `Idempotency-Key` header: a retry with the same\nkey and the same body returns the first answer (with\n`Idempotent-Replayed: true`); the same key with a different body is\nrefused with `idempotency_key_reused`. Keys are kept for 24 hours, per\ncredential: an answer is replayed only to the API key (or the OAuth\nconnection) that sent the request; another credential of the company\nusing the same key, a rotated key's replacement included, makes a\nrequest of its own.\n\nWebhooks POST each event (see `webhooks`) to the endpoints a company\nregisters, signed with HMAC-SHA256 in the `WF-Signature` header:\n`t=,v1=`, where `v1` is the hex HMAC-SHA256 of\n`t + \".\" + raw body` keyed with the endpoint's secret (`whsec_…`).\nRefuse a `t` more than 300 seconds from your clock, compare in constant\ntime, and accept either `v1` for 24 hours after a secret rotation.\n\nInvoice lifecycle: `POST /invoices` issues at once unless\n`\"issue\": false` makes a draft (a `DRAFT-…` reference, no legal number,\nnothing sent to ZATCA). A draft is checked with\n`POST /invoices/{invoice}/validate` and issued with\n`POST /invoices/{invoice}/issue` (scope `invoices:issue`). Issuing\nassigns the next legal number; for a company linked to ZATCA, a\nstandard invoice is then cleared and a simplified one reported, and\n`zatca.status` follows on the invoice and in webhooks. An issued\ninvoice is final: it is corrected only with a credit or debit note.\n\nRate limits: every key of one company shares one budget, by plan\n(Enterprise 240 requests a minute and 50,000 a day; Business 60 and\n5,000; a sandbox company 30 and 2,000). On top of that, each\ncredential may issue 30 documents a minute and download 10 PDFs or\nXMLs a minute. Over a limit the answer is `429 rate_limited` with a\n`Retry-After` header (seconds); wait that long before retrying.\n" }, "servers": [ { "url": "https://fatoora.tw.sa/api/v1" } ], "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ { "name": "General" }, { "name": "Company" }, { "name": "Customers" }, { "name": "Invoices" }, { "name": "Notes", "description": "Credit and debit notes, the only way to correct an issued invoice." }, { "name": "Webhooks", "description": "Signed HTTPS notifications of the company's events, the endpoints that receive them, and the events list for polling." } ], "paths": { "/ping": { "get": { "operationId": "ping", "tags": [ "General" ], "summary": "Check that a key works", "description": "Any valid key may call it, whatever its scopes.", "security": [ { "apiKey": [] }, { "oauth2": [] } ], "responses": { "200": { "description": "The key works.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/company": { "get": { "operationId": "getCompany", "tags": [ "Company" ], "summary": "The company this key acts for", "security": [ { "apiKey": [ "companies:read" ] }, { "oauth2": [ "companies:read" ] } ], "responses": { "200": { "description": "The company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/company/readiness": { "get": { "operationId": "getCompanyReadiness", "tags": [ "Company" ], "summary": "Whether the company can issue invoices now", "description": "What is missing before invoices can be issued, and how far ZATCA linking has come.", "security": [ { "apiKey": [ "companies:read" ] }, { "oauth2": [ "companies:read" ] } ], "responses": { "200": { "description": "The readiness summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/customers": { "get": { "operationId": "listCustomers", "tags": [ "Customers" ], "summary": "List customers", "security": [ { "apiKey": [ "customers:read" ] }, { "oauth2": [ "customers:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "q", "in": "query", "description": "Searches names, e-mail, phone and VAT number.", "schema": { "type": "string", "maxLength": 191 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "individual", "business" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "vat_number", "in": "query", "schema": { "type": "string", "maxLength": 32 } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of customers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createCustomer", "tags": [ "Customers" ], "summary": "Create a customer", "description": "Needs the person behind the key to be allowed to manage customers. Counts against the plan's customer allowance.", "security": [ { "apiKey": [ "customers:write" ] }, { "oauth2": [ "customers:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "201": { "description": "The customer was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/customers/{customer}": { "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "get": { "operationId": "getCustomer", "tags": [ "Customers" ], "summary": "Get a customer", "security": [ { "apiKey": [ "customers:read" ] }, { "oauth2": [ "customers:read" ] } ], "responses": { "200": { "description": "The customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateCustomer", "tags": [ "Customers" ], "summary": "Update a customer", "description": "Changes only the fields sent; a field left out keeps its value.", "security": [ { "apiKey": [ "customers:write" ] }, { "oauth2": [ "customers:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPatch" } } } }, "responses": { "200": { "description": "The updated customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices": { "get": { "operationId": "listInvoices", "tags": [ "Invoices" ], "summary": "List invoices", "description": "Tax invoices only, newest first.", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "description": "One or more statuses (`status[]=paid&status[]=partial`, or comma-separated). `overdue` is worked out from the due date.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceStatusValue" } }, "style": "form", "explode": true }, { "name": "zatca_status", "in": "query", "description": "One or more ZATCA statuses.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ZatcaStatusValue" } }, "style": "form", "explode": true }, { "name": "customer_id", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "issue_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "issue_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "external_reference", "in": "query", "schema": { "type": "string", "maxLength": 191 } }, { "name": "number", "in": "query", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "A page of invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createInvoice", "tags": [ "Invoices" ], "summary": "Create an invoice, as a draft or issued at once", "description": "Issues the invoice unless `issue` is `false`; issuing also needs the\n`invoices:issue` scope. Counts against the plan's monthly invoice\nallowance.\n\nSending your own `external_reference` (an order number) makes the call\nsafe to retry: a repeat answers 200 with `replayed: true` and the\ninvoice already made. A key without `invoices:read` is told only the\ninvoice's id, number and status.\n\nPaid already, through your own payment gateway or till? Send\n`payment` and the payment is recorded in the same call, so the\ninvoice arrives `paid` (or `partial`). It needs the `payments:write`\nscope and an issued invoice; `amount` defaults to the whole total.\nIf the payment is refused, nothing is created.\n", "security": [ { "apiKey": [ "invoices:draft" ] }, { "oauth2": [ "invoices:draft" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "201": { "description": "The invoice was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "200": { "description": "A repeat of an `external_reference` already invoiced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceReplayResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "get": { "operationId": "getInvoice", "tags": [ "Invoices" ], "summary": "Get an invoice", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/status": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "get": { "operationId": "getInvoiceStatus", "tags": [ "Invoices" ], "summary": "Where an invoice stands", "description": "Its status, payments and ZATCA status, without its lines. Made for polling.", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "responses": { "200": { "description": "The status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceStatusResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/validate": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "post": { "operationId": "validateInvoice", "tags": [ "Invoices" ], "summary": "Check whether a draft can be issued", "description": "Runs every check issuing runs, and changes nothing.", "security": [ { "apiKey": [ "invoices:draft" ] }, { "oauth2": [ "invoices:draft" ] } ], "responses": { "200": { "description": "Whether it can be issued, and what is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/issue": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "post": { "operationId": "issueInvoice", "tags": [ "Invoices" ], "summary": "Issue a draft", "description": "Gives the draft its tax-invoice number and QR and, for a company linked\nto ZATCA, submits it. Irreversible: an issued invoice is corrected with\na credit or debit note. An invoice already issued answers 200 with\n`already_issued: true`.\n", "security": [ { "apiKey": [ "invoices:issue" ] }, { "oauth2": [ "invoices:issue" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The issued invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueInvoiceResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/pdf": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "get": { "operationId": "downloadInvoicePdf", "tags": [ "Invoices" ], "summary": "Download the invoice PDF", "description": "A standard invoice ZATCA has not cleared yet prints without a QR and is marked as not yet valid.", "security": [ { "apiKey": [ "invoices:download" ] }, { "oauth2": [ "invoices:download" ] } ], "responses": { "200": { "description": "The PDF.", "content": { "application/pdf": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/xml": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "get": { "operationId": "downloadInvoiceXml", "tags": [ "Invoices" ], "summary": "Download the legal XML", "description": "The document ZATCA holds: the cleared XML of a standard invoice, the\nsigned XML of a simplified one. `document_not_available` (409) until\nthere is one; `xml_not_applicable` (404) for a company not linked to\nZATCA.\n", "security": [ { "apiKey": [ "invoices:download" ] }, { "oauth2": [ "invoices:download" ] } ], "responses": { "200": { "description": "The XML.", "content": { "application/xml": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/notes": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "get": { "operationId": "listInvoiceNotes", "tags": [ "Notes" ], "summary": "Credit and debit notes of an invoice", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "responses": { "200": { "description": "The notes, oldest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createInvoiceNote", "tags": [ "Notes" ], "summary": "Raise a credit or debit note on an issued invoice", "description": "A draft unless `issue` is `true`, which also needs `invoices:issue`.\nA reason is required, and a credit can never exceed what is left on\nthe invoice (`credit_exceeds_invoice`). If issuing fails, no note is\nkept.\n", "security": [ { "apiKey": [ "invoices:draft" ] }, { "oauth2": [ "invoices:draft" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "201": { "description": "The note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{invoice}/payments": { "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "get": { "operationId": "listInvoicePayments", "tags": [ "Invoices" ], "summary": "Customer payments of an invoice", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "responses": { "200": { "description": "The payments, oldest first, and the invoice balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "recordInvoicePayment", "tags": [ "Invoices" ], "summary": "Record a customer payment on an issued invoice", "description": "For money received after the invoice was made (a bank transfer, a\nlate confirmation from your gateway). Never more than the balance\nstill owed (`payment_exceeds_balance`), never on a draft, cancelled\nor refunded invoice (`invoice_not_payable`). Paid before the invoice\nwas made? Send `payment` with `POST /invoices` instead.\n", "security": [ { "apiKey": [ "payments:write" ] }, { "oauth2": [ "payments:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInput" } } } }, "responses": { "201": { "description": "The payment and the invoice new balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/notes/{note}": { "parameters": [ { "$ref": "#/components/parameters/NoteId" } ], "get": { "operationId": "getNote", "tags": [ "Notes" ], "summary": "Get a credit or debit note", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "responses": { "200": { "description": "The note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/notes/{note}/issue": { "parameters": [ { "$ref": "#/components/parameters/NoteId" } ], "post": { "operationId": "issueNote", "tags": [ "Notes" ], "summary": "Issue a draft note", "description": "Irreversible. A note already issued answers 200 with `already_issued: true`.", "security": [ { "apiKey": [ "invoices:issue" ] }, { "oauth2": [ "invoices:issue" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The issued note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueNoteResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/notes/{note}/pdf": { "parameters": [ { "$ref": "#/components/parameters/NoteId" } ], "get": { "operationId": "downloadNotePdf", "tags": [ "Notes" ], "summary": "Download the note PDF", "security": [ { "apiKey": [ "invoices:download" ] }, { "oauth2": [ "invoices:download" ] } ], "responses": { "200": { "description": "The PDF.", "content": { "application/pdf": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/notes/{note}/xml": { "parameters": [ { "$ref": "#/components/parameters/NoteId" } ], "get": { "operationId": "downloadNoteXml", "tags": [ "Notes" ], "summary": "Download the note's legal XML", "security": [ { "apiKey": [ "invoices:download" ] }, { "oauth2": [ "invoices:download" ] } ], "responses": { "200": { "description": "The XML.", "content": { "application/xml": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events": { "get": { "operationId": "listEvents", "tags": [ "Webhooks" ], "summary": "List recent events", "description": "The company's events, newest first: the polling alternative to\nwebhooks, with the same `data` a delivery carries. Customer events\nare listed only for a key that also holds `customers:read`. Events\nare recorded while the company has an active webhook endpoint and\nkept for 30 days.\n", "security": [ { "apiKey": [ "invoices:read" ] }, { "oauth2": [ "invoices:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "description": "One or more event types (`type[]=invoice.issued&type[]=invoice.paid`, or comma-separated).", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeValue" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Needs the person behind the key to be allowed to manage the company's\nsettings. An OAuth app sees only the endpoints it registered itself;\nan API key sees every endpoint of the company.\n", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "disabled" ] } } ], "responses": { "200": { "description": "A page of endpoints. Secrets are never listed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Register a webhook endpoint", "description": "The URL must be a public `https` address on port 443 or 8443, with a\ndomain name (not an IP address) that resolves only to public\naddresses; it is checked again before every delivery. The answer\ncarries the signing `secret`, **once**: store it now. At most 10\nendpoints per company. No `Idempotency-Key`: a stored replay would\nkeep the secret.\n\n`events` may only name types your credential can read\n(`invoices:read` for invoice and note events, `customers:read` for\ncustomer events); any other type answers `422 validation_failed`,\nand so does a credential that can read none. `*` is stored as\nexactly the types your credential can read.\n\nAn endpoint an OAuth app registers belongs to that app's connection\nto the company: it is switched off (`disabled_reason`\n`connection_revoked` or `connection_suspended`) when the connection\nis revoked or suspended, stays off after a new consent, and never\nreceives an event the connection's current scopes cannot read.\n", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } }, "responses": { "201": { "description": "The endpoint, with its secret (shown this once).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointSecretResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-endpoints/{endpoint}": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "get": { "operationId": "getWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "The endpoint, without its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Change a webhook endpoint", "description": "Only the fields sent change. `status` switches it off (`disabled`) or\non again (`active`, which also clears its failure count). New\n`events` follow the same rule as on creation. A new `url`, or\nswitching on again, also needs your credential to read every type the\nendpoint subscribes to. An app's endpoint cannot be switched on while\nits connection is not active.\n", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointPatch" } } } }, "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Remove a webhook endpoint", "description": "Deliveries still waiting for it are dropped.", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDeletedResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-endpoints/{endpoint}/rotate-secret": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "post": { "operationId": "rotateWebhookEndpointSecret", "tags": [ "Webhooks" ], "summary": "Rotate an endpoint's signing secret", "description": "Returns the new `secret`, once. For the next 24 hours deliveries carry\ntwo signatures (a `v1=` with the new secret and a `v1=` with the\nprevious one), so the receiver can switch without missing any.\n", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "The endpoint, with its new secret (shown this once).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointSecretResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-endpoints/{endpoint}/test": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "post": { "operationId": "testWebhookEndpoint", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Queues a `ping` event to this endpoint only; it is delivered within a minute, signed like any other.", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The test delivery, queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-endpoints/{endpoint}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" } ], "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List an endpoint's deliveries", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatusValue" } } ], "responses": { "200": { "description": "A page of deliveries, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhook-deliveries/{delivery}/redeliver": { "parameters": [ { "$ref": "#/components/parameters/WebhookDeliveryId" } ], "post": { "operationId": "redeliverWebhook", "tags": [ "Webhooks" ], "summary": "Redeliver an event", "description": "Starts a new series of attempts for the same event, with the same event id.", "security": [ { "apiKey": [ "webhooks:manage" ] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "The delivery, queued again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryResponse" } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "webhooks": { "invoice.created": { "post": { "summary": "An invoice draft was created", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invoice.issued": { "post": { "summary": "An invoice was issued", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invoice.zatca_status_changed": { "post": { "summary": "An invoice's ZATCA status changed", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invoice.payment_recorded": { "post": { "summary": "A payment was recorded, voided or deleted", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invoice.paid": { "post": { "summary": "An invoice was paid in full", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invoice.overdue": { "post": { "summary": "An invoice became overdue", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invoice.cancelled": { "post": { "summary": "A draft invoice was cancelled", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "credit_note.issued": { "post": { "summary": "A credit note was issued", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "debit_note.issued": { "post": { "summary": "A debit note was issued", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "credit_note.zatca_status_changed": { "post": { "summary": "A credit note's ZATCA status changed", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "debit_note.zatca_status_changed": { "post": { "summary": "A debit note's ZATCA status changed", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "customer.created": { "post": { "summary": "A customer was added", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "customer.updated": { "post": { "summary": "A customer was changed", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "ping": { "post": { "summary": "A test event you sent", "description": "Sent to each active endpoint of the company that subscribes to the\nevent, as an HTTPS `POST` with a JSON body. Answer any 2xx within 8\nseconds; anything else (a redirect included) is retried after 1, 5,\n30, 120, 360, 720 and 1440 minutes, then given up. Delivery is at\nleast once and in no guaranteed order: deduplicate on `WF-Event-Id`\nand read the object again when you need its current state.\n", "parameters": [ { "name": "WF-Event-Id", "in": "header", "required": true, "description": "The event id (`evt_…`); the same on every retry and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Event-Type", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/EventTypeValue" } }, { "name": "WF-Delivery-Id", "in": "header", "required": true, "description": "The delivery id (`whd_…`), for support and redelivery.", "schema": { "type": "string" } }, { "name": "WF-Api-Version", "in": "header", "required": true, "description": "The payload format, pinned per endpoint when it was created.", "schema": { "type": "string" } }, { "name": "WF-Signature", "in": "header", "required": true, "description": "`t=,v1=`. During a secret rotation a second `v1=`\nsigned with the previous secret follows. Refuse a `t` more than\n300 seconds from your clock and compare in constant time.\n", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A key from Settings → API, sent as `Authorization: Bearer ` (or\nin an `X-Api-Key` header). Never in the query string. The scopes an\noperation needs are listed in its security requirement. Every key\nexpires (30, 90, 180 or 365 days after it was created); an expired\nkey answers `401 token_expired` with `WWW-Authenticate: Bearer\nerror=\"invalid_token\", error_description=\"The API key has expired\"`.\n" }, "oauth2": { "type": "oauth2", "description": "An access token (`wfo_at_…`, or `wfo_test_at_…` for a sandbox\ncompany) of an app a company connected, sent as\n`Authorization: Bearer `. It acts for the company that\nconnected the app, as the person who approved it, with the scopes\ngranted. Authorization code with PKCE (S256, required for every app)\nfor apps that act for other companies; client credentials for a\nconfidential app acting for its own company. Tokens last an hour;\nrefresh tokens rotate on every use. Request `resource`\n`https://fatoora.tw.sa/api`. Available where app connections are\nswitched on.\n", "flows": { "authorizationCode": { "authorizationUrl": "https://fatoora.tw.sa/oauth/authorize", "tokenUrl": "https://fatoora.tw.sa/oauth/token", "refreshUrl": "https://fatoora.tw.sa/oauth/token", "scopes": { "companies:read": "Read the company profile and readiness", "customers:read": "Read customers", "customers:write": "Create and update customers", "products:read": "Read products and services (MCP tools)", "products:write": "Create and update products and services (MCP tools)", "invoices:read": "Read invoices, notes and their status", "invoices:draft": "Create draft invoices and notes, and validate them", "invoices:issue": "Issue invoices and notes (irreversible, reported to ZATCA)", "invoices:download": "Download invoice and note PDFs and legal XML", "payments:write": "Record customer payments on invoices (MCP tools)", "webhooks:manage": "Manage webhook endpoints" } }, "clientCredentials": { "tokenUrl": "https://fatoora.tw.sa/oauth/token", "scopes": { "companies:read": "Read the company profile and readiness", "customers:read": "Read customers", "customers:write": "Create and update customers", "products:read": "Read products and services (MCP tools)", "products:write": "Create and update products and services (MCP tools)", "invoices:read": "Read invoices, notes and their status", "invoices:draft": "Create draft invoices and notes, and validate them", "invoices:issue": "Issue invoices and notes (irreversible, reported to ZATCA)", "invoices:download": "Download invoice and note PDFs and legal XML", "payments:write": "Record customer payments on invoices (MCP tools)", "webhooks:manage": "Manage webhook endpoints" } } } } }, "parameters": { "InvoiceId": { "name": "invoice", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "CustomerId": { "name": "customer", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "NoteId": { "name": "note", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "Limit": { "name": "limit", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Cursor": { "name": "cursor", "in": "query", "description": "`meta.pagination.next_cursor` of the previous page.", "schema": { "type": "string", "maxLength": 200 } }, "WebhookEndpointId": { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, "WebhookDeliveryId": { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whd_[0-9A-HJKMNP-TV-Z]{26}$" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "8 to 255 visible ASCII characters, unique per operation you mean to perform.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } }, "responses": { "Error": { "description": "An error. `error.code` says which.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unsupported_api_version", "unauthorized", "invalid_token", "token_expired", "insufficient_scope", "forbidden", "plan_upgrade_required", "mode_mismatch", "not_found", "invoice_not_found", "customer_not_found", "note_not_found", "xml_not_applicable", "method_not_allowed", "invoice_not_draft", "invoice_immutable", "document_not_available", "idempotency_in_progress", "payload_too_large", "unsupported_media_type", "validation_failed", "invalid_reference", "invoice_requirements_missing", "invoice_not_issuable", "customer_vat_invalid", "credit_exceeds_invoice", "note_reason_required", "invoice_not_payable", "payment_exceeds_balance", "plan_limit_reached", "idempotency_key_reused", "rate_limited", "server_error", "service_unavailable" ] }, "message": { "type": "string" }, "details": { "type": "object", "description": "Field errors (field → messages), `required_scope`, `resource` and `limit`, `request_id`, `supported_versions` (for `unsupported_api_version`), or `expired_at` (ISO 8601) and `renew_url` (for `token_expired`), depending on the code." } } } } }, "Meta": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "description": "Also sent as the X-Request-Id header." }, "company_id": { "type": "integer", "description": "The company the key acts for." }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pagination": { "type": "object", "additionalProperties": false, "required": [ "next_cursor", "has_more", "limit" ], "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" } } }, "PingResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "authenticated", "tenant", "time" ], "properties": { "authenticated": { "const": true }, "tenant": { "type": "string" }, "time": { "type": "string", "format": "date-time" } } } } }, "Company": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mode", "zatca_linked" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "name_ar": { "type": [ "string", "null" ] }, "name_en": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "cr_number": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address_line1": { "type": [ "string", "null" ] }, "address_line2": { "type": [ "string", "null" ] }, "building_number": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "default_currency": { "type": "string" }, "default_language": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "`test` for a sandbox company." }, "plan": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "zatca_linked": { "type": "boolean", "description": "Whether invoices are submitted to ZATCA." } } }, "CompanyResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "company" ], "properties": { "company": { "$ref": "#/components/schemas/Company" } } } } }, "Problem": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "blocking" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "scope": { "type": "string", "enum": [ "company", "customer" ] }, "blocking": { "type": "boolean" } } }, "Readiness": { "type": "object", "additionalProperties": false, "required": [ "ready_to_issue", "problems", "zatca" ], "properties": { "ready_to_issue": { "type": "boolean" }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/Problem" } }, "zatca": { "type": "object", "additionalProperties": false, "required": [ "enabled", "linked", "onboarding" ], "properties": { "enabled": { "type": "boolean" }, "linked": { "type": "boolean" }, "onboarding": { "type": "object", "additionalProperties": false, "required": [ "complete", "done_count", "total", "steps" ], "properties": { "complete": { "type": "boolean" }, "done_count": { "type": "integer" }, "total": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "done" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } } } } } } } } } }, "ReadinessResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "readiness" ], "properties": { "readiness": { "$ref": "#/components/schemas/Readiness" } } } } }, "Customer": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "type", "status" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "name_ar": { "type": [ "string", "null" ] }, "name_en": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "individual", "business" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "mobile": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "cr_number": { "type": [ "string", "null" ] }, "id_scheme": { "type": [ "string", "null" ] }, "id_number": { "type": [ "string", "null" ] }, "contact_person": { "type": [ "string", "null" ] }, "address_line1": { "type": [ "string", "null" ] }, "address_line2": { "type": [ "string", "null" ] }, "building_number": { "type": [ "string", "null" ] }, "additional_number": { "type": [ "string", "null" ] }, "district": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "national_address": { "type": [ "string", "null" ] }, "payment_terms": { "type": [ "integer", "null" ] }, "credit_limit": { "type": [ "number", "null" ] }, "preferred_locale": { "type": [ "string", "null" ], "enum": [ "ar", "en", null ] }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CustomerInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 191 }, "name_ar": { "type": [ "string", "null" ], "maxLength": 191 }, "name_en": { "type": [ "string", "null" ], "maxLength": 191 }, "type": { "type": [ "string", "null" ], "enum": [ "individual", "business", null ], "description": "Defaults to business." }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive", null ] }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Unique within the company." }, "phone": { "type": [ "string", "null" ], "maxLength": 32 }, "mobile": { "type": [ "string", "null" ], "maxLength": 32 }, "vat_number": { "type": [ "string", "null" ], "description": "A Saudi buyer's VAT number: 15 digits, first and last 3. Unique within the company." }, "cr_number": { "type": [ "string", "null" ] }, "id_scheme": { "type": [ "string", "null" ], "enum": [ "TIN", "CRN", "MOM", "MLS", "700", "SAG", "NAT", "GCC", "IQA", "PAS", "OTH", null ] }, "id_number": { "type": [ "string", "null" ], "maxLength": 64 }, "contact_person": { "type": [ "string", "null" ], "maxLength": 191 }, "address_line1": { "type": [ "string", "null" ], "maxLength": 191 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 191 }, "building_number": { "type": [ "string", "null" ], "description": "4 digits for a Saudi address." }, "additional_number": { "type": [ "string", "null" ], "description": "4 digits for a Saudi address." }, "district": { "type": [ "string", "null" ], "maxLength": 120 }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "postal_code": { "type": [ "string", "null" ], "maxLength": 20 }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2; defaults to SA." }, "national_address": { "type": [ "string", "null" ], "maxLength": 120 }, "payment_terms": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "credit_limit": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999.99 }, "preferred_locale": { "type": [ "string", "null" ], "enum": [ "ar", "en", null ] }, "notes": { "type": [ "string", "null" ], "maxLength": 10000 } } }, "CustomerPatch": { "description": "Any fields of CustomerInput; only those sent change.", "type": "object", "properties": { "name": { "type": "string", "maxLength": 191 } }, "additionalProperties": true }, "CustomerResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "customer" ], "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } }, "CustomerListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "customers" ], "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } } }, "InvoiceStatusValue": { "type": "string", "enum": [ "draft", "issued", "sent", "viewed", "partial", "paid", "overdue", "cancelled", "refunded" ] }, "ZatcaStatusValue": { "type": "string", "enum": [ "pending", "not_submitted", "cleared", "reported", "rejected", "retrying", "unknown" ] }, "Zatca": { "type": "object", "additionalProperties": false, "required": [ "flow", "status", "with_warnings", "deliverable", "errors" ], "description": "Where the document stands with ZATCA. `status` is null when nothing is\nsubmitted for it (a draft, or a company not linked to ZATCA).\n`deliverable` is false until the document may be handed to the buyer:\na standard (B2B) invoice of a linked company only once ZATCA cleared it.\n", "properties": { "flow": { "type": [ "string", "null" ], "enum": [ "clearance", "reporting", null ] }, "status": { "oneOf": [ { "$ref": "#/components/schemas/ZatcaStatusValue" }, { "type": "null" } ] }, "with_warnings": { "type": "boolean" }, "uuid": { "type": [ "string", "null" ] }, "deliverable": { "type": "boolean" }, "errors": { "type": "array", "description": "ZATCA's own messages, for a rejected document.", "items": { "type": "string" } } } }, "PartySummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "vat_number" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "vat_number": { "type": [ "string", "null" ] } } }, "InvoiceLine": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit", "unit_price", "discount", "vat_rate", "vat_amount", "total" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": [ "string", "null" ] }, "unit_price": { "type": "number" }, "discount": { "type": "number" }, "vat_rate": { "type": "number" }, "vat_amount": { "type": "number" }, "total": { "type": "number" } } }, "Invoice": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "number_is_final", "status", "source", "currency", "issue_date", "due_date", "customer", "subtotal", "discount_total", "vat_total", "total", "items", "public_url", "zatca", "created_at" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string", "description": "The tax-invoice number once issued; a draft reference (DRAFT-…) before." }, "number_is_final": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/InvoiceStatusValue" }, "source": { "type": "string", "description": "Where the invoice was created." }, "currency": { "type": "string" }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/PartySummary" }, { "type": "null" } ] }, "subtotal": { "type": "number" }, "discount_total": { "type": "number" }, "vat_total": { "type": "number" }, "total": { "type": "number" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "public_url": { "type": [ "string", "null" ], "format": "uri" }, "zatca": { "$ref": "#/components/schemas/Zatca" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceIdentity": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "status" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatusValue" } } }, "InvoiceInput": { "type": "object", "required": [ "issue_date", "items" ], "properties": { "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "issue": { "type": [ "boolean", "null" ], "default": true, "description": "`false` creates a draft." }, "currency": { "type": [ "string", "null" ], "description": "Defaults to SAR." }, "exchange_rate": { "type": [ "number", "null" ], "description": "SAR per unit of `currency`; required for a foreign currency." }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "en", null ] }, "notes": { "type": [ "string", "null" ], "maxLength": 5000 }, "terms": { "type": [ "string", "null" ], "maxLength": 5000 }, "external_reference": { "type": [ "string", "null" ], "maxLength": 191, "description": "Your own id for the sale." }, "source_system": { "type": [ "string", "null" ], "maxLength": 191 }, "document_discount_type": { "type": [ "string", "null" ], "enum": [ "amount", "percent", null ] }, "document_discount_value": { "type": [ "number", "null" ], "minimum": 0 }, "payment": { "type": [ "object", "null" ], "description": "Paid already: recorded with the invoice, which then arrives `paid` (or `partial`). Needs `payments:write`; not with `issue: false`.", "properties": { "amount": { "type": [ "number", "null" ], "minimum": 0.01, "description": "Defaults to the invoice total." }, "method": { "type": [ "string", "null" ], "maxLength": 50, "description": "cash (default), bank_transfer, mada, visa_mastercard, apple_pay, stc_pay, cheque, other, or a code the company added." }, "reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Your gateway transaction id, for example." }, "paid_on": { "type": [ "string", "null" ], "format": "date", "description": "Defaults to today; never later than today." }, "notes": { "type": [ "string", "null" ], "maxLength": 500 }, "account_id": { "type": [ "integer", "null" ], "description": "The company cash or bank account the money went into." } } }, "customer": { "type": [ "object", "null" ], "description": "An existing customer by `id`, or a new one by its details.", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "individual", "business", null ], "description": "Defaults to business with a VAT number, individual without. A Saudi business gets a standard invoice even without a VAT number." }, "cr_number": { "type": [ "string", "null" ], "description": "Commercial registration; 10 digits for a Saudi buyer." }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address_line1": { "type": [ "string", "null" ] }, "address_line2": { "type": [ "string", "null" ], "maxLength": 191 }, "building_number": { "type": [ "string", "null" ], "description": "National address building number; 4 digits for a Saudi buyer." }, "additional_number": { "type": [ "string", "null" ], "description": "National address additional number; 4 digits for a Saudi buyer." }, "district": { "type": [ "string", "null" ], "maxLength": 120 }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] } } }, "items": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0.001 }, "unit_price": { "type": "number", "minimum": 0 }, "unit": { "type": [ "string", "null" ] }, "discount": { "type": [ "number", "null" ], "minimum": 0 }, "vat_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "tax_rate_id": { "type": [ "integer", "null" ] }, "product_id": { "type": [ "integer", "null" ] }, "vat_exemption_code": { "type": [ "string", "null" ] }, "vat_exemption_reason": { "type": [ "string", "null" ] } } } } } }, "InvoiceResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "payment": { "$ref": "#/components/schemas/Payment" } } } } }, "Payment": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "invoice_id", "amount", "currency", "method", "account_id", "reference", "notes", "paid_on", "status", "voided_at", "created_at" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string", "description": "The receipt number." }, "invoice_id": { "type": "integer" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "method": { "type": "string" }, "account_id": { "type": [ "integer", "null" ] }, "reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "paid_on": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "recorded", "voided" ] }, "voided_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceBalance": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "status", "currency", "total", "paid_total", "balance" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatusValue" }, "currency": { "type": "string" }, "total": { "type": "number" }, "paid_total": { "type": "number" }, "balance": { "type": "number", "description": "Still owed, after issued credit notes." } } }, "PaymentInput": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "minimum": 0.01, "description": "In the invoice currency; at most the balance." }, "method": { "type": [ "string", "null" ], "maxLength": 50, "description": "cash (default), bank_transfer, mada, visa_mastercard, apple_pay, stc_pay, cheque, other, or a code the company added." }, "reference": { "type": [ "string", "null" ], "maxLength": 120 }, "paid_on": { "type": [ "string", "null" ], "format": "date", "description": "Defaults to today; never later than today." }, "notes": { "type": [ "string", "null" ], "maxLength": 500 }, "account_id": { "type": [ "integer", "null" ], "description": "The company cash or bank account the money went into." } } }, "PaymentResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "payment", "invoice" ], "properties": { "payment": { "$ref": "#/components/schemas/Payment" }, "invoice": { "$ref": "#/components/schemas/InvoiceBalance" } } } } }, "PaymentListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "payments", "invoice" ], "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "invoice": { "$ref": "#/components/schemas/InvoiceBalance" } } } } }, "InvoiceReplayResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "invoice", "replayed" ], "properties": { "invoice": { "oneOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/InvoiceIdentity" } ] }, "replayed": { "const": true }, "replay_payload_matches": { "type": [ "boolean", "null" ], "description": "false when the repeat's body differs from the original's; null when it cannot be told." } } } } }, "InvoiceListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "invoices" ], "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } } }, "InvoiceStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "number_is_final", "status", "paid_total", "zatca", "deliverable", "updated_at" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "number_is_final": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/InvoiceStatusValue" }, "paid_total": { "type": "number" }, "zatca": { "$ref": "#/components/schemas/Zatca" }, "deliverable": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "InvoiceStatusResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/InvoiceStatus" } } } } }, "ValidationResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "issuable", "problems" ], "properties": { "issuable": { "type": "boolean" }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/Problem" } } } } } }, "IssueInvoiceResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "invoice", "already_issued" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "already_issued": { "type": "boolean" } } } } }, "NoteLine": { "type": "object", "additionalProperties": false, "required": [ "description", "quantity", "unit_price", "vat_rate", "vat_amount", "total" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "vat_rate": { "type": "number" }, "vat_amount": { "type": "number" }, "total": { "type": "number" } } }, "NoteZatca": { "type": "object", "additionalProperties": false, "required": [ "flow", "status", "with_warnings", "deliverable", "errors" ], "properties": { "flow": { "type": [ "string", "null" ], "enum": [ "clearance", "reporting", null ] }, "status": { "oneOf": [ { "$ref": "#/components/schemas/ZatcaStatusValue" }, { "type": "null" } ] }, "with_warnings": { "type": "boolean" }, "deliverable": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "Note": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "number_is_final", "type", "status", "invoice_id", "currency", "issue_date", "reason", "notes", "customer", "subtotal", "vat_total", "total", "items", "public_url", "zatca", "issued_at", "created_at" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "number_is_final": { "type": "boolean" }, "type": { "type": "string", "enum": [ "credit", "debit" ] }, "status": { "type": "string", "enum": [ "draft", "issued", "cancelled" ] }, "invoice_id": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "reason": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/PartySummary" }, { "type": "null" } ] }, "subtotal": { "type": "number" }, "vat_total": { "type": "number" }, "total": { "type": "number" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NoteLine" } }, "public_url": { "type": [ "string", "null" ], "format": "uri" }, "zatca": { "$ref": "#/components/schemas/NoteZatca" }, "issued_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "NoteInput": { "type": "object", "required": [ "type", "reason", "items" ], "properties": { "type": { "type": "string", "enum": [ "credit", "debit" ] }, "reason": { "type": "string", "maxLength": 255, "description": "Why the invoice is corrected; printed on the note." }, "issue_date": { "type": [ "string", "null" ], "format": "date", "description": "Defaults to today." }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "issue": { "type": [ "boolean", "null" ], "default": false }, "items": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "required": [ "description", "quantity", "unit_price", "vat_rate" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0.001 }, "unit_price": { "type": "number", "minimum": 0 }, "vat_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "One of the invoice's own VAT rates." }, "tax_rate_id": { "type": [ "integer", "null" ] }, "vat_exemption_code": { "type": [ "string", "null" ] } } } } } }, "NoteResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "note" ], "properties": { "note": { "$ref": "#/components/schemas/Note" } } } } }, "NoteListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "notes" ], "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } } } } } }, "IssueNoteResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "note", "already_issued" ], "properties": { "note": { "$ref": "#/components/schemas/Note" }, "already_issued": { "type": "boolean" } } } } }, "EventTypeValue": { "type": "string", "enum": [ "invoice.created", "invoice.issued", "invoice.zatca_status_changed", "invoice.payment_recorded", "invoice.paid", "invoice.overdue", "invoice.cancelled", "credit_note.issued", "debit_note.issued", "credit_note.zatca_status_changed", "debit_note.zatca_status_changed", "customer.created", "customer.updated" ] }, "EventData": { "type": "object", "additionalProperties": false, "required": [ "object" ], "description": "`object` is the subject as the API represents it (an Invoice for\ninvoice events, a Note for note events, a Customer for customer\nevents), as it stood when the change was committed.\n", "properties": { "object": { "type": "object" }, "payment": { "type": "object", "additionalProperties": false, "description": "For `invoice.payment_recorded`, the payment and what happened to it.", "required": [ "id", "amount", "currency", "status" ], "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "amount": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ] }, "paid_on": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "recorded", "voided", "deleted" ] } } }, "previous_zatca_status": { "description": "For the `*.zatca_status_changed` events, the status before the change.", "oneOf": [ { "$ref": "#/components/schemas/ZatcaStatusValue" }, { "type": "null" } ] } } }, "Event": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "description": "`evt_` followed by a time-ordered id." }, "type": { "$ref": "#/components/schemas/EventTypeValue" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "livemode": { "type": "boolean", "description": "false for a sandbox company's events." }, "data": { "$ref": "#/components/schemas/EventData" } } }, "EventListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } }, "WebhookPayload": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "api_version", "created_at", "livemode", "company_id", "connection_id", "data" ], "properties": { "id": { "type": "string", "description": "The event id, also in WF-Event-Id." }, "type": { "type": "string", "description": "An event type, or `ping` for a test." }, "api_version": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "livemode": { "type": "boolean" }, "company_id": { "type": "integer", "description": "The company the event belongs to." }, "connection_id": { "type": "null", "description": "Reserved for app connections." }, "data": { "$ref": "#/components/schemas/EventData" } } }, "WebhookEndpointStatusValue": { "type": "string", "enum": [ "active", "disabled" ] }, "WebhookEndpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "url", "description", "events", "api_version", "livemode", "status", "disabled_reason", "consecutive_failures", "previous_secret_expires_at", "last_success_at", "last_failure_at", "created_at", "updated_at" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "description": "Event types sent to it. `*` (set on the dashboard only) means every type, including ones added later; through the API, `*` is stored as the types the credential can read.", "items": { "type": "string" } }, "api_version": { "type": "string" }, "livemode": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/WebhookEndpointStatusValue" }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "manual", "failing", "connection_revoked", "connection_suspended", null ], "description": "`failing`: switched off automatically after 100 failures in a row and 72 hours without a success. `connection_revoked`, `connection_suspended`: the connection of the app that registered it was revoked, or suspended because the person who connected it can no longer manage settings." }, "consecutive_failures": { "type": "integer" }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "While a rotated secret still signs (as a second `v1=`), until when." }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEndpointWithSecret": { "type": "object", "additionalProperties": false, "required": [ "id", "url", "events", "api_version", "livemode", "status", "secret" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "description": "Event types sent to it. `*` (set on the dashboard only) means every type, including ones added later; through the API, `*` is stored as the types the credential can read.", "items": { "type": "string" } }, "api_version": { "type": "string" }, "livemode": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/WebhookEndpointStatusValue" }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ "manual", "failing", "connection_revoked", "connection_suspended", null ], "description": "`failing`: switched off automatically after 100 failures in a row and 72 hours without a success. `connection_revoked`, `connection_suspended`: the connection of the app that registered it was revoked, or suspended because the person who connected it can no longer manage settings." }, "consecutive_failures": { "type": "integer" }, "previous_secret_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "While a rotated secret still signs (as a second `v1=`), until when." }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string", "description": "`whsec_…`. Shown in this answer only." } } }, "WebhookEndpointInput": { "type": "object", "additionalProperties": false, "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "An event type your credential can read, or `*` for all of those." } }, "description": { "type": [ "string", "null" ], "maxLength": 255 } } }, "WebhookEndpointPatch": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "status": { "$ref": "#/components/schemas/WebhookEndpointStatusValue" } } }, "WebhookEndpointResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "webhook_endpoint" ], "properties": { "webhook_endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } }, "WebhookEndpointSecretResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "webhook_endpoint" ], "properties": { "webhook_endpoint": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } } }, "WebhookEndpointListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "webhook_endpoints" ], "properties": { "webhook_endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "WebhookEndpointDeletedResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "deleted", "id" ], "properties": { "deleted": { "const": true }, "id": { "type": "integer" } } } } }, "WebhookDeliveryStatusValue": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed", "abandoned" ] }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "endpoint_id", "event_id", "event_type", "status", "attempts", "next_attempt_at", "last_response", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "`whd_` followed by a time-ordered id." }, "endpoint_id": { "type": "integer" }, "event_id": { "type": "string" }, "event_type": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatusValue" }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_response": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "status": { "type": [ "integer", "null" ], "description": "The receiver's HTTP status, if it answered." }, "duration_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "enum": [ "invalid_url", "dns_refused", "private_address", "timeout", "tls", "connection_failed", "redirect", "http_4xx", "http_5xx", "endpoint_disabled", null ] }, "excerpt": { "type": [ "string", "null" ], "description": "The first 512 bytes of the answer, control characters removed." } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookDeliveryResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "delivery" ], "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery" } } } } }, "WebhookDeliveryListResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "additionalProperties": false, "required": [ "deliveries" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } } } }