ربط زاتكا بـ Python

من فريق ماثل · آخر تحديث

طلب HTTP واحد من Python (requests + psycopg): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ XML القانوني والـ PDF مع رمز QR.

١. جرّبه الحين (بدون مفتاح)

# pip install matheel-zatca
import os
from matheel_zatca import Matheel

matheel = Matheel(os.environ.get("MATHEEL_KEY"))  # the sandbox needs no key
res = matheel.file_invoice(
    {"type": "simplified", "line_items": [{"name": "قهوة", "quantity": 2, "price": "50.00"}]},
    environment="sandbox", pdf=True)
print(res["status"])  # reported, plus res["qr"], res["pdf"], res["invoice_xml"]
# After a payment: matheel.file_with_store(store, invoice) keeps the device chain for you

٢. الدالة الجاهزة بعد الدفع

تقفل صف الجهاز (عشان دفعتين بنفس اللحظة ما يكسرون السلسلة)، ترسل الفاتورة مع "pdf": true، وتحفظ device_token الجديد. أي رد غير 200 يرجّع الـ transaction والمفتاح القديم يظل صالح.

# psycopg + requests. `with conn:` commits on success and rolls back on any exception.
import os, requests

def matheel_invoice(conn, items):
    with conn, conn.cursor() as cur:
        cur.execute("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE")
        token = cur.fetchone()[0]
        r = requests.post("https://matheel.app/api/v1/invoices", timeout=60,
            headers={"Authorization": f"Bearer {os.environ['MATHEEL_KEY']}"},
            json={"device_token": token, "pdf": True, "invoice": {"type": "simplified", "line_items": items}})
        res = r.json()
        if r.status_code != 200:
            raise RuntimeError(res)
        cur.execute("UPDATE matheel_device SET token = %s WHERE id = 1", (res["device_token"],))
        return res  # base64.b64decode(res["pdf"]) is the PDF

أو بمكتبة ماثل الرسمية: pip install matheel-zatca، وfile_with_store تسوي نفس الشي: تقرأ المفتاح وتحفظه في متجرك، وتعيد المحاولة لحالها لو رجع 409.

٣. للإنتاج

أسئلة شائعة

أحتاج مكتبة Python خاصة بزاتكا؟

لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل. وفيه مكتبة رسمية لو تبيها: pip install matheel-zatca

وين أحفظ مفتاح الجهاز؟

صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.

أجرّب قبل الاشتراك؟

إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.

جرّبه الحين على بيئة المطورين

بدون مفتاح ولا تسجيل: الرد رد الهيئة الحقيقي، ومعه الفاتورة PDF عربي وإنجليزي ورمز QR.

ابدأ الأسعار