API reference

https://invoiceapi.io/v1OpenAPI 3.1 JSONBack to start

Endpoints

POST

/templates/{id}/invoices

Generate an invoice from a template

Generates a ZUGFeRD PDF/A-3 and/or an XRechnung XML from the template and payload. Idempotent per Idempotency-Key: a repeat with the same key and an identical body replays the original invoice with a 200 instead of creating a new one. Supply the optional `deliverEmail` block to also email the finished invoice: delivery is attempted synchronously and its outcome is reported on the 201, but a delivery failure NEVER fails the request — the invoice is archived either way.

Parameters

Field	In	Required	Description
id	path	Required	Resource id.
output	query	—	Repeatable. Which artifact kind(s) to produce. Defaults to zugferd_pdf when omitted.
Idempotency-Key	header	—	Client-supplied key. A repeat with the same key and body returns the original invoice (200); the same key with a different body returns 409.

Response

200: Idempotency-Key replay: the invoice already generated for this key and body. A replay NEVER sends email and never reports delivery — the `deliverEmail` field is absent, even if the replayed request carried a `deliverEmail` block. The original request owns the delivery; consult the invoice to see its state.
application/json
Field Type Required Description
id string
Required
Invoice id.
number string
Required
Invoice number (BT-1).
mode "live" | "test"
Required
—
status "generated" | "delivered" | "delivery_failed"
Required
—
templateVersion integer
Required
—
createdAt string
Required
—
validation object
Required
—
validation.summary string
Required
—
outputs object[]
Required
—
outputs[].kind "zugferd_pdf" | "xrechnung_xml" | "pdf"
Required
—
outputs[].sha256 string
Required
—
outputs[].bytes integer
Required
—
outputs[].url string
Required
Signed GET URL (expires in <= 15 minutes).
201: Invoice generated. `deliverEmail` reports the delivery outcome, or is null.
application/json
400: Malformed payload or deliverEmail block (schema validation failed).
application/problem+json
401: Missing or invalid API key (Authorization: Bearer <key>).
application/problem+json
402: Monthly quota exceeded (only enforced when billing is enabled).
application/problem+json
404: Template, template version, or profile not found.
application/problem+json
409: Idempotency-Key reused with a different request body.
application/problem+json
422: Compliance validation failed (KoSIT / veraPDF findings).
application/problem+json
429: Rate limit exceeded; see the Retry-After header.
application/problem+json

Field	Type	Required	Description
id	string	Required	Invoice id.
number	string	Required	Invoice number (BT-1).
mode	"live" \| "test"	Required	—
status	"generated" \| "delivered" \| "delivery_failed"	Required	—
templateVersion	integer	Required	—
createdAt	string	Required	—
validation	object	Required	—
validation.summary	string	Required	—
outputs	object[]	Required	—
outputs[].kind	"zugferd_pdf" \| "xrechnung_xml" \| "pdf"	Required	—
outputs[].sha256	string	Required	—
outputs[].bytes	integer	Required	—
outputs[].url	string	Required	Signed GET URL (expires in <= 15 minutes).

GET

/invoices

List invoices

Cursor-paginated. Test-mode invoices are excluded unless mode=test.

Parameters

Field	In	Required	Description
profile	query	—	Filter by profile id.
from	query	—	Filter by record creation time (createdAt), lower bound, inclusive (any Date.parse-able value). NOT the invoice issue date (BT-2).
to	query	—	Filter by record creation time (createdAt), upper bound, inclusive (any Date.parse-able value). NOT the invoice issue date (BT-2).
mode	query	—	live (default) or test.
cursor	query	—	Opaque pagination cursor from a previous nextCursor.
limit	query	—	Page size, clamped to [1, 100] (default 25).

Response

200: A page of invoices.
application/json
Field Type Required Description
data PublicInvoice[]
Required
—
data[].id string
Required
Invoice id.
data[].number string
Required
Invoice number (BT-1).
data[].mode "live" | "test"
Required
—
data[].status "generated" | "delivered" | "delivery_failed"
Required
—
data[].templateVersion integer
Required
—
data[].createdAt string
Required
—
data[].validation object
Required
—
data[].validation.summary string
Required
—
data[].outputs object[]
Required
—
data[].outputs[].kind "zugferd_pdf" | "xrechnung_xml" | "pdf"
Required
—
data[].outputs[].sha256 string
Required
—
data[].outputs[].bytes integer
Required
—
data[].outputs[].url string
Required
Signed GET URL (expires in <= 15 minutes).
nextCursor string | null
Required
—
400: Invalid profile/cursor/from/to query parameter.
application/problem+json
401: Missing or invalid API key (Authorization: Bearer <key>).
application/problem+json
429: Rate limit exceeded; see the Retry-After header.
application/problem+json

Field	Type	Required	Description
data	PublicInvoice[]	Required	—
data[].id	string	Required	Invoice id.
data[].number	string	Required	Invoice number (BT-1).
data[].mode	"live" \| "test"	Required	—
data[].status	"generated" \| "delivered" \| "delivery_failed"	Required	—
data[].templateVersion	integer	Required	—
data[].createdAt	string	Required	—
data[].validation	object	Required	—
data[].validation.summary	string	Required	—
data[].outputs	object[]	Required	—
data[].outputs[].kind	"zugferd_pdf" \| "xrechnung_xml" \| "pdf"	Required	—
data[].outputs[].sha256	string	Required	—
data[].outputs[].bytes	integer	Required	—
data[].outputs[].url	string	Required	Signed GET URL (expires in <= 15 minutes).
nextCursor	string \| null	Required	—

GET

/invoices/{id}

Retrieve an invoice

Returns invoice metadata with freshly signed artifact URLs.

Parameters

Field	In	Required	Description
id	path	Required	Resource id.

Response

200: The invoice.
application/json
Field Type Required Description
id string
Required
Invoice id.
number string
Required
Invoice number (BT-1).
mode "live" | "test"
Required
—
status "generated" | "delivered" | "delivery_failed"
Required
—
templateVersion integer
Required
—
createdAt string
Required
—
validation object
Required
—
validation.summary string
Required
—
outputs object[]
Required
—
outputs[].kind "zugferd_pdf" | "xrechnung_xml" | "pdf"
Required
—
outputs[].sha256 string
Required
—
outputs[].bytes integer
Required
—
outputs[].url string
Required
Signed GET URL (expires in <= 15 minutes).
401: Missing or invalid API key (Authorization: Bearer <key>).
application/problem+json
404: No such invoice for this account.
application/problem+json
429: Rate limit exceeded; see the Retry-After header.
application/problem+json

Field	Type	Required	Description
id	string	Required	Invoice id.
number	string	Required	Invoice number (BT-1).
mode	"live" \| "test"	Required	—
status	"generated" \| "delivered" \| "delivery_failed"	Required	—
templateVersion	integer	Required	—
createdAt	string	Required	—
validation	object	Required	—
validation.summary	string	Required	—
outputs	object[]	Required	—
outputs[].kind	"zugferd_pdf" \| "xrechnung_xml" \| "pdf"	Required	—
outputs[].sha256	string	Required	—
outputs[].bytes	integer	Required	—
outputs[].url	string	Required	Signed GET URL (expires in <= 15 minutes).

GET

/templates

List templates

Unpaginated: org template counts are small (plan-limited).

Response

200: The account templates.
application/json
Field Type Required Description
data PublicTemplate[]
Required
—
data[].id string
Required
—
data[].name string
Required
—
data[].layoutId "classic" | "modern" | "compact" | "bold" | "minimal"
Required
—
data[].version integer
Required
—
data[].profileId string — Present only for profile-scoped templates.
data[].createdAt string
Required
—
401: Missing or invalid API key (Authorization: Bearer <key>).
application/problem+json
429: Rate limit exceeded; see the Retry-After header.
application/problem+json

Field	Type	Required	Description
data	PublicTemplate[]	Required	—
data[].id	string	Required	—
data[].name	string	Required	—
data[].layoutId	"classic" \| "modern" \| "compact" \| "bold" \| "minimal"	Required	—
data[].version	integer	Required	—
data[].profileId	string	—	Present only for profile-scoped templates.
data[].createdAt	string	Required	—

GET

/templates/{id}

Retrieve a template

Parameters

Field	In	Required	Description
id	path	Required	Resource id.

Response

200: The template.
application/json
Field Type Required Description
id string
Required
—
name string
Required
—
layoutId "classic" | "modern" | "compact" | "bold" | "minimal"
Required
—
version integer
Required
—
profileId string — Present only for profile-scoped templates.
createdAt string
Required
—
401: Missing or invalid API key (Authorization: Bearer <key>).
application/problem+json
404: No such template for this account.
application/problem+json
429: Rate limit exceeded; see the Retry-After header.
application/problem+json

Field	Type	Required	Description
id	string	Required	—
name	string	Required	—
layoutId	"classic" \| "modern" \| "compact" \| "bold" \| "minimal"	Required	—
version	integer	Required	—
profileId	string	—	Present only for profile-scoped templates.
createdAt	string	Required	—

POST

/validate

Validate an invoice document

Validates an XRechnung/UBL/CII XML or a ZUGFeRD PDF against KoSIT (Schematron) and veraPDF. Quota-exempt. Findings are translated to DE/EN.

Accepted content types

application/xml

application/pdf

multipart/form-data

Field	Type	Required	Description
file	string	Required	The XML or PDF document to validate.

Response

200: The validation report.
application/json
Field Type Required Description
validation object
Required
Raw compliance-engine validation result (engine-specific shape).
versions object — —
findings object[]
Required
—
findings[].path string
Required
—
findings[].bt string — —
findings[].code string — —
findings[].message object
Required
—
findings[].message.de string
Required
—
findings[].message.en string
Required
—
findings[].untranslated boolean — —
400: Empty body, or the compliance engine could not decode it.
application/problem+json
401: Missing or invalid API key (Authorization: Bearer <key>).
application/problem+json
429: Rate limit exceeded; see the Retry-After header.
application/problem+json
502: The compliance engine is unreachable.
application/problem+json

Field	Type	Required	Description
validation	object	Required	Raw compliance-engine validation result (engine-specific shape).
versions	object	—	—
findings	object[]	Required	—
findings[].path	string	Required	—
findings[].bt	string	—	—
findings[].code	string	—	—
findings[].message	object	Required	—
findings[].message.de	string	Required	—
findings[].message.en	string	Required	—
findings[].untranslated	boolean	—	—

GET

/health

Liveness and dependency reachability

Public. Reports compliance-engine reachability and engine versions.

Response

200: Service health.
application/json
Field Type Required Description
status "ok" | "degraded"
Required
—
compliance "ok" | "unreachable"
Required
—
versions object — —

Field	Type	Required	Description
status	"ok" \| "degraded"	Required	—
compliance	"ok" \| "unreachable"	Required	—
versions	object	—	—