An unofficial open-source toolkit for everything you'd need for ZATCA (Zakat, Tax and Customs Authority of Saudi Arabia) Phase 1 and 2 compliant e-invoicing.
With bindings and support for many programming languages:
-
๐ฆ Rust
-
๐ Python
-
JavaScript / TypeScript: WASM package for Node and browsers
-
๐ C/C++ (through the C FFI see
)
-
๐ Also, a Command Line Interface (CLI) Tool
Disclaimer:
fatoority is not affiliated, associated, authorized, endorsed by, or in any way officially connected with ZATCA (Zakat, Tax and Customs Authority), or any of its subsidiaries or its affiliates. The official ZATCA website can be found at https://zatca.gov.sa.
๐๏ธ Documentation
Checkout the homepage, also the Rust API at docs.rs may prove useful.
โก Features
Everything done by the official ZATCA SDK
- ๐ฉ CSR Generation
- โ๏ธ Invoice Signing (All invoice types)
- โ Validation (UBL and local ZATCA rules)
- ๐งพ QR Generation
- ๐จ API Requests
๐ But we do it faster and better e.g. ~190x faster invoice hashing than ZATCA's SDK (see bench/)
๐งฉ Dependencies
XML parsing, signing edits, canonicalization, and XSD validation use Rust crates. The library, CLI, and bindings do not require a system libxml2 installation.
๐ฅ Installation
cargo add fatoora-core
pip install fatoority
Build the package from a source checkout (Node 22+, npm, Rust and Python 3):
( && )
Install the resulting .tgz in your application with npm install /path/to/fatoority-0.4.1.tgz.
Generated bindings are checked in. Version tags publish the tested package to npm through GitHub Actions.
import from 'fatoority';
const key = ;
const report = JSON.;
console.log;
The WASM package includes the Rust validator and bundled UBL schemas. See JavaScript / TypeScript for async fetch, errors, decimal strings, browser setup, and measured artifact sizes.
Download the fatoora-ffi-* archive for your platform from
releases and extract it. The shared
library is at the archive root. The C API header is include/fatoora.h,
with its adapter in src/fatoora.c and generated headers in include/generated; C++ headers
are in include/diplomat-cpp and expose types in namespace fatoora.
For example, on Linux, compile your application from the extracted directory:
Include fatoora.h in C or fatoora/Config.hpp in C++. Keep the shared library
beside these executables. On Windows, link the supplied import library and keep
the DLLs from the archive beside your executable.
To build the library from a source checkout:
The C API
provides one fatoora.h, plain strings, shared errors, and named-field options.
Compile bindings/c/fatoora.c once with your application, add bindings/c to
your include path, and link fatoora_ffi. Release archives also include the C
examples under examples/c.
The library is written to target/release/. The generated headers are checked in
under bindings/c/generated and bindings/cpp; raw ABI callers use those include paths and
-Ltarget/release when compiling against a source build. Cargo does not regenerate
headers. After changing bridge declarations, follow the
Diplomat generation workflow.
The cli tool can also be installed with cargo:
cargo install fatoora-cli
Alternatively, you can grab the precompiled binary for your platform on the repo's releases (fatoora-cli-*). Extract the archive and run fatoora.
๐ก Examples
Rust
use EnvironmentType;
use ;
let props_text = read_to_string?;
let props = from_properties_str?;
let key = generate;
let csr = props.build?;
let csr_pem = csr.to_pem?;
let key_pem = key.to_pem?;
Python
=
=
=
=
=
JavaScript
import from 'fatoority';
const key = ;
const csr = .;
const csrPem = csr.;
CLI
Rust
use InvoiceSigner;
let cert_pem = read_to_string?;
let key_pem = read_to_string?;
let signer = from_pem?;
let xml = read_to_string?;
let signed_xml = signer.sign_xml?;
CLI
Rust
use Config;
use ;
let config = new;
let xml = read_to_string?;
let options = ZatcaValidationOptions ;
let report = validate_zatca_invoice_from_str?;
if !report.is_valid
CLI
The local profile implements all 257 business-rule assertions from SDK
238-R3.4.8, plus applicable signature, QR and predecessor checks. It preserves
warnings and partial reports. Standard invoices skip signature/QR checks under
this SDK profile. Local validation does not establish issuer trust or remote
acceptance. Existing validate_xml_invoice_from_str and the default CLI profile
continue to check XSD only.
Rust
use parse_signed_invoice_xml;
let xml = read_to_string?;
let signed = parse_signed_invoice_xml?;
let qr = signed.qr_code;
CLI
Rust
use parse_finalized_invoice_xml;
let xml = read_to_string?;
let invoice = parse_finalized_invoice_xml?;
let hash = invoice.hash_base64?;
CLI
Rust
use parse_signed_invoice_xml;
let xml = read_to_string?;
let signed = parse_signed_invoice_xml?;
let payload = json!;
CLI
And much more... see the guides in the homepage for more info.
๐ค Contributing
Contributions are always welcome! See CONTRIBUTING.md for more details.
๐ชง Roadmap
- Increase test coverage to 100% (Inshallah)
- Expand bindings to other languages (subject to demand)
- PDF invoice generation
Author ๐ค
This project began as a personal undertaking, and continues to be developed and maintained by me @mqqz.
While this means development happens alongside other commitments, I do my best to keep the project maintained and responsive to issues. Contributions, feedback, and suggestions are always welcome.
If you or your team are working on fintech or ZATCA integrations and need help building reliable scalable infrastructure, feel free to get in touch.
๐ Relevant Links
License
This project's code is licensed under either the MIT License or the Apache License, Version 2.0, at your option.
Third-party schemas, fixtures, templates, and dependencies retain their applicable upstream licenses and notices. The project license does not relicense those materials.
See third-party notices for attribution, applicable terms, and outstanding permission questions.