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,))
def invoice_order(conn, items):
with conn, conn.cursor() as cur: # commits on success, rolls back on any exception
return matheel.file_with_store(DeviceRow(cur), {"type": "simplified", "line_items": items}, pdf=True)
On 200 it writes the new token. On 409 device_token_reused it re-reads the token and retries (3 times). On any other
error it leaves the token alone and raises MatheelError (status, body, code): fix the invoice and resend.
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) |
The safe chain helper above. store has read() and write(token). |
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.
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.1.1
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.1.1.tar.gz | 8.9 kB | Without provenance | Details for matheel_zatca-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| matheel_zatca-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for matheel_zatca-0.1.1-py3-none-any.whl |
Total release size: 17.1 kB
Release files / matheel_zatca-0.1.1.tar.gz
| Download URL | matheel_zatca-0.1.1.tar.gz |
|---|---|
| Size | 8.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ccd8bab0eba4a94faec91fd7f263fa02757314e1efd1f8569a127ad0cda7bdde
|
|
BLAKE2b-256 checksum How to use checksums |
06dfea444abbaa7457af696302dac136c996859652b15ab396a573c34d095c25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / matheel_zatca-0.1.1-py3-none-any.whl
| Download URL | matheel_zatca-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e7b518200156d82ada9e0940b8ad3e2c8668e579265286f6ba2d0f3c68e2336
|
|
BLAKE2b-256 checksum How to use checksums |
236e471c8f52bd4a753c38eda88717a4baec020a51e8e202a6d858ed00d8806d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for matheel-zatca 0.1.1
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.