fatoority is an unofficial open-source toolkit for developers building e-invoicing integrations
in Saudi Arabia. Sign invoice XML, validate it locally, generate QR payloads, and
connect to ZATCA APIs for Phase 1 and Phase 2 workflows.
With bindings and support for many programming languages:
-
π¦ Rust
-
π Python
-
π―βπΈβ JavaScript / TypeScript
-
π£ C# / .NET
-
β Kotlin / Java / Android
-
π C/C++ (through the C FFI see releases)
-
π Also, a Command Line Interface (CLI) Tool
Disclaimer:
fatoorityis 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
Tools for your ZATCA integration:
- π© CSR Generation
- βοΈ Invoice Signing (Standard and simplified invoices, credit notes, and debit notes)
- β 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
See the benchmarks for measured performance and methodology, and SDK compatibility notes for the scope of comparison with the official SDK. Local validation does not establish certificate issuer trust or ZATCA gateway acceptance.
π₯ Installation
Install a published release from Maven Central.
Gradle (build.gradle.kts):
repositories { mavenCentral() }
dependencies {
implementation("com.fatoority:fatoority:0.5.0")
}
Maven (pom.xml):
com.fatoority
fatoority
0.5.0
For Android, use com.fatoority:fatoority-android:0.5.0 instead of the desktop
artifact. Java/Kotlin imports remain com.fatoora.
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.