ZATCA e-invoicing in Rust

By Matheel · Updated

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

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.

Try it now on the developer sandbox

No key, no signup: a real ZATCA answer, with the bilingual PDF and the QR.

Start Pricing