API-Referenz

https://invoiceapi.io/v1OpenAPI 3.1 JSONZur Startseite

Endpunkte

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.

Parameter

Feld	Ort	Erforderlich	Beschreibung
id	path	Erforderlich	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.

Antwort

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
Feld Typ Erforderlich Beschreibung
id string
Erforderlich
Invoice id.
number string
Erforderlich
Invoice number (BT-1).
mode "live" | "test"
Erforderlich
—
status "generated" | "delivered" | "delivery_failed"
Erforderlich
—
templateVersion integer
Erforderlich
—
createdAt string
Erforderlich
—
validation object
Erforderlich
—
validation.summary string
Erforderlich
—
outputs object[]
Erforderlich
—
outputs[].kind "zugferd_pdf" | "xrechnung_xml" | "pdf"
Erforderlich
—
outputs[].sha256 string
Erforderlich
—
outputs[].bytes integer
Erforderlich
—
outputs[].url string
Erforderlich
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

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

GET

/invoices

List invoices

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

Parameter

Feld	Ort	Erforderlich	Beschreibung
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).

Antwort

200: A page of invoices.
application/json
Feld Typ Erforderlich Beschreibung
data PublicInvoice[]
Erforderlich
—
data[].id string
Erforderlich
Invoice id.
data[].number string
Erforderlich
Invoice number (BT-1).
data[].mode "live" | "test"
Erforderlich
—
data[].status "generated" | "delivered" | "delivery_failed"
Erforderlich
—
data[].templateVersion integer
Erforderlich
—
data[].createdAt string
Erforderlich
—
data[].validation object
Erforderlich
—
data[].validation.summary string
Erforderlich
—
data[].outputs object[]
Erforderlich
—
data[].outputs[].kind "zugferd_pdf" | "xrechnung_xml" | "pdf"
Erforderlich
—
data[].outputs[].sha256 string
Erforderlich
—
data[].outputs[].bytes integer
Erforderlich
—
data[].outputs[].url string
Erforderlich
Signed GET URL (expires in <= 15 minutes).
nextCursor string | null
Erforderlich
—
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

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

GET

/invoices/{id}

Retrieve an invoice

Returns invoice metadata with freshly signed artifact URLs.

Parameter

Feld	Ort	Erforderlich	Beschreibung
id	path	Erforderlich	Resource id.

Antwort

200: The invoice.
application/json
Feld Typ Erforderlich Beschreibung
id string
Erforderlich
Invoice id.
number string
Erforderlich
Invoice number (BT-1).
mode "live" | "test"
Erforderlich
—
status "generated" | "delivered" | "delivery_failed"
Erforderlich
—
templateVersion integer
Erforderlich
—
createdAt string
Erforderlich
—
validation object
Erforderlich
—
validation.summary string
Erforderlich
—
outputs object[]
Erforderlich
—
outputs[].kind "zugferd_pdf" | "xrechnung_xml" | "pdf"
Erforderlich
—
outputs[].sha256 string
Erforderlich
—
outputs[].bytes integer
Erforderlich
—
outputs[].url string
Erforderlich
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

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

GET

/templates

List templates

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

Antwort

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

Feld	Typ	Erforderlich	Beschreibung
data	PublicTemplate[]	Erforderlich	—
data[].id	string	Erforderlich	—
data[].name	string	Erforderlich	—
data[].layoutId	"classic" \| "modern" \| "compact" \| "bold" \| "minimal"	Erforderlich	—
data[].version	integer	Erforderlich	—
data[].profileId	string	—	Present only for profile-scoped templates.
data[].createdAt	string	Erforderlich	—

GET

/templates/{id}

Retrieve a template

Parameter

Feld	Ort	Erforderlich	Beschreibung
id	path	Erforderlich	Resource id.

Antwort

200: The template.
application/json
Feld Typ Erforderlich Beschreibung
id string
Erforderlich
—
name string
Erforderlich
—
layoutId "classic" | "modern" | "compact" | "bold" | "minimal"
Erforderlich
—
version integer
Erforderlich
—
profileId string — Present only for profile-scoped templates.
createdAt string
Erforderlich
—
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

Feld	Typ	Erforderlich	Beschreibung
id	string	Erforderlich	—
name	string	Erforderlich	—
layoutId	"classic" \| "modern" \| "compact" \| "bold" \| "minimal"	Erforderlich	—
version	integer	Erforderlich	—
profileId	string	—	Present only for profile-scoped templates.
createdAt	string	Erforderlich	—

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.

Akzeptierte Content-Types

application/xml

application/pdf

multipart/form-data

Feld	Typ	Erforderlich	Beschreibung
file	string	Erforderlich	The XML or PDF document to validate.

Antwort

200: The validation report.
application/json
Feld Typ Erforderlich Beschreibung
validation object
Erforderlich
Raw compliance-engine validation result (engine-specific shape).
versions object — —
findings object[]
Erforderlich
—
findings[].path string
Erforderlich
—
findings[].bt string — —
findings[].code string — —
findings[].message object
Erforderlich
—
findings[].message.de string
Erforderlich
—
findings[].message.en string
Erforderlich
—
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

Feld	Typ	Erforderlich	Beschreibung
validation	object	Erforderlich	Raw compliance-engine validation result (engine-specific shape).
versions	object	—	—
findings	object[]	Erforderlich	—
findings[].path	string	Erforderlich	—
findings[].bt	string	—	—
findings[].code	string	—	—
findings[].message	object	Erforderlich	—
findings[].message.de	string	Erforderlich	—
findings[].message.en	string	Erforderlich	—
findings[].untranslated	boolean	—	—

GET

/health

Liveness and dependency reachability

Public. Reports compliance-engine reachability and engine versions.

Antwort

200: Service health.
application/json
Feld Typ Erforderlich Beschreibung
status "ok" | "degraded"
Erforderlich
—
compliance "ok" | "unreachable"
Erforderlich
—
versions object — —

Feld	Typ	Erforderlich	Beschreibung
status	"ok" \| "degraded"	Erforderlich	—
compliance	"ok" \| "unreachable"	Erforderlich	—
versions	object	—	—