n8n and Saudi e-invoicing — issue ZATCA invoices from your workflow

See it working

A full recording, from installation to an invoice accepted by the Authority. There is no sound, so jump to any step from the list below it.

Set up in five minutes

1

Install the package

In n8n, open Settings → Community Nodes → Install and paste the package name.
2

Create a free account

Sign up at zatcatools.com and connect your business to the Fatoora platform.
3

Copy your API key

From Settings → API. The key starts with ztk_live_
4

Add the credential

In n8n, add a ZATCA Tools API credential and paste the key. It is tested immediately, so a wrong key fails now rather than at your first invoice.

npm install n8n-nodes-zatca-tools

Available operations

Resource	Operation	What it does
Invoice	Create	Builds the invoice, signs it and sends it to the Authority — simplified (B2C) or a tax invoice (B2B).
Invoice	Get	A single invoice by its id, with its status at the Authority and its links.
Invoice	Get many	Newest first, with filtering by type, status or date.
Invoice	Send by email	Sends the signed PDF file to the buyer.
Note	Create	A credit note (a reduction) or a debit note (an increase) against an issued invoice.
Account	Get	Your business details and the balance remaining on your plan.

There is also a second trigger node — ZATCA Tools Trigger — which fires whenever any document is issued. It works by polling, so it needs no public webhook URL, and the first run records only the starting point. Without that, activating the workflow would have fired it once for every invoice in your history.

Two points that save you a permanent mistake

Always set an External ID

It is your own identifier for the transaction (order-5501). Send it again — after a retry, a duplicate run, or re-activating the workflow — and you get back the same invoice instead of a second one. And an invoice the Authority has accepted cannot be deleted, and that is the difference between a mistake and a permanent one.

Cancelling means a credit note, not a deletion

The "cancel the whole invoice" switch reverses the invoice against its open balance, and the amount is worked out on the server so a sum already partly refunded is not refunded again. To reinstate a cancelled transaction you issue a Debit note. Read the difference between the two notes.

Why connect n8n to e-invoicing?

n8n is an open-source automation tool that connects your systems together without writing a full service. In Saudi e-invoicing it solves a common problem: your source of sales is not a ready-made store with an existing integration — it may be an in-house system, a spreadsheet, a form or a database. Instead of building a custom integration for every source, you drop a single node at the end of the workflow and a compliant invoice comes out of it.

Practical examples

In-house system or ERP:When a sale is recorded, the workflow fires, issues the invoice and sends the PDF to the customer.
Google Sheets:A new row in your sales sheet turns into a simplified tax invoice automatically.
Forms and payments:An order form or a payment notification produces an invoice as soon as payment is confirmed.
Accounting sync:Use the trigger to push every issued document into your accounting system or a notification channel.
Returns:A return in your system issues a credit note for the refunded amount.

What you never have to deal with

The node talks to the the ZATCA Tools API, and all the heavy lifting happens in the service: building the invoice in UBL 2.1, the digital signature with your business certificate, the hash chain (PIH/ICV), clearance or reporting to the Fatoora platform, and generating the matching QR code. Your workflow only sends the sale data.

Privacy and keys

Your API key is stored in n8n itself as an encrypted credential, and it never appears in the node's output. If you think your key has leaked, revoke it from Settings and issue another — revocation is immediate.

Frequently asked questions

Yes. The package is open source under the MIT licence, and the ZATCA Tools account it connects to is free as well — no credit card.

No. The node talks to the ZATCA Tools API, and the digital signature, the UBL 2.1 build and the submission to the Fatoora platform all happen in the service — your workflow never touches a certificate.

Use the External ID field and put your own identifier for the transaction in it, such as order-5501. Sending again with the same identifier returns the same invoice instead of creating a second one — which matters, because an invoice the Authority has accepted cannot be deleted.

Cancelling is done with a credit note, not a deletion. The "cancel the whole invoice" switch reverses the invoice against its open balance, and the amount is worked out on the server so nothing already refunded is refunded twice. To reverse a cancelled transaction you issue a debit note.

Yes, it is called ZATCA Tools Trigger — a node that fires whenever any document is issued: an invoice, a credit note or a debit note. It works by polling, so it needs no public webhook URL. The first run records only the starting point and fires nothing, so the workflow does not run away with your entire history.

Tested with n8n 1.x and n8n-workflow 2.x; it requires Node 20.15 or newer.

Links

The package on npm ↗ The source code on GitHub ↗ ZATCA Tools API documentation The rest of the free tools

Ready to connect your workflow?

The account is free, and connecting to the Fatoora platform takes less than five minutes.

Try ZATCA Tools, completely free