API-Referenz

Backend contract for the invoicing application. This service owns business logic, validation, totals/VAT calculation, persistence, and schema. Money and quantity values are transmitted as DECIMAL STRINGS (e.g. "9542.50", "86.75") to preserve exact precision. Totals are ALWAYS computed server-side; any totals supplied in a request body are ignored. The model is aligned with EN 16931 / ZUGFeRD concepts so a compliant export can be added later. v1 exposes only a subset.

What this base URL accepts

The published base URL authenticates programmatic API keys (Authorization: Bearer sk_live_… / sk_test_…). Present a key on every request; an access token issued to a signed-in person is not accepted here and is refused before the request reaches the application. That is why a large part of this reference is marked as requiring a signed-in session rather than a key: account and administration work — team and membership changes, company master data, key and webhook management, billing and the archive — is performed in the web dashboard, and those operations are documented here so the behaviour they implement is inspectable, not because they are callable from this base URL. If an operation is documented as requiring a signed-in session, reach for the dashboard rather than a key. Issuing, sending and retrieving documents — the surface an integration actually automates — is fully available with a key.

Rate limiting

A refused request returns 429 with the rate_limited error code, a Retry-After header and the X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset trio. Honour Retry-After, and treat the headers as the authoritative budget for the current window. Any request budget we state is a FLOOR — the number we guarantee to accept — and never a ceiling. Observing more being accepted than the stated figure is not a promise that it will continue, so do not calibrate a client against what it happens to get away with. No figure is published yet; it will be stated only once it has been measured against real traffic. Each API key has its own request budget: traffic on one key never uses up another key's budget, even when both come from the same address.

Request size

A JSON request body may be at most 1 MiB, and any other body (for example the XML document sent to POST /validate) at most 10 MiB. A larger body is refused with 413 and the payload_too_large error code. An invoice, offer or subscription carries at most 1000 line items; more is a 400 validation_error naming lineItems.

Idempotency

An Idempotency-Key is scoped to the mode of the request (test or live) and to the company it acts for. Reusing one value — say, your order id — first with a test key and then with a live key runs two separate requests; it never replays the test result as the live one.