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
-
π£ C# / .NET
-
π 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/)
βοΈ Rigorously tested with fuzzing and ~97% coverage
π₯ Installation
The package uses namespace Fatoora and includes native libraries for Linux x64,
Windows x64, and macOS arm64.
See the C# reference for installation, deterministic
disposal, prepared HTTP requests, and package verification.
Install a published release from Maven Central.
Gradle (build.gradle.kts):
repositories { mavenCentral() }
dependencies {
implementation("com.fatoority:fatoority:0.4.3")
}
Maven (pom.xml):
com.fatoority
fatoority
0.4.3
For Android, use com.fatoority:fatoority-android:0.4.3 instead of the desktop
artifact. Java/Kotlin imports remain com.fatoora.
The desktop package runs on Java 8+ and bundles Linux x86-64, Windows x86-64 and
macOS arm64 native libraries. Android supports API 26+ on arm64-v8a / x86_64.
See the Kotlin / Java reference
for Android installation, platform prerequisites, ownership and coroutines.
For unpublished versions, use the
local build instructions.
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.