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