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,))


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)

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

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

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