matheel-zatca
Official Python client for Matheel, the ZATCA (Fatoora) Phase 2 e-invoicing API for Saudi Arabia. One call signs the invoice, files it with ZATCA (reporting or clearance) and returns ZATCA's answer, the legal XML, the QR and a bilingual PDF. Python 3.9+, standard library only.
pip install matheel-zatca
import base64, os
from matheel_zatca import Matheel
matheel = Matheel(os.environ.get("MATHEEL_KEY")) # no key needed on the sandbox
# Try it now: the keyless sandbox files as Matheel's shared test taxpayer.
res = matheel.file_invoice(
{"type": "simplified", "line_items": [{"name": "Iqama renewal service", "quantity": 1, "price": "100.00"}]},
environment="sandbox",
pdf=True,
)
res["status"] # "reported"
base64.b64decode(res["pdf"]) # the PDF/A-3 invoice
After a payment: file_with_store
Register the device once (onboard, or an activation_link for a merchant), keep its device_token in one database
row, and file every paid order through file_with_store. The token carries the invoice chain (counter and hash), so
invoices of one device must be filed one after another: read and write the token under a row lock.
# psycopg; CREATE TABLE matheel_device (id INT PRIMARY KEY, token TEXT NOT NULL);
class DeviceRow:
def __init__(self, cur):
self.cur = cur
def read(self):
self.cur.execute("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE")
return self.cur.fetchone()[0]
def write(self, token):
self.cur.execute("UPDATE matheel_device SET token = %s WHERE id = 1", (token,))
# order.invoice_uuid: str(uuid.uuid4()), made once when the order is created and stored with it.
def invoice_order(conn, order, items):
with conn, conn.cursor() as cur: # commits on success, rolls back on any exception
invoice = {"type": "simplified", "line_items": items}
return matheel.file_with_store(DeviceRow(cur), invoice, pdf=True, uuid=order.invoice_uuid)
What file_with_store does with each answer (up to retries resends, default 3):
- 200: writes the next
device_tokenand returns.replayed: Truemeans this document was already accepted and its stored answer came back: it was not filed twice. - 409
device_token_reused: another invoice moved the chain on. It writeserror.latest_device_tokenand sends this invoice again with it. - 409
filing_in_progress: waitsRetry-After(at most 10 s) and sends the same request again. - Anything else: leaves the token alone and raises
MatheelError(status,body,code,retry_after).
Pass a stable uuid. Make one UUID v4 per business document, store it with the order, and send it on every
attempt (uuid= or invoice["uuid"]). The library never invents one: a resend after a timeout is only safe when it
carries the same uuid, which is how Matheel knows not to file it twice.
What to do with an error: MatheelError.retryable
try:
invoice_order(conn, order, items)
except MatheelError as e:
if e.retryable == "retry":
queue_retry(order) # same request later: same token, same uuid
elif e.retryable == "permanent":
mark_invalid(order, e.body) # fix the document (ZATCA rejection, bad fields)
else: # "attention"
alert_ops(e) # key, plan, certificate, or resend e.body["error"]["uuid"] first
retryable |
Codes |
|---|---|
"retry" |
network_error (status 0: timeout, DNS, reset, TLS), invalid_response (a 200 that is not the API's JSON), filing_outcome_unknown (504), zatca_unavailable (503), filing_failed, 429, any 5xx |
"permanent" |
zatca_rejected, invalid, missing_fields, invalid_amount, validation_failed (422) |
"attention" |
invalid_api_key, invalid_csid (401), production_plan_required (402), previous_filing_unknown (409: resend the document error.uuid first), anything unknown |
API
Matheel(key=None, base_url="https://matheel.app", timeout=60) |
The client. |
file_invoice(invoice, device_token=None, pdf=None, **fields) |
POST /api/v1/invoices. Extra fields (environment, seller, csid, mode) pass through. |
file_with_store(store, invoice, pdf=None, retries=3, uuid=None) |
The safe chain helper above. store has read() and write(token). |
MatheelError.retryable |
"retry", "permanent" or "attention", per the API contract. |
onboard(environment, seller, device=None, otp=None) |
POST /api/v1/onboarding, returns device_token. |
activation_link(environment, reference, callback_url=None, expires_in_days=None, max_devices=None) |
POST /api/v1/onboarding/links. |
decode_qr(qr) |
QrData(seller_name, vat_number, timestamp, total, vat_amount, invoice_hash, signature, public_key, certificate_signature) (tags 8 and 9 as base64). |
verify_activation_callback(raw_body, request.headers["x-matheel-signature"], callback_secret) |
Checks an activation callback (HMAC-SHA256, constant time). Pass the raw body bytes. |
verify_telr(post_fields, telr_secret) |
Checks Telr's tran_check on a transaction advice. |
Every non-200 answer raises MatheelError; code is the API's error code (device_token_reused,
sandbox_rate_limited, invalid_device_token, …) or zatca_rejected when ZATCA's errors are in the body. A network
failure (URLError, timeout, reset, TLS) raises MatheelError with status 0 and code network_error.
Keep the key and the device token on your server, never in an app.
Docs: https://matheel.app/en/docs · Python guide: https://matheel.app/en/zatca-integration/python · API reference for agents: https://matheel.app/llms.txt
عربي
مكتبة ماثل الرسمية لبايثون: أرسل فاتورة زاتكا (المرحلة الثانية) بطلب واحد، ويرجع لك رد الهيئة والـ XML والـ QR والـ PDF.
بعد الدفع استخدم file_with_store مع قفل صف الجهاز في قاعدة بياناتك (SELECT … FOR UPDATE)، وهي تحفظ device_token
الجديد بعد كل فاتورة مقبولة. بيئة التجربة ما تحتاج مفتاح. الدليل: matheel.app/rabt
Metadata
Release files for matheel-zatca 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| matheel_zatca-0.2.0.tar.gz | 12.7 kB | Without provenance | Details for matheel_zatca-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| matheel_zatca-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for matheel_zatca-0.2.0-py3-none-any.whl |
Total release size: 23.2 kB
Release files / matheel_zatca-0.2.0.tar.gz
| Download URL | matheel_zatca-0.2.0.tar.gz |
|---|---|
| Size | 12.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ef7225aec14b2ac782a56437881bb04ee920fdeba1b92908032481855bba118
|
|
BLAKE2b-256 checksum How to use checksums |
0fe2f5a1fbed7fcc975fd5b290a764e25b8e5bb5748d7f6d648dac1e1d4e6a78
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / matheel_zatca-0.2.0-py3-none-any.whl
| Download URL | matheel_zatca-0.2.0-py3-none-any.whl |
|---|---|
| Size | 10.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
73823badd8e0c5b8a5d96e73d40ede750cce6912a535b187e1eeae3394dd02cd
|
|
BLAKE2b-256 checksum How to use checksums |
64edbf629c0d40268c8de53e8981edd94f9e5ffedc7a7d75168b9ecad9ce77e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Security for matheel-zatca 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.