Metadata-Version: 2.4
Name: timbro-invoices
Version: 0.1.0a2
Summary: Python client for Timbro's canonical Invoice API
Author: Timbro contributors
Project-URL: Homepage, https://timbro.do
Project-URL: Source, https://github.com/indexa-labs/Timbro
Project-URL: Issues, https://github.com/indexa-labs/Timbro/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jsonschema[format]<5,>=4.22
Requires-Dist: regex>=2024.11.6

# 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:

```sh
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.

```python
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`.
