Description
n8n-nodes-zatca-tools
Issue Saudi ZATCA Phase 2 e-invoices from any n8n workflow — signed, QR-coded, and reported to the Zakat, Tax and Customs Authority.
ZATCA Tools is a Saudi e-invoicing service. This node talks to its REST API, so your workflow never handles certificates, XML signing or the Fatoora platform.
Installation · Operations · Credentials · Compatibility · Resources
Installation
Follow the community nodes installation guide and use the package name:
n8n-nodes-zatca-tools
Operations
ZATCA Tools
| Resource | Operation | What it does |
| — | — | — |
| Invoice | Create | Builds, signs and reports a tax invoice. Simplified (B2C) or Standard (B2B). |
| Invoice | Get | One invoice by uuid, with its ZATCA status and links. |
| Invoice | Get Many | Newest first; filter by kind, status or since. |
| Invoice | Email | Sends the signed PDF to the buyer. |
| Note | Create | A credit note (reduce) or debit note (increase) against an issued invoice. |
| Account | Get | Your establishment and the invoices left in your quota. |
ZATCA Tools Trigger
Fires when a document is issued — an invoice, a credit note, a debit note, or any of them. Poll-based, so no public webhook URL is needed.
The first run records where it is and emits nothing. Without that, switching a workflow on would fire it once for every invoice in your history.
Credentials
1. Create a free account at sandbox quickstart.
What does the node not do? It never builds XML, signs, or talks to ZATCA itself — the service does (UBL 2.1, XAdES signature, ICV/PIH chain, TLV QR, reporting/clearance). Your workflow sends invoice JSON and gets back the status, QR, XML and PDF.
Can one workflow invoice for several establishments? One credential = one establishment (one certificate, one invoice chain). Use one credential per establishment, or the rejection codes cheat sheet.
VAT per line (1.1.0)
Each invoice line can carry its own VAT Treatment: Standard Rate (15%), Zero-Rated (0%), Exempt or Out of Scope. Left on Establishment Default, it takes your establishment’s own treatment, as every line did before 1.1.0. A zero-rated or exempt line may name its Exemption Reason (ZATCA’s VATEX-SA-… list). The reason is optional: left empty, the line takes the reason its sibling lines name, else the one your establishment used last, else none, which ZATCA accepts with a warning. One invoice can mix treatments, for example a taxed haircut beside a tip that is out of scope.
Turn on Prices Include VAT under Additional Fields to send what the customer pays. Each line’s VAT is then taken out at its own rate.
Two things worth knowing
Set External ID. It is your own id for the sale (order-5501). Send it again — after a retry, a duplicated run, a re-activated workflow — and you get the same invoice back instead of a second one. An e-invoice cannot be deleted once ZATCA has accepted it, so this is the difference between a mistake and a permanent one.
Cancelling is a credit note, not a delete. The Cancel the Whole Invoice toggle reverses an invoice for its open balance, computed on the server so an earlier partial refund is never credited twice. To put a cancelled sale back, issue a debit note.
Compatibility
Tested against n8n 1.x with n8n-workflow 2.x. Requires Node 20.15+.
