ربط زاتكا بـ Rust
طلب HTTP واحد من Rust (reqwest + sqlx): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ XML القانوني والـ PDF مع رمز QR.
١. جرّبه الحين (بدون مفتاح)
// 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"
٢. الدالة الجاهزة بعد الدفع
تقفل صف الجهاز (عشان دفعتين بنفس اللحظة ما يكسرون السلسلة)، ترسل الفاتورة مع "pdf": true، وتحفظ device_token الجديد. أي رد غير 200 يرجّع الـ transaction والمفتاح القديم يظل صالح.
// 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
}
٣. للإنتاج
- سجّل جهازك مرة (مفتاح الجهاز أو لينك التفعيل) وحط
device_tokenفي جدولmatheel_device. - لو المبلغ اللي معك شامل الضريبة، أرسل
"prices_include_vat": true. - احفظ
invoice_xml(القانوني) وpdfمع الطلب، والتطبيق يعرض الـ PDF من سيرفرك.
أسئلة شائعة
أحتاج مكتبة Rust خاصة بزاتكا؟
لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل.
وين أحفظ مفتاح الجهاز؟
صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.
أجرّب قبل الاشتراك؟
إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.