ZATCA e-invoicing in Rust
One HTTP request from Rust (reqwest + sqlx): Matheel builds the invoice, signs it, files it with ZATCA and returns ZATCA's answer, the legal XML and the PDF with the QR.
1. Try it now (no key)
// reqwest (blocking, json) + serde_json
let res: serde_json::Value = reqwest::blocking::Client::new()
.post("https://matheel.app/api/v1/invoices")
.json(&serde_json::json!({ "environment": "sandbox", "pdf": true, "invoice": {
"type": "simplified", "line_items": [{ "name": "قهوة", "quantity": 2, "price": "50.00" }] } }))
.send()?.json()?;
println!("{}", res["status"]); // "reported"
2. The ready function, after payment
It locks the device row (so two payments at once never fork the chain), files the invoice with "pdf": true and saves the new device_token. Any non-200 rolls the transaction back and the old token stays valid.
// sqlx (Postgres) + reqwest (json) + serde_json + anyhow. Dropping `tx` without commit rolls back.
pub async fn matheel_invoice(pool: &sqlx::PgPool, items: serde_json::Value) -> anyhow::Result<serde_json::Value> {
let mut tx = pool.begin().await?;
let token: String = sqlx::query_scalar("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE")
.fetch_one(&mut *tx).await?;
let r = reqwest::Client::new()
.post("https://matheel.app/api/v1/invoices")
.bearer_auth(std::env::var("MATHEEL_KEY")?)
.json(&serde_json::json!({ "device_token": token, "pdf": true,
"invoice": { "type": "simplified", "line_items": items } }))
.send().await?;
let status = r.status();
let res: serde_json::Value = r.json().await?;
anyhow::ensure!(status == 200, "matheel {status}: {res}");
sqlx::query("UPDATE matheel_device SET token = $1 WHERE id = 1")
.bind(res["device_token"].as_str()).execute(&mut *tx).await?;
tx.commit().await?;
Ok(res) // base64-decode res["pdf"] for the PDF
}
3. For production
- Register your device once (device token or an activation link) and put its
device_tokenin thematheel_devicetable. - If your amount includes VAT, send
"prices_include_vat": true. - Keep
invoice_xml(the legal copy) andpdfwith the order; your app shows the PDF from your server.
FAQ
Do I need a ZATCA library for Rust?
No. Matheel is a plain JSON API: one HTTP request. Signing, the XML, the certificate and filing with ZATCA all happen at Matheel.
Where do I keep the device token?
One row in your database (a matheel_device table). After every 200, save the new device_token in the same transaction.
Can I try before subscribing?
Yes, on the developer sandbox without a key: the request below returns ZATCA's real answer and the PDF.