Skip to main content

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_token and returns. replayed: True means 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 writes error.latest_device_token and sends this invoice again with it.
  • 409 filing_in_progress: waits Retry-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)

Source distribution for matheel-zatca 0.2.0
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)

Table of built distributions (wheels) for matheel-zatca 0.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page