Timbro Invoices for Python

timbro-invoices is the Python client for the canonical /v1/invoices API. Invoice request and response wire shapes are defined by the Timbro API; the installed package carries a generated projection of that contract.

Requires Python 3.10 or later. Install the current prerelease from PyPI:

python -m pip install "timbro-invoices==0.1.0a2"

This alpha targets the redesigned Invoice API, which is still awaiting coordinated hosted qualification. Its API contract may change before the stable release.

from timbro_invoices import TimbroInvoices

client = TimbroInvoices(api_key="your-invoice-api-key")
preview = client.preview_invoice(invoice_request)
invoice = client.create_invoice(invoice_request)
current = client.retrieve_invoice(invoice["id"])
page = client.list_invoices(invoice_reference="odoo:2026:1042")
xml = client.download_xml(invoice["id"])
pdf = client.download_pdf(invoice["id"])

# Replace a retained, replaceable Invoice with a new canonical request.
replacement = client.replace_invoice(
    rejected_invoice["id"],
    {**invoice_request, "invoiceReference": "odoo:2026:1042-r1"},
)

# Share an accepted receipt with a payment service.
receipt_access = client.share_receipt(invoice["id"])
receipt = client.retrieve_receipt(receipt_access)
receipt_pdf = client.download_receipt_pdf(receipt_access)

Keep the receipt access grant on your server and pass it to the receiving service over an authenticated channel. Restricted reads use its accessToken; the token is never sent in the URL and grants access only to receipt data and its PDF. Receipt PDF downloads verify the Invoice identity, media type, and SHA-256 headers. Other file downloads also verify Timbro's security metadata. HTTP problems preserve Timbro's status and machine-readable code. Webhook helpers verify Standard Webhooks signatures over the original bytes and parse only the canonical Invoice event envelope. The distribution uses jsonschema and regex to validate data against the generated OpenAPI contract.

A 422 admission refusal has no retained Invoice ID. Correct the request and call create_invoice; replace_invoice applies to a retained replaceable Invoice. Authority-rejected numbering gaps still require the existing administrator authorization. A replacement retains the predecessor's Source ID, uses a new Source version and invoiceReference, and exposes its predecessor in replacesInvoiceId.

Regenerate the contract projection with python python-sdk/scripts/generate_contract.py. Run the package tests with python -m unittest discover -s python-sdk/tests.