API-Dokumentation
EN-16931-konforme E-Rechnungen (XRechnung & ZUGFeRD) erzeugen, validieren, extrahieren und analysieren – über eine einfache REST- + JSON-Schnittstelle. Produktüberblick mit Formaten und Preisen: XRechnung API und ZUGFeRD API.
https://api.rechnungsapi.deOhne Programmierung? Die Ordner-Integration erzeugt ZUGFeRD-Rechnungen aus PDFs und Bildern per Nextcloud oder SFTP.
Authentifizierung
Alle Anfragen werden mit einem Bearer-Token authentifiziert. Senden Sie ihn bei jedem Aufruf im Authorization-Header. Tokens sind kontogebunden – geben Sie sie nicht weiter und committen Sie sie nicht.
Header-Format
Authorization: Bearer <your-token>
- Melden Sie sich im Dashboard an unter rechnungsapi.de.
- Öffnen Sie Ihr Profil und kopieren Sie unten den API-Token.
- Speichern Sie den Token sicher (Env-Variable oder Secret-Manager) und übergeben Sie ihn bei jeder Anfrage.
Schnellstart
Machen Sie Ihren ersten Aufruf in unter einer Minute. Das folgende Beispiel analysiert ein PNG-Rechnungsfoto mit dem V2-Analyzer und liefert strukturiertes JSON sowie einen Konfidenzwert — PDF, PNG, JPEG und TIFF werden alle im selben Feld akzeptiert.
curl -X POST "https://api.v2.rechnungsapi.de/createJSONFromAnalysedPdf" \
-H "Authorization: Bearer $RECHNUNGSAPI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"pdfInvoiceBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
"withLineItems": true
}'
# PDF, PNG, JPEG, and TIFF are all accepted in this same field — the type is
# detected from the base64 content, not from a filename or MIME type.Setzen Sie die Umgebungsvariable RECHNUNGSAPI_TOKEN auf Ihren API-Token, bevor Sie das Snippet ausführen.
Endpunkte
Die meisten Endpunkte sind POST und akzeptieren application/json; der Status-Endpunkt der asynchronen Analyse ist ein GET mit Query-Parameter. Wählen Sie den Workflow passend zu Ihrem Anwendungsfall – Erzeugung, Analyse, Extraktion oder Validierung.
PDF Analyse
https://api.v2.rechnungsapi.de/createJSONFromAnalysedPdfRechnungs-PDF analysieren (V2 — empfohlen)
Analyzer der nächsten Generation mit höherer Genauigkeit und Unterstützung für große, mehrseitige Rechnungen. Akzeptiert PDF, PNG, JPEG oder TIFF im selben Feld pdfInvoiceBase64 — der Typ wird anhand des Base64-Inhalts selbst erkannt (Dateiname/MIME-Type sind irrelevant), der Feldname bleibt aus Gründen der Abwärtskompatibilität unverändert. Akzeptiert ein optionales withLineItems-Flag, um die Positions-Extraktion für eine schnellere reine Kopfdaten-Analyse zu überspringen. Hinweis: V2 läuft auf einem separaten Host (api.v2.rechnungsapi.de) — bitte die oben angezeigte vollständige URL verwenden. Derselbe Bearer-Token authentifiziert V1 und V2. Ablehnungen (fehlerhafte Eingabe, Auth, zu große Datei) antworten in deutlich unter einer Sekunde; eine erfolgreiche Extraktion dauert je nach OCR-/Modellzeit etwa 7–25 Sekunden, unabhängig von der Dateigröße — Client-Timeouts auf mindestens 60s setzen, oder für große bzw. mehrseitige Dokumente den Async-Endpunkt unten verwenden.
| Field | Type | Required | Description |
|---|---|---|---|
pdfInvoiceBase64 | string | required | Base64-kodierter Inhalt der Rechnungsdatei — PDF, PNG, JPEG oder TIFF. Wird anhand des Inhalts erkannt, nicht anhand von Feldname oder Dateiendung. Wird auch unter den Feldnamen invoiceBase64 und fileBase64 akzeptiert. Ein data:*;base64,-Präfix wird toleriert und serverseitig entfernt; Zeilenumbrüche im Base64 werden ebenfalls toleriert. Größenlimit: 11 MB roh (≈14,7 MB base64) — Bodies über ~12 MB werden bereits von der Plattform abgelehnt, bevor dieser Endpunkt überhaupt läuft (siehe FILE_TOO_LARGE unten). |
withLineItems | boolean | optional | Bei true werden zusätzlich zu den Kopfdaten auch einzelne Rechnungspositionen extrahiert. Bei false werden nur die Kopfdaten zurückgegeben — etwa 2× schneller. Im Playground standardmäßig true. |
Beispiel
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf...",
"withLineItems": true
}Beispielantwort
{
"extractionConfidence": 100,
"invoice": {
"invoiceNumber": "RE-2026-08-0815",
"invoiceIssueDate": "24.08.2026",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"paymentDueDate": "23.09.2026",
"buyerReference": "04011000-12345-67",
"purchaseOrderReference": "BST-2026-4471",
"paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …",
"seller": {
"sellerName": "Müller & Söhne Großhandel GmbH",
"sellerVatIdentifier": "DE812345678"
},
"buyer": {
"buyerName": "Bäckerei Schröder KG"
},
"deliveryInformation": {
"actualDeliveryDate": "31.07.2026"
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78",
"paymentAccountName": "Müller & Söhne Großhandel GmbH",
"paymentServiceProviderIdentifier": "DUSSDEDDXXX"
}
]
},
"documentTotals": {
"sumOfInvoiceLineNetAmount": 6519.7,
"invoiceTotalAmountWithoutVat": 6519.7,
"invoiceTotalVatAmount": 1234.1,
"invoiceTotalAmountWithVat": 7753.8,
"amountDueForPayment": 7753.8
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 6481,
"vatCategoryTaxAmount": 1231.39,
"vatCategoryCode": "S",
"vatCategoryRate": 19
},
{
"vatCategoryTaxableAmount": 38.7,
"vatCategoryTaxAmount": 2.71,
"vatCategoryCode": "S",
"vatCategoryRate": 7
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoicedQuantity": 12,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1740,
"priceDetails": {
"itemNetPrice": 145
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratungsleistung Softwarearchitektur"
}
}
]
},
"zugferdReady": true,
"lineItemCheck": {
"status": "ok",
"verified": true,
"lines": 5,
"linesRecomputed": 5,
"linesInconsistent": 0,
"lineSum": 6519.7,
"sumCheck": "ok",
"confirmedBy": "printed BT-106",
"vatCheck": "ok"
},
"confidenceBasis": {
"requirementsChecked": 43,
"requirementsMet": 43
},
"warnings": []
}Antwortfelder
| Field | Type | Description |
|---|---|---|
extractionConfidence | integer (0–100) | Wie vollständig die Extraktion ist: der Anteil der geprüften Anforderungen, die sie erfüllt (`confidenceBasis.requirementsMet` von `requirementsChecked`, z. B. 41 von 43 → 95). 100 = vollständig. Alles darunter bedeutet, dass Pflichtangaben fehlen (siehe `mandatoryFieldReport`) und sich die Rechnung so nicht in eine ZUGFeRD-Rechnung umwandeln lässt. |
invoice | object | Die extrahierte Rechnung (siehe Rechnungsobjekt-Referenz). Felder ohne Wert im Quelldokument werden weggelassen. |
zugferdReady | boolean | Bereitschafts-Flag für die ZUGFeRD-Erzeugung: `true`, wenn die Extraktion alle geprüften Anforderungen erfüllt hat (siehe `confidenceBasis`), also `extractionConfidence` 100 ist. Sonst `false` — `mandatoryFieldReport` listet dann, was fehlt. |
mandatoryFieldReport | array (only below 100) | Die im Dokument fehlenden Pflichtangaben, ein Eintrag je Lücke. Nur vorhanden, wenn `extractionConfidence` unter 100 liegt; bei 100 fehlt die Eigenschaft vollständig — prüfen Sie auf ihr Vorhandensein, gehen Sie nicht von einem leeren Array aus. Diese Lücken senken die Konfidenz und verhindern die ZUGFeRD-Erzeugung: Ergänzen Sie die Angaben im Quelldokument und analysieren Sie es erneut, oder ergänzen Sie sie im extrahierten `invoice`, bevor Sie die ZUGFeRD-Datei erzeugen. |
mandatoryFieldReport[].rule | string | Die Regel, die die Angabe verpflichtend macht: eine EN-16931-Geschäftsregel (`BR-09`, `BR-CO-26`) oder eine deutsche XRechnung-Regel (`BR-DE-1`, `BR-DE-16`). |
mandatoryFieldReport[].bt | string | Der betroffene EN-16931-Business-Term (`BT-40`) bzw. die Business-Gruppe (`BG-16`). Genügen mehrere Terme alternativ der Regel, werden sie mit `/` verbunden, z. B. `BT-29/BT-30/BT-31`. |
mandatoryFieldReport[].field | string | Punktpfad in `invoice`, an den der fehlende Wert gehört, z. B. `seller.sellerContact.sellerContactTelephoneNumber`. Eine ganze Gruppe wird über ihren Objektnamen angesprochen, z. B. `paymentInstructions`. |
mandatoryFieldReport[].label | string | Kurzer deutscher Name der fehlenden Angabe, zur Anzeige. Mit ae/oe/ue statt ä/ö/ü geschrieben (z. B. `Land des Verkaeufers`): zeigen Sie ihn Nutzern an, verwenden Sie im Code aber `field`, `bt` oder `rule`. |
lineItemCheck | object | Plausibilitätsprüfung der extrahierten Positionen gegen die Summen. Eigenschaften unten. |
lineItemCheck.status | string | Gesamtergebnis der Positionsprüfung, z. B. `ok`. |
lineItemCheck.verified | boolean | `true`, wenn die Positionen gegen eine aufgedruckte Summe bestätigt werden konnten. |
lineItemCheck.lines | integer | Anzahl der gefundenen Positionen. |
lineItemCheck.linesRecomputed | integer | Anzahl der Positionen, deren Betrag für die Prüfung nachgerechnet wurde. |
lineItemCheck.linesInconsistent | integer | Anzahl der Positionen, deren nachgerechneter Betrag nicht zum extrahierten passte. `0` ist der Idealfall. |
lineItemCheck.lineSum | number | Summe der Positions-Nettobeträge. |
lineItemCheck.sumCheck | string | Ob `lineSum` mit der Dokumentsumme übereinstimmt, z. B. `ok`. |
lineItemCheck.confirmedBy | string | Welcher Wert im Dokument die Summe bestätigt hat, z. B. `printed BT-106` (die aufgedruckte Summe der Positions-Nettobeträge). |
lineItemCheck.vatCheck | string | Ob die Umsatzsteuer-Angaben konsistent sind, z. B. `ok`. |
confidenceBasis | object | Worauf `extractionConfidence` beruht: `requirementsChecked` ist die Zahl der Anforderungen, gegen die die Extraktion geprüft wurde, `requirementsMet` wie viele davon erfüllt sind. |
warnings | array of objects | Hinweise auf Werte, die der Analyzer ersetzen oder ableiten musste, damit die Rechnung verarbeitbar bleibt (siehe `code`); leer, wenn es keine gibt. Ein Platzhalter sind keine echten Daten: bitte prüfen. |
warnings[].code | string | Art der Warnung. Beobachtet: `PLACEHOLDER_INSERTED` (ein erforderlicher Wert stand nicht im Dokument, es wurde ein Platzhalter eingefügt) und `VALUE_DERIVED` (ein Wert wurde abgeleitet statt gelesen, z. B. Land `DE` für eine inländische Adresse angenommen). |
warnings[].field | string | Der betroffene Business-Term, z. B. `BT-10`. |
warnings[].message | string | Erklärung in Klartext, auf Deutsch. |
Beispielantwort
{
"extractionConfidence": 95,
"invoice": {
"invoiceNumber": "RE-2026-08-0815",
"invoiceIssueDate": "24.08.2026",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"paymentDueDate": "23.09.2026",
"buyerReference": "04011000-12345-67",
"purchaseOrderReference": "BST-2026-4471",
"paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …",
"seller": {
"sellerName": "Müller & Söhne Großhandel GmbH",
"sellerVatIdentifier": "DE812345678"
},
"buyer": {
"buyerName": "Bäckerei Schröder KG"
},
"deliveryInformation": {
"actualDeliveryDate": "31.07.2026"
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78",
"paymentAccountName": "Müller & Söhne Großhandel GmbH",
"paymentServiceProviderIdentifier": "DUSSDEDDXXX"
}
]
},
"documentTotals": {
"sumOfInvoiceLineNetAmount": 6519.7,
"invoiceTotalAmountWithoutVat": 6519.7,
"invoiceTotalVatAmount": 1234.1,
"invoiceTotalAmountWithVat": 7753.8,
"amountDueForPayment": 7753.8
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 6481,
"vatCategoryTaxAmount": 1231.39,
"vatCategoryCode": "S",
"vatCategoryRate": 19
},
{
"vatCategoryTaxableAmount": 38.7,
"vatCategoryTaxAmount": 2.71,
"vatCategoryCode": "S",
"vatCategoryRate": 7
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoicedQuantity": 12,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1740,
"priceDetails": {
"itemNetPrice": 145
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratungsleistung Softwarearchitektur"
}
}
]
},
"zugferdReady": false,
"mandatoryFieldReport": [
{
"rule": "BR-DE-6",
"bt": "BT-42",
"field": "seller.sellerContact.sellerContactTelephoneNumber",
"label": "Telefon des Verkaeufers"
},
{
"rule": "BR-DE-7",
"bt": "BT-43",
"field": "seller.sellerContact.sellerContactEmailAddress",
"label": "E-Mail des Verkaeufers"
}
],
"lineItemCheck": {
"status": "ok",
"verified": true,
"lines": 5,
"linesRecomputed": 5,
"linesInconsistent": 0,
"lineSum": 6519.7,
"sumCheck": "ok",
"confirmedBy": "printed BT-106",
"vatCheck": "ok"
},
"confidenceBasis": {
"requirementsChecked": 43,
"requirementsMet": 41
},
"warnings": [
{
"code": "VALUE_DERIVED",
"field": "BT-40/BT-55",
"message": "Land DE angenommen (inländische Adresse, kein Land gedruckt)"
},
{
"code": "PLACEHOLDER_INSERTED",
"field": "BT-10",
"message": "Keine Käuferreferenz / Leitweg-ID gedruckt: Platzhalter \"No BuyerReference provided\" (XRechnung verlangt BT-10)"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
https://api.v2.rechnungsapi.de/createJSONFromAnalysedPdfAsyncRechnungs-PDF analysieren (Asynchron — Einreichen)
Reicht ein PDF oder TIFF zur Hintergrundanalyse ein, statt auf die Antwort inline zu warten — für große oder mehrseitige Rechnungen, die das 60-Sekunden-Timeout des synchronen Endpunkts überschreiten würden. Antwortet sofort mit einer job_id (HTTP 200, nicht 202); den Status-Endpunkt unten alle ~3s abfragen, bis "done" oder "failed" gemeldet wird — Jobs und deren Ergebnisse werden 24 Stunden aufbewahrt. Für kleine, einseitige Rechnungen den synchronen V2-Endpunkt oben bevorzugen — einfacher und liefert das Ergebnis direkt. Gleiche Authentifizierung wie V2: ein roher Token (ohne "Bearer "-Präfix) oder ein authtoken-Header liefern beide 403 — nur Authorization: Bearer <token> wird akzeptiert.
| Field | Type | Required | Description |
|---|---|---|---|
pdfInvoiceBase64 | string | required | Base64-kodierter Inhalt der Rechnungsdatei — PDF oder TIFF (gleiche Varianten und Erkennung wie beim V2-Endpunkt oben; aktuell kein PNG/JPEG bei Async). Wird auch unter den Feldnamen invoiceBase64 und fileBase64 akzeptiert. Ein data:*;base64,-Präfix wird toleriert und serverseitig entfernt; Zeilenumbrüche im Base64 werden ebenfalls toleriert. Gleiches 11-MB-Limit wie bei V2 — siehe FILE_TOO_LARGE unten. |
withLineItems | boolean | optional | Bei true (Standard) werden zusätzlich zu den Kopfdaten auch einzelne Rechnungspositionen extrahiert. Bei false wird invoice.invoiceLine[] im Ergebnis weggelassen. |
Beispiel
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf...",
"withLineItems": true
}Beispielantwort
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "processing"
}Playground
Diesen Endpunkt live im Browser testen.
https://api.v2.rechnungsapi.de/rechnungsapi-invoice-async-statusStatus der asynchronen Analyse abfragen
Fragt das Ergebnis eines Jobs ab, der über den obigen asynchronen Submit-Endpunkt erstellt wurde. ⚠️ Dieser Pfad wird nicht aus dem Submit-Pfad abgeleitet — er ist ein fester, unabhängiger Routenname (rechnungsapi-invoice-async-status), identisch auf jedem Host; nicht durch Anhängen von "Status" an den Submit-Endpunkt konstruieren. Ergebnisse werden 24 Stunden nach Abschluss aufbewahrt und danach gelöscht.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid, query param) | required | Die vom Submit-Aufruf zurückgegebene job_id. Muss eine UUID sein — jeder andere Wert wird als nicht gefunden behandelt. |
Beispiel
https://api.v2.rechnungsapi.de/rechnungsapi-invoice-async-status?id=1b2c3d4e-5f6a-7890-abcd-ef1234567890
Beispielantwort
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "processing"
}Beispielantwort
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "done",
"result": {
"extractionConfidence": 100,
"invoice": {
"invoiceNumber": "RE-2026-08-0815",
"invoiceIssueDate": "24.08.2026",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"paymentDueDate": "23.09.2026",
"buyerReference": "04011000-12345-67",
"purchaseOrderReference": "BST-2026-4471",
"paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …",
"seller": {
"sellerName": "Müller & Söhne Großhandel GmbH",
"sellerVatIdentifier": "DE812345678"
},
"buyer": {
"buyerName": "Bäckerei Schröder KG"
},
"deliveryInformation": {
"actualDeliveryDate": "31.07.2026"
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78",
"paymentAccountName": "Müller & Söhne Großhandel GmbH",
"paymentServiceProviderIdentifier": "DUSSDEDDXXX"
}
]
},
"documentTotals": {
"sumOfInvoiceLineNetAmount": 6519.7,
"invoiceTotalAmountWithoutVat": 6519.7,
"invoiceTotalVatAmount": 1234.1,
"invoiceTotalAmountWithVat": 7753.8,
"amountDueForPayment": 7753.8
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 6481,
"vatCategoryTaxAmount": 1231.39,
"vatCategoryCode": "S",
"vatCategoryRate": 19
},
{
"vatCategoryTaxableAmount": 38.7,
"vatCategoryTaxAmount": 2.71,
"vatCategoryCode": "S",
"vatCategoryRate": 7
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoicedQuantity": 12,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1740,
"priceDetails": {
"itemNetPrice": 145
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratungsleistung Softwarearchitektur"
}
}
]
},
"zugferdReady": true,
"lineItemCheck": {
"status": "ok",
"verified": true,
"lines": 5,
"linesRecomputed": 5,
"linesInconsistent": 0,
"lineSum": 6519.7,
"sumCheck": "ok",
"confirmedBy": "printed BT-106",
"vatCheck": "ok"
},
"confidenceBasis": {
"requirementsChecked": 43,
"requirementsMet": 43
},
"warnings": []
}
}Beispielantwort
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "failed",
"error": {
"code": "PDF_NO_TEXT",
"userMessage": "Diese Datei enthält keinen auslesbaren Text (vermutlich ein reines Scan- oder Bilddokument). Bitte laden Sie eine Version mit Textebene hoch oder wenden Sie sich an den Support.",
"reference": "REA-144853"
}
}Playground
Diesen Endpunkt live im Browser testen.
/api/v1/zugferd/createJSONFromAnalysedPdfRechnungs-PDF analysieren (V1 — legacy)
Analysiert das übergebene Rechnungs-PDF und extrahiert strukturierte Daten: Käufer, Verkäufer, Positionen, MwSt. und Gesamtbeträge. Bestehende Integrationen funktionieren weiterhin; neue Integrationen sollten den V2-Endpunkt oben für höhere Genauigkeit und Unterstützung großer Rechnungen bevorzugen.
| Field | Type | Required | Description |
|---|---|---|---|
pdfInvoiceBase64 | string | required | Base64-kodierter Inhalt der PDF-Rechnung. |
Beispiel
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf..."
}Beispielantwort
{
"apiStatus": 200,
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125",
"supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
"attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
}
}Playground
Diesen Endpunkt live im Browser testen.
Rechnungserzeugung
https://api.v2.rechnungsapi.de/createZugferdFromPdfPDF zu ZUGFeRD konvertieren (ein Aufruf)
Sendet ein PDF oder ein gescanntes Rechnungsbild und liefert entweder ein validiertes ZUGFeRD-PDF/A-3 (eingebettetes EN-16931-XML, bereits ZUGFeRD- und XRechnung-validiert) oder eine detaillierte JSON-Begründung, warum keines erzeugt werden konnte — nie beides. Anders als der zweistufige Ablauf createJSONFromAnalysedPdf → createZugferdFromJson unten analysiert, prüft und baut dieser Endpunkt das ZUGFeRD-Dokument in einer einzigen synchronen Anfrage: aus den extrahierten Positionen berechnete Summen werden gegen die auf der Seite gedruckten Summen geprüft, und die Konvertierung wird abgelehnt, statt ein Dokument mit nicht belegten Beträgen auszuliefern. Hinweis: Wie der V2-Analyzer oben läuft dieser Endpunkt auf einem separaten Host (api.v2.rechnungsapi.de) — bitte die oben angezeigte vollständige URL verwenden, nicht die an anderer Stelle auf dieser Seite genutzte Basis api.rechnungsapi.de. Derselbe Bearer-Token authentifiziert beide Hosts. Der Aufruf ist synchron, ohne Polling — Analyse und Build zusammen können je nach Seitenzahl und OCR-Aufwand wenige Sekunden bis mehrere Minuten dauern; Client- (und vorgelagerte Proxy-)Timeouts daher auf mindestens 600s setzen. Abrechnung: Eine erfolgreiche Konvertierung erfasst je eine Nutzung pro Seite sowohl für den Analyse- als auch den Build-Schritt; es gibt keinen Idempotency-Key, identische Anfragen konvertieren und berechnen also erneut — Mehrfach-Übermittlungen clientseitig deduplizieren. Jede Fehlerantwort enthält zudem ein versandfertiges email-Objekt ({subject, text, html}) zur Benachrichtigung des Rechnungseigentümers — im ersten Fehlerbeispiel unten einmalig gezeigt.
| Field | Type | Required | Description |
|---|---|---|---|
pdfInvoiceBase64 | string (base64) | required | Base64 des Rechnungsdokuments — PDF, PNG, JPEG oder TIFF, erkannt anhand des Inhalts (Magic Bytes), nicht anhand von Dateiname oder Content-Type. Ein data:…;base64,-Präfix sowie Leerzeichen werden automatisch entfernt. Wird auch unter invoiceBase64 und fileBase64 akzeptiert (in dieser Reihenfolge). Nicht unterstützt: HEIC/HEIF, WEBP, BMP, GIF, SVG, Office-Dateien, ZIP — HEIC clientseitig zuerst in JPEG konvertieren. Größenlimit dekodiert: 11 MiB (≈14,7 MB Base64); der umgebende HTTP-Body ist zusätzlich von der Plattform auf 16 MB begrenzt, darüber erhalten Sie statt des JSON-Envelopes unten einen rohen Fehler — eigene clientseitige Größenprüfung vornehmen. |
fileName | string | optional | Ursprünglicher Dateiname. Bestimmt den Ausgabedateinamen (…-zugferd.pdf) und den Wortlaut der Fehler-E-Mail. Wird serverseitig bereinigt (Steuerzeichen, Anführungszeichen und Backslashes werden zu Leerzeichen; / wird zu _; auf 200 Zeichen gekürzt). Standardwert: invoice.pdf. |
Beispiel
{
"pdfInvoiceBase64": "JVBERi0xLjQKJc...",
"fileName": "Rechnung-2026-0042.pdf"
}Beispielantwort
{
"// body": "raw PDF bytes (Content-Type: application/pdf) — not JSON",
"headers": {
"Content-Type": "application/pdf",
"Content-Disposition": "attachment; filename=\"Rechnung-2026-0042-zugferd.pdf\"",
"X-Zugferd-Status": "success",
"X-Zugferd-Reference": "ZAPI-151430"
}
}Playground
Diesen Endpunkt live im Browser testen.
/api/v1/zugferd/createXinvoiceFromJsonXRechnung-XML aus JSON erzeugen
Erzeugt ein EN-16931-konformes XRechnungs-XML-Dokument aus strukturierten JSON-Rechnungsdaten – kein PDF erforderlich. Die XML-Syntax ist standardmäßig CII; setzen Sie `xmlFormat` auf `UBL`, um stattdessen ein UBL-Dokument zu erhalten (`xmlFormat: "CII"` liefert CII, wie wenn das Feld fehlt). Das Rechnungs-JSON ist für beide Syntaxen identisch — nur das XML in der Antwort ändert sich. UBL-Ausgabe gibt es nur über diesen Endpunkt; die ZUGFeRD-Endpunkte betten, wie vom ZUGFeRD-Standard verlangt, immer CII-XML ein.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
xmlFormat | string | optional | Syntax des erzeugten XML: `CII` (UN/CEFACT Cross Industry Invoice, Standard, wenn das Feld fehlt) oder `UBL` (Universal Business Language, UBL-2.1-`Invoice`). Die Groß-/Kleinschreibung spielt keine Rolle, `ubl` und `UBL` wirken gleich. Das Feld bestimmt das XML in `xInvoice` und unter `downloadURL`; der Aufruf ist sonst unverändert. Beispiel: `{ "invoice": { … }, "xmlFormat": "UBL" }`. Validierungsbefunde nennen das Regelwerk der jeweiligen Syntax (siehe `schemaFile` unten). |
Beispiel
{
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125",
"supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
"attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
},
"xmlFormat": "CII",
"transport": {
"type": "email",
"useTransport": true,
"sender": "rechnung@ihre-domain.de",
"senderName": "Ihre Firma GmbH",
"receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
"cc": "steuerberater@kanzlei.de",
"bcc": "archiv@ihre-domain.de",
"subject": "Rechnung {invoicenumber} vom {invoicedate}",
"message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
"attachments": [
{
"fileName": "Leistungsnachweis.pdf",
"fileBase64": "<base64>"
}
]
}
}Beispielantwort
{
"message": "xInvoice generated",
"valid": true,
"numberOfXInvoiceErrors": 0,
"xInvoiceErrors": [],
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"downloadURL": "https://api.rechnungsapi.de/file/get/1793267754_Qx7LmN2pVd9RtKs4WbHy8CfJe1ZaGu3o",
"resendToken": "",
"invoice": [
{
"invoiceNumber": "RE-2025-001",
"invoiceIssueDate": "2026-02-16T00:00:00+01:00",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"vatAccountingCurrencyCode": null,
"valueAddedTaxPointDate": null,
"valueAddedTaxPointDateCode": "",
"paymentDueDate": "2026-03-02T00:00:00+01:00",
"buyerReference": "BEST-2025-042",
"projectReference": {
"projectReferenceIdentifier": "",
"projectReferenceName": ""
},
"contractReference": "",
"purchaseOrderReference": "",
"salesOrderReference": "",
"receivingAdviceReference": "",
"despatchAdviceReference": "",
"tenderOrLotReference": null,
"invoicedObjectIdentifier": null,
"buyerAccountingReference": "Sachkonto 12000",
"paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
"invoiceNote": [],
"processControl": {
"businessProcessTypeIdentifier": "",
"specificationIdentifier": ""
},
"precedingInvoiceReference": [],
"seller": {
"sellerName": "Ihre Firma GmbH",
"sellerTradingName": "",
"sellerIdentifier": [],
"sellerLegalRegistrationIdentifier": "HRB 67890 B",
"sellerVatIdentifier": "DE123456789",
"sellerTaxRegistrationIdentifier": "12/345/67890",
"sellerAdditionalLegalInformation": "",
"sellerElectronicAddress": "info@ihre-firma.de",
"sellerPostalAddress": {
"sellerAddressLine1": "Musterstraße 1",
"sellerAddressLine2": "",
"sellerAddressLine3": "",
"sellerCity": "Berlin",
"sellerPostCode": "12345",
"sellerCountrySubdivision": "",
"sellerCountryCode": "DE"
},
"sellerContact": {
"sellerContactPoint": "Vertrieb",
"sellerContactTelephoneNumber": "+49 30 9876543",
"sellerContactEmailAddress": "info@ihre-firma.de"
}
},
"buyer": {
"buyerName": "Müller und Mayer GmbH",
"buyerTradingName": "",
"buyerIdentifier": "",
"buyerLegalRegistrationIdentifier": "HRB 12345",
"buyerVatIdentifier": "DE987654321",
"buyerElectronicAddress": "rechnung@mueller-mayer.de",
"buyerPostalAddress": {
"buyerAddressLine1": "Kundenstraße 42",
"buyerAddressLine2": "",
"buyerAddressLine3": "",
"buyerCity": "Berlin",
"buyerPostCode": "10115",
"buyerCountrySubdivision": "",
"buyerCountryCode": "DE"
},
"buyerContact": {
"buyerContactPoint": "",
"buyerContactTelephoneNumber": "+49 30 12345678",
"buyerContactEmailAddress": "rechnung@mueller-mayer.de"
}
},
"payee": {
"payeeName": "",
"payeeIdentifier": "",
"payeeLegalRegistrationIdentifier": ""
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "",
"sellerTaxRepresentativeVatIdentifier": "",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "",
"taxRepresentativeAddressLine2": "",
"taxRepresentativeAddressLine3": "",
"taxRepresentativeCity": "",
"taxRepresentativePostCode": "",
"taxRepresentativeCountrySubdivision": "",
"taxRepresentativeCountryCode": ""
}
},
"deliveryInformation": null,
"invoicingPeriod": {
"invoicingPeriodStartDate": null,
"invoicingPeriodEndDate": null
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"paymentMeansText": "SEPA-Überweisung",
"remittanceInformation": "RE-2025-001",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE89370400440532013000",
"paymentAccountName": "Ihre Firma GmbH",
"paymentServiceProviderIdentifier": "COBADEFFXXX"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "",
"paymentCardHolderName": ""
},
"directDebit": {
"mandateReferenceIdentifier": "",
"bankAssignedCreditorIdentifier": "",
"debitedAccountIdentifier": ""
}
},
"documentLevelAllowances": [],
"documentLevelCharges": [],
"documentTotals": {
"sumOfInvoiceLineNetAmount": 1799,
"sumOfAllowancesOnDocumentLevel": 0,
"sumOfChargesOnDocumentLevel": 0,
"invoiceTotalAmountWithoutVat": 1799,
"invoiceTotalVatAmount": 341.81,
"invoiceTotalVatAmountInAccountingCurrency": 0,
"invoiceTotalAmountWithVat": 2140.81,
"paidAmount": 0,
"roundingAmount": 0,
"amountDueForPayment": 2140.81
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 1799,
"vatCategoryTaxAmount": 341.81,
"vatCategoryCode": "S",
"vatCategoryRate": 19,
"vatExemptionReasonText": "",
"vatExemptionReasonCode": ""
}
],
"additionalSupportingDocuments": [],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoiceLineNote": "",
"invoiceLineObjectIdentifier": "",
"invoicedQuantity": 10,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1200,
"referencedPurchaseOrderLineReference": "",
"invoiceLineBuyerAccountingReference": "",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": null,
"invoiceLinePeriodEndDate": null
},
"invoiceLineAllowances": [],
"invoiceLineCharges": [],
"priceDetails": {
"itemNetPrice": 120,
"itemPriceDiscount": 0,
"itemGrossPrice": 120,
"itemPriceBaseQuantity": 1,
"itemPriceBaseQuantityUnitOfMeasure": "HUR"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratung & Projektbegleitung",
"itemDescription": "",
"itemSellersIdentifier": "",
"itemBuyersIdentifier": "",
"itemStandardIdentifier": "",
"itemStandardIdentifierSchemeIdentifier": "",
"itemClassificationIdentifier": [],
"itemCountryOfOrigin": "",
"itemAttributes": []
}
}
]
}
]
}Antwortfelder
| Field | Type | Description |
|---|---|---|
message | string | Statustext, `xInvoice generated`. |
valid | boolean | `true`, wenn das erzeugte XML die Validierung bestanden hat (`xInvoiceErrors` ist leer). Das XML wird in jedem Fall zurückgegeben. |
numberOfXInvoiceErrors | integer | Anzahl der Einträge in `xInvoiceErrors`. |
xInvoiceErrors | array | Validierungsbefunde zum erzeugten XML; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
xInvoiceErrors[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
xInvoiceErrors[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
xInvoiceErrors[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
xInvoiceErrors[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
xInvoiceErrors[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
xInvoiceErrors[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
xInvoice | string | Das erzeugte XRechnungs-XML (UTF-8) in der mit `xmlFormat` angeforderten Syntax — standardmäßig CII, auf Wunsch UBL —, inline zurückgegeben, auch wenn `valid` `false` ist. |
downloadURL | string (url) | Link zum erzeugten XML (`Content-Type: application/xml`). Er lässt sich ohne Authorization-Header öffnen — jeder, der den Link kennt, kann die Datei herunterladen. Behandeln Sie ihn wie ein Geheimnis. |
resendToken | string | Leerer String `""`, wenn keine E-Mail versendet wurde. Wurde `transport` bei einem gültigen Dokument genutzt, der Token für `sendEmailWithZugferdData` — siehe E-Mail-Versand. |
invoice | array | Ein Array mit einem Element: die Rechnung, wie das System sie verstanden hat — das vollständige Rechnungsobjekt (siehe unten), normalisiert. Jedes Feld ist vorhanden — nicht gesetzte Textfelder sind `""`, nicht gesetzte Datumswerte und Objekte `null`, nicht gesetzte Listen `[]`; Datumswerte sind ISO-8601-Zeitstempel mit UTC-Offset (z. B. `2026-02-16T00:00:00+01:00`). Weggelassene Preisangaben werden mit `0` befüllt. |
Beispielantwort
{
"message": "xInvoice generated",
"valid": true,
"numberOfXInvoiceErrors": 0,
"xInvoiceErrors": [],
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ubl:Invoice xmlns:ubl=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\" xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\" xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\">...</ubl:Invoice>",
"downloadURL": "https://api.rechnungsapi.de/file/get/1793267803_Wd5TrB1nXcQ8LsKy3MzHp6EvAj2UfGo9",
"resendToken": "",
"invoice": [
{
"invoiceNumber": "RE-2025-001",
"invoiceIssueDate": "2026-02-16T00:00:00+01:00",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"vatAccountingCurrencyCode": null,
"valueAddedTaxPointDate": null,
"valueAddedTaxPointDateCode": "",
"paymentDueDate": "2026-03-02T00:00:00+01:00",
"buyerReference": "BEST-2025-042",
"projectReference": {
"projectReferenceIdentifier": "",
"projectReferenceName": ""
},
"contractReference": "",
"purchaseOrderReference": "",
"salesOrderReference": "",
"receivingAdviceReference": "",
"despatchAdviceReference": "",
"tenderOrLotReference": null,
"invoicedObjectIdentifier": null,
"buyerAccountingReference": "Sachkonto 12000",
"paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
"invoiceNote": [],
"processControl": {
"businessProcessTypeIdentifier": "",
"specificationIdentifier": ""
},
"precedingInvoiceReference": [],
"seller": {
"sellerName": "Ihre Firma GmbH",
"sellerTradingName": "",
"sellerIdentifier": [],
"sellerLegalRegistrationIdentifier": "HRB 67890 B",
"sellerVatIdentifier": "DE123456789",
"sellerTaxRegistrationIdentifier": "12/345/67890",
"sellerAdditionalLegalInformation": "",
"sellerElectronicAddress": "info@ihre-firma.de",
"sellerPostalAddress": {
"sellerAddressLine1": "Musterstraße 1",
"sellerAddressLine2": "",
"sellerAddressLine3": "",
"sellerCity": "Berlin",
"sellerPostCode": "12345",
"sellerCountrySubdivision": "",
"sellerCountryCode": "DE"
},
"sellerContact": {
"sellerContactPoint": "Vertrieb",
"sellerContactTelephoneNumber": "+49 30 9876543",
"sellerContactEmailAddress": "info@ihre-firma.de"
}
},
"buyer": {
"buyerName": "Müller und Mayer GmbH",
"buyerTradingName": "",
"buyerIdentifier": "",
"buyerLegalRegistrationIdentifier": "HRB 12345",
"buyerVatIdentifier": "DE987654321",
"buyerElectronicAddress": "rechnung@mueller-mayer.de",
"buyerPostalAddress": {
"buyerAddressLine1": "Kundenstraße 42",
"buyerAddressLine2": "",
"buyerAddressLine3": "",
"buyerCity": "Berlin",
"buyerPostCode": "10115",
"buyerCountrySubdivision": "",
"buyerCountryCode": "DE"
},
"buyerContact": {
"buyerContactPoint": "",
"buyerContactTelephoneNumber": "+49 30 12345678",
"buyerContactEmailAddress": "rechnung@mueller-mayer.de"
}
},
"payee": {
"payeeName": "",
"payeeIdentifier": "",
"payeeLegalRegistrationIdentifier": ""
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "",
"sellerTaxRepresentativeVatIdentifier": "",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "",
"taxRepresentativeAddressLine2": "",
"taxRepresentativeAddressLine3": "",
"taxRepresentativeCity": "",
"taxRepresentativePostCode": "",
"taxRepresentativeCountrySubdivision": "",
"taxRepresentativeCountryCode": ""
}
},
"deliveryInformation": null,
"invoicingPeriod": {
"invoicingPeriodStartDate": null,
"invoicingPeriodEndDate": null
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"paymentMeansText": "SEPA-Überweisung",
"remittanceInformation": "RE-2025-001",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE89370400440532013000",
"paymentAccountName": "Ihre Firma GmbH",
"paymentServiceProviderIdentifier": "COBADEFFXXX"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "",
"paymentCardHolderName": ""
},
"directDebit": {
"mandateReferenceIdentifier": "",
"bankAssignedCreditorIdentifier": "",
"debitedAccountIdentifier": ""
}
},
"documentLevelAllowances": [],
"documentLevelCharges": [],
"documentTotals": {
"sumOfInvoiceLineNetAmount": 1799,
"sumOfAllowancesOnDocumentLevel": 0,
"sumOfChargesOnDocumentLevel": 0,
"invoiceTotalAmountWithoutVat": 1799,
"invoiceTotalVatAmount": 341.81,
"invoiceTotalVatAmountInAccountingCurrency": 0,
"invoiceTotalAmountWithVat": 2140.81,
"paidAmount": 0,
"roundingAmount": 0,
"amountDueForPayment": 2140.81
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 1799,
"vatCategoryTaxAmount": 341.81,
"vatCategoryCode": "S",
"vatCategoryRate": 19,
"vatExemptionReasonText": "",
"vatExemptionReasonCode": ""
}
],
"additionalSupportingDocuments": [],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoiceLineNote": "",
"invoiceLineObjectIdentifier": "",
"invoicedQuantity": 10,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1200,
"referencedPurchaseOrderLineReference": "",
"invoiceLineBuyerAccountingReference": "",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": null,
"invoiceLinePeriodEndDate": null
},
"invoiceLineAllowances": [],
"invoiceLineCharges": [],
"priceDetails": {
"itemNetPrice": 120,
"itemPriceDiscount": 0,
"itemGrossPrice": 120,
"itemPriceBaseQuantity": 1,
"itemPriceBaseQuantityUnitOfMeasure": "HUR"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratung & Projektbegleitung",
"itemDescription": "",
"itemSellersIdentifier": "",
"itemBuyersIdentifier": "",
"itemStandardIdentifier": "",
"itemStandardIdentifierSchemeIdentifier": "",
"itemClassificationIdentifier": [],
"itemCountryOfOrigin": "",
"itemAttributes": []
}
}
]
}
]
}Beispielantwort
{
"message": "xInvoice generated",
"valid": false,
"numberOfXInvoiceErrors": 10,
"xInvoiceErrors": [
{
"message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
"id": "BR-CO-25",
"line": null
},
{
"message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
"schemaFile": "XRechnung-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
"id": "BR-DE-15",
"line": null
}
],
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"downloadURL": "https://api.rechnungsapi.de/file/get/1793267782_Hk3VnB8sQwXc5MtYj2PdLr7EaUf9ZoGi",
"resendToken": "",
"invoice": [
{
"invoiceNumber": "RE-2025-002",
"invoiceIssueDate": "2026-02-16T00:00:00+01:00",
"…": "the complete normalised invoice, same structure as in the response above"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
/api/v1/zugferd/createZugferdFromJsonZUGFeRD aus JSON + PDF erzeugen
Kombiniert strukturierte JSON-Rechnungsdaten mit einem vorhandenen PDF zu einem ZUGFeRD-konformen PDF/A-3-Dokument mit eingebetteter XRechnungs-XML.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
invoicePdf64 | string (base64) | required | Base64-kodiertes PDF für die XML-Einbettung. |
Beispiel
{
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125",
"supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
"attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
},
"invoicePdf64": "JVBERi0xLjQK...",
"transport": {
"type": "email",
"useTransport": true,
"sender": "rechnung@ihre-domain.de",
"senderName": "Ihre Firma GmbH",
"receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
"cc": "steuerberater@kanzlei.de",
"bcc": "archiv@ihre-domain.de",
"subject": "Rechnung {invoicenumber} vom {invoicedate}",
"message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
"attachments": [
{
"fileName": "Leistungsnachweis.pdf",
"fileBase64": "<base64>"
}
]
}
}Beispielantwort
{
"message": "ZUGFeRD created",
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"zugferd": "JVBERi0xLjcKJaLN+vwK...",
"downloadURL": "https://api.rechnungsapi.de/file/get/1793359631_NbRS0bMYy68cicTsBocYzDK8MHCAFIz0",
"resendToken": "",
"xInvoiceValid": true,
"zugferdValid": true,
"numberOfxInvoiceErrors": 0,
"numberOfZugferdErrors": 0,
"xInvoiceErrorList": [],
"zugferdErrorList": [],
"invoiceJson": [
{
"invoiceNumber": "RE-2025-001",
"invoiceIssueDate": "2026-02-16T00:00:00+01:00",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"vatAccountingCurrencyCode": null,
"valueAddedTaxPointDate": null,
"valueAddedTaxPointDateCode": "",
"paymentDueDate": "2026-03-02T00:00:00+01:00",
"buyerReference": "BEST-2025-042",
"projectReference": {
"projectReferenceIdentifier": "",
"projectReferenceName": ""
},
"contractReference": "",
"purchaseOrderReference": "",
"salesOrderReference": "",
"receivingAdviceReference": "",
"despatchAdviceReference": "",
"tenderOrLotReference": null,
"invoicedObjectIdentifier": null,
"buyerAccountingReference": "Sachkonto 12000",
"paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
"invoiceNote": [],
"processControl": {
"businessProcessTypeIdentifier": "",
"specificationIdentifier": ""
},
"precedingInvoiceReference": [],
"seller": {
"sellerName": "Ihre Firma GmbH",
"sellerTradingName": "",
"sellerIdentifier": [],
"sellerLegalRegistrationIdentifier": "HRB 67890 B",
"sellerVatIdentifier": "DE123456789",
"sellerTaxRegistrationIdentifier": "12/345/67890",
"sellerAdditionalLegalInformation": "",
"sellerElectronicAddress": "info@ihre-firma.de",
"sellerPostalAddress": {
"sellerAddressLine1": "Musterstraße 1",
"sellerAddressLine2": "",
"sellerAddressLine3": "",
"sellerCity": "Berlin",
"sellerPostCode": "12345",
"sellerCountrySubdivision": "",
"sellerCountryCode": "DE"
},
"sellerContact": {
"sellerContactPoint": "Vertrieb",
"sellerContactTelephoneNumber": "+49 30 9876543",
"sellerContactEmailAddress": "info@ihre-firma.de"
}
},
"buyer": {
"buyerName": "Müller und Mayer GmbH",
"buyerTradingName": "",
"buyerIdentifier": "",
"buyerLegalRegistrationIdentifier": "HRB 12345",
"buyerVatIdentifier": "DE987654321",
"buyerElectronicAddress": "rechnung@mueller-mayer.de",
"buyerPostalAddress": {
"buyerAddressLine1": "Kundenstraße 42",
"buyerAddressLine2": "",
"buyerAddressLine3": "",
"buyerCity": "Berlin",
"buyerPostCode": "10115",
"buyerCountrySubdivision": "",
"buyerCountryCode": "DE"
},
"buyerContact": {
"buyerContactPoint": "",
"buyerContactTelephoneNumber": "+49 30 12345678",
"buyerContactEmailAddress": "rechnung@mueller-mayer.de"
}
},
"payee": {
"payeeName": "",
"payeeIdentifier": "",
"payeeLegalRegistrationIdentifier": ""
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "",
"sellerTaxRepresentativeVatIdentifier": "",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "",
"taxRepresentativeAddressLine2": "",
"taxRepresentativeAddressLine3": "",
"taxRepresentativeCity": "",
"taxRepresentativePostCode": "",
"taxRepresentativeCountrySubdivision": "",
"taxRepresentativeCountryCode": ""
}
},
"deliveryInformation": null,
"invoicingPeriod": {
"invoicingPeriodStartDate": null,
"invoicingPeriodEndDate": null
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"paymentMeansText": "SEPA-Überweisung",
"remittanceInformation": "RE-2025-001",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE89370400440532013000",
"paymentAccountName": "Ihre Firma GmbH",
"paymentServiceProviderIdentifier": "COBADEFFXXX"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "",
"paymentCardHolderName": ""
},
"directDebit": {
"mandateReferenceIdentifier": "",
"bankAssignedCreditorIdentifier": "",
"debitedAccountIdentifier": ""
}
},
"documentLevelAllowances": [],
"documentLevelCharges": [],
"documentTotals": {
"sumOfInvoiceLineNetAmount": 1799,
"sumOfAllowancesOnDocumentLevel": 0,
"sumOfChargesOnDocumentLevel": 0,
"invoiceTotalAmountWithoutVat": 1799,
"invoiceTotalVatAmount": 341.81,
"invoiceTotalVatAmountInAccountingCurrency": 0,
"invoiceTotalAmountWithVat": 2140.81,
"paidAmount": 0,
"roundingAmount": 0,
"amountDueForPayment": 2140.81
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 1799,
"vatCategoryTaxAmount": 341.81,
"vatCategoryCode": "S",
"vatCategoryRate": 19,
"vatExemptionReasonText": "",
"vatExemptionReasonCode": ""
}
],
"additionalSupportingDocuments": [],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoiceLineNote": "",
"invoiceLineObjectIdentifier": "",
"invoicedQuantity": 10,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1200,
"referencedPurchaseOrderLineReference": "",
"invoiceLineBuyerAccountingReference": "",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": null,
"invoiceLinePeriodEndDate": null
},
"invoiceLineAllowances": [],
"invoiceLineCharges": [],
"priceDetails": {
"itemNetPrice": 120,
"itemPriceDiscount": 0,
"itemGrossPrice": 120,
"itemPriceBaseQuantity": 1,
"itemPriceBaseQuantityUnitOfMeasure": "HUR"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratung & Projektbegleitung",
"itemDescription": "",
"itemSellersIdentifier": "",
"itemBuyersIdentifier": "",
"itemStandardIdentifier": "",
"itemStandardIdentifierSchemeIdentifier": "",
"itemClassificationIdentifier": [],
"itemCountryOfOrigin": "",
"itemAttributes": []
}
}
]
}
],
"invoice": [
{
"invoiceNumber": "RE-2025-001",
"invoiceIssueDate": "2026-02-16T00:00:00+01:00",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"vatAccountingCurrencyCode": null,
"valueAddedTaxPointDate": null,
"valueAddedTaxPointDateCode": "",
"paymentDueDate": "2026-03-02T00:00:00+01:00",
"buyerReference": "BEST-2025-042",
"projectReference": {
"projectReferenceIdentifier": "",
"projectReferenceName": ""
},
"contractReference": "",
"purchaseOrderReference": "",
"salesOrderReference": "",
"receivingAdviceReference": "",
"despatchAdviceReference": "",
"tenderOrLotReference": null,
"invoicedObjectIdentifier": null,
"buyerAccountingReference": "Sachkonto 12000",
"paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
"invoiceNote": [],
"processControl": {
"businessProcessTypeIdentifier": "",
"specificationIdentifier": ""
},
"precedingInvoiceReference": [],
"seller": {
"sellerName": "Ihre Firma GmbH",
"sellerTradingName": "",
"sellerIdentifier": [],
"sellerLegalRegistrationIdentifier": "HRB 67890 B",
"sellerVatIdentifier": "DE123456789",
"sellerTaxRegistrationIdentifier": "12/345/67890",
"sellerAdditionalLegalInformation": "",
"sellerElectronicAddress": "info@ihre-firma.de",
"sellerPostalAddress": {
"sellerAddressLine1": "Musterstraße 1",
"sellerAddressLine2": "",
"sellerAddressLine3": "",
"sellerCity": "Berlin",
"sellerPostCode": "12345",
"sellerCountrySubdivision": "",
"sellerCountryCode": "DE"
},
"sellerContact": {
"sellerContactPoint": "Vertrieb",
"sellerContactTelephoneNumber": "+49 30 9876543",
"sellerContactEmailAddress": "info@ihre-firma.de"
}
},
"buyer": {
"buyerName": "Müller und Mayer GmbH",
"buyerTradingName": "",
"buyerIdentifier": "",
"buyerLegalRegistrationIdentifier": "HRB 12345",
"buyerVatIdentifier": "DE987654321",
"buyerElectronicAddress": "rechnung@mueller-mayer.de",
"buyerPostalAddress": {
"buyerAddressLine1": "Kundenstraße 42",
"buyerAddressLine2": "",
"buyerAddressLine3": "",
"buyerCity": "Berlin",
"buyerPostCode": "10115",
"buyerCountrySubdivision": "",
"buyerCountryCode": "DE"
},
"buyerContact": {
"buyerContactPoint": "",
"buyerContactTelephoneNumber": "+49 30 12345678",
"buyerContactEmailAddress": "rechnung@mueller-mayer.de"
}
},
"payee": {
"payeeName": "",
"payeeIdentifier": "",
"payeeLegalRegistrationIdentifier": ""
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "",
"sellerTaxRepresentativeVatIdentifier": "",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "",
"taxRepresentativeAddressLine2": "",
"taxRepresentativeAddressLine3": "",
"taxRepresentativeCity": "",
"taxRepresentativePostCode": "",
"taxRepresentativeCountrySubdivision": "",
"taxRepresentativeCountryCode": ""
}
},
"deliveryInformation": null,
"invoicingPeriod": {
"invoicingPeriodStartDate": null,
"invoicingPeriodEndDate": null
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"paymentMeansText": "SEPA-Überweisung",
"remittanceInformation": "RE-2025-001",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE89370400440532013000",
"paymentAccountName": "Ihre Firma GmbH",
"paymentServiceProviderIdentifier": "COBADEFFXXX"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "",
"paymentCardHolderName": ""
},
"directDebit": {
"mandateReferenceIdentifier": "",
"bankAssignedCreditorIdentifier": "",
"debitedAccountIdentifier": ""
}
},
"documentLevelAllowances": [],
"documentLevelCharges": [],
"documentTotals": {
"sumOfInvoiceLineNetAmount": 1799,
"sumOfAllowancesOnDocumentLevel": 0,
"sumOfChargesOnDocumentLevel": 0,
"invoiceTotalAmountWithoutVat": 1799,
"invoiceTotalVatAmount": 341.81,
"invoiceTotalVatAmountInAccountingCurrency": 0,
"invoiceTotalAmountWithVat": 2140.81,
"paidAmount": 0,
"roundingAmount": 0,
"amountDueForPayment": 2140.81
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 1799,
"vatCategoryTaxAmount": 341.81,
"vatCategoryCode": "S",
"vatCategoryRate": 19,
"vatExemptionReasonText": "",
"vatExemptionReasonCode": ""
}
],
"additionalSupportingDocuments": [],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoiceLineNote": "",
"invoiceLineObjectIdentifier": "",
"invoicedQuantity": 10,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1200,
"referencedPurchaseOrderLineReference": "",
"invoiceLineBuyerAccountingReference": "",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": null,
"invoiceLinePeriodEndDate": null
},
"invoiceLineAllowances": [],
"invoiceLineCharges": [],
"priceDetails": {
"itemNetPrice": 120,
"itemPriceDiscount": 0,
"itemGrossPrice": 120,
"itemPriceBaseQuantity": 1,
"itemPriceBaseQuantityUnitOfMeasure": "HUR"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratung & Projektbegleitung",
"itemDescription": "",
"itemSellersIdentifier": "",
"itemBuyersIdentifier": "",
"itemStandardIdentifier": "",
"itemStandardIdentifierSchemeIdentifier": "",
"itemClassificationIdentifier": [],
"itemCountryOfOrigin": "",
"itemAttributes": []
}
}
]
}
]
}Antwortfelder
| Field | Type | Description |
|---|---|---|
message | string | Statustext, `ZUGFeRD created`. |
xInvoice | string | Das aus Ihren Rechnungsdaten erzeugte und ins PDF eingebettete XRechnungs-XML (UTF-8), inline zurückgegeben. |
zugferd | string (base64) | Das ZUGFeRD-PDF/A-3, Base64-kodiert — auch wenn die Validierung Fehler gefunden hat. |
downloadURL | string (url) | Link zur erzeugten Datei. Er lässt sich ohne Authorization-Header öffnen — jeder, der den Link kennt, kann sie herunterladen. Behandeln Sie ihn wie ein Geheimnis. |
resendToken | string | Leerer String `""`, wenn keine E-Mail versendet wurde. Wurde `transport` bei einem gültigen Dokument genutzt, der Token für `sendEmailWithZugferdData` — siehe E-Mail-Versand. |
xInvoiceValid | boolean | `true`, wenn das erzeugte XML die Validierung bestanden hat (`xInvoiceErrorList` ist leer). |
zugferdValid | boolean | `true`, wenn das fertige ZUGFeRD-PDF die Validierung bestanden hat (`zugferdErrorList` ist leer). |
numberOfxInvoiceErrors | integer | Anzahl der Einträge in `xInvoiceErrorList`. Beachten Sie das kleine `x` in diesem Namen. |
numberOfZugferdErrors | integer | Anzahl der Einträge in `zugferdErrorList`. |
xInvoiceErrorList | array | Validierungsbefunde zum erzeugten XML; leer, wenn `xInvoiceValid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
xInvoiceErrorList[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
xInvoiceErrorList[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
xInvoiceErrorList[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
xInvoiceErrorList[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
xInvoiceErrorList[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
xInvoiceErrorList[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
zugferdErrorList | array | Validierungsbefunde zum fertigen ZUGFeRD-PDF; leer, wenn `zugferdValid` `true` ist. Dieselben Eigenschaften wie oben. |
invoiceJson | array | Ein Array mit einem Element: die Rechnung, wie das System sie verstanden hat — das vollständige Rechnungsobjekt, normalisiert (siehe `createXinvoiceFromJson`). Identisch mit `invoice`. |
invoice | array | Dieselbe normalisierte Rechnung wie in `invoiceJson`, unter dem Namen wiederholt, den auch `createXinvoiceFromJson` verwendet. |
Beispielantwort
{
"message": "ZUGFeRD created",
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"zugferd": "JVBERi0xLjcKJaLN+vwK...",
"downloadURL": "https://api.rechnungsapi.de/file/get/1793364463_3uLBx0wWp4ABuFRtYQFzpqzQ0MGthdNV",
"resendToken": "",
"xInvoiceValid": false,
"zugferdValid": false,
"numberOfxInvoiceErrors": 3,
"numberOfZugferdErrors": 3,
"xInvoiceErrorList": [
{
"message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
"schemaFile": "XRechnung-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
"id": "BR-DE-15",
"line": null
},
{
"message": "[BR-DE-6] Das Element \"Seller contact telephone number\" (BT-42) muss übermittelt werden.",
"schemaFile": "XRechnung-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeAgreement[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}SellerTradeParty[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}DefinedTradeContact[1]",
"id": "BR-DE-6",
"line": null
}
],
"zugferdErrorList": [
{
"message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
"schemaFile": "XRechnung-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
"id": "BR-DE-15",
"line": null
}
],
"invoiceJson": [
{
"invoiceNumber": "RE-2025-002",
"…": "the complete normalised invoice, same structure as in the response above"
}
],
"invoice": [
{
"invoiceNumber": "RE-2025-002",
"…": "the complete normalised invoice, same structure as in the response above"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
/api/v1/zugferd/createZugferdPdfFromXinvoiceZUGFeRD-PDF aus XRechnung erstellen
Erstellt ein ZUGFeRD-konformes PDF/A-3, indem eine vorhandene XRechnungs-XML in ein PDF-Dokument eingebettet wird.
| Field | Type | Required | Description |
|---|---|---|---|
xInvoiceXml | string | required | XRechnungs-XML als String. |
invoicePdf64 | string (base64) | required | Base64-kodiertes PDF für die XML-Einbettung. |
Beispiel
{
"xInvoiceXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"invoicePdf64": "JVBERi0xLjQK..."
}Beispielantwort
{
"message": "zugferd created",
"valid": false,
"numberOfZugferdErrors": 1,
"zugferdErrors": [
{
"message": "[PEPPOL-EN16931-R008]-Document MUST not contain empty elements.",
"schemaFile": "XRechnung-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeDelivery[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ShipToTradeParty[1]",
"id": "PEPPOL-EN16931-R008",
"line": null
}
],
"zugferdFile": "JVBERi0xLjcKJaOIwOMKMyAwIG9iago...",
"createdInvoice": [
{
"invoiceNumber": "RE-2025-001",
"…": "the complete invoice the PDF was built from — same structure as the Invoice Object"
}
],
"extractedInvoice": [
{
"invoiceNumber": "RE-2025-001",
"…": "the complete invoice read back from the finished ZUGFeRD — same structure as `extractedInvoice` of extractXInvoiceFromZugferdToJson, but wrapped in an array"
}
],
"validXRechnung": true,
"xrechnungErrors": []
}Antwortfelder
| Field | Type | Description |
|---|---|---|
message | string | Statustext, `zugferd created`. |
valid | boolean | `true`, wenn das fertige ZUGFeRD-PDF die Validierung bestanden hat (`zugferdErrors` ist leer). Das PDF wird in jedem Fall zurückgegeben. |
numberOfZugferdErrors | integer | Anzahl der Einträge in `zugferdErrors`. |
zugferdErrors | array | Validierungsbefunde zum fertigen ZUGFeRD-PDF; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
zugferdErrors[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
zugferdErrors[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
zugferdErrors[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrors[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrors[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
zugferdErrors[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
zugferdFile | string (base64) | Das ZUGFeRD-PDF/A-3, Base64-kodiert. |
createdInvoice | array | Ein Array mit einem Element: die Rechnungsdaten, aus denen das PDF gebaut wurde, d. h. Ihr XML, geparst in die Struktur des Rechnungsobjekts. |
extractedInvoice | array | Ein Array mit einem Element: die aus dem fertigen ZUGFeRD zurückgelesenen Rechnungsdaten, in derselben Form wie das `extractedInvoice` von `extractXInvoiceFromZugferdToJson` — hier aber in ein Array verpackt. |
validXRechnung | boolean | `true`, wenn das von Ihnen übergebene XML die XRechnung-Validierung bestanden hat (`xrechnungErrors` ist leer). |
xrechnungErrors | array | Validierungsbefunde zum übergebenen XML, in derselben Form wie `zugferdErrors`; leer, wenn `validXRechnung` `true` ist. |
Playground
Diesen Endpunkt live im Browser testen.
/api/v1/zugferd/createInvoicePdfFromJsonZUGFeRD-Rechnungs-PDF aus JSON erzeugen (Template)
Erzeugt ein ZUGFeRD-konformes Rechnungs-PDF aus JSON-Daten über ein eigenes Word- oder Design-Template. Ab 2027 in Deutschland verpflichtend. Unterstützt einen optionalen Idempotency-Key-Request-Header (beliebiger eindeutiger String, z. B. eine UUID): Die erste Anfrage mit einem bestimmten Key wird normal verarbeitet, ihre Antwort – inklusive Rechnungsnummer, Download-URL und ZUGFeRD-Daten – wird 24 Stunden lang zwischengespeichert. Wird derselbe Key mit identischem Body innerhalb dieses Zeitraums erneut gesendet, liefert die API die ursprünglich zwischengespeicherte Antwort zurück, statt eine neue Rechnung zu erzeugen – dabei werden keine Credits verbraucht. Der Response-Header X-Idempotency-Key-Reused zeigt an, was passiert ist: true bei einer wiederholten Antwort aus dem Cache, false bei einer frisch erzeugten. Wird derselbe Key mit abweichendem Request-Body wiederverwendet, wird die Anfrage mit 409 Conflict abgelehnt – ebenfalls ohne Credit-Verbrauch.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
templateId | string | required | ID des Templates für die PDF-Erzeugung. |
invoiceFilename | string | optional | Eigener Dateiname für die erzeugte PDF-Datei, anstelle des automatisch generierten Namens (z. B. für den E-Mail-Anhang bei Nutzung von transport, oder beim direkten Speichern der Response als Datei). Wird das Feld weggelassen, vergibt die API wie bisher automatisch einen Dateinamen. |
invoicePassthrough | boolean | optional | Standardmäßig true. Jede erzeugte Rechnung erhält einen Eintrag in der Rechnungsliste Ihres Kontos. Bei true wird das Dokument selbst nicht gespeichert – es wird nur in der Response zurückgegeben, speichern Sie es von dort. Auf false setzen, um zusätzlich das Dokument zu speichern, sodass es später in der Rechnungsliste angesehen und heruntergeladen werden kann. Hinweis zur Seite „Rechnung erstellen" im Dashboard: Dort wird dies als Frage „Möchten Sie das Rechnungsdokument speichern?" mit Ja/Nein dargestellt (Nein vorausgewählt) – „Nein“ sendet invoicePassthrough: true (Standard), „Ja“ sendet invoicePassthrough: false. |
Beispiel
{
"templateId": "your-template-id",
"invoiceFilename": "my-custom-invoice-name.pdf",
"invoicePassthrough": false,
"invoice": {
"invoiceNumber": "String | BT-1",
"invoiceIssueDate": "Date | BT-2",
"invoiceTypeCode": "String | BT-3",
"invoiceCurrencyCode": "String | BT-5",
"vatAccountingCurrencyCode": "String | BT-6",
"valueAddedTaxPointDate": "String | BT-7",
"valueAddedTaxPointDateCode": "String | BT-8",
"paymentDueDate": "Date | BT-9",
"buyerReference": "String | BT-10",
"projectReference": {
"projectReferenceIdentifier": "String | BT-11",
"projectReferenceName": "String | BT-11-0"
},
"contractReference": "String | BT-12",
"purchaseOrderReference": "String | BT-13",
"salesOrderReference": "String | BT-14",
"receivingAdviceReference": "String | BT-15",
"despatchAdviceReference": "String | BT-16",
"tenderOrLotReference": "String | BT-17",
"invoicedObjectIdentifier": "String | BT-18",
"buyerAccountingReference": "String | BT-19",
"paymentTerms": "String | BT-20",
"invoiceNote": [
{
"invoiceNoteSubjectCode": "String | BT-21",
"invoiceNote": "String | BT-22"
}
],
"processControl": {
"businessProcessTypeIdentifier": "String | BT-23",
"specificationIdentifier": "String | BT-24"
},
"precedingInvoiceReference": [
{
"precedingInvoiceReference": "String | BT-25",
"precedingInvoiceIssueDate": "Date | BT-26"
}
],
"seller": {
"sellerName": "String | BT-27",
"sellerTradingName": "String | BT-28",
"sellerIdentifier": [
"String | BT-29"
],
"sellerLegalRegistrationIdentifier": "String | BT-30",
"sellerVatIdentifier": "String | BT-31",
"sellerTaxRegistrationIdentifier": "String | BT-32",
"sellerAdditionalLegalInformation": "String | BT-33",
"sellerElectronicAddress": "String | BT-34",
"sellerPostalAddress": {
"sellerAddressLine1": "String | BT-35",
"sellerAddressLine2": "String | BT-36",
"sellerAddressLine3": "String | BT-162",
"sellerCity": "String | BT-37",
"sellerPostCode": "String | BT-38",
"sellerCountrySubdivision": "String | BT-39",
"sellerCountryCode": "String | BT-40"
},
"sellerContact": {
"sellerContactPoint": "String | BT-41",
"sellerContactTelephoneNumber": "String | BT-42",
"sellerContactEmailAddress": "String | BT-43"
}
},
"buyer": {
"buyerName": "String | BT-44",
"buyerTradingName": "String | BT-45",
"buyerIdentifier": "String | BT-46",
"buyerLegalRegistrationIdentifier": "String | BT-47",
"buyerVatIdentifier": "String | BT-48",
"buyerElectronicAddress": "String | BT-49",
"buyerPostalAddress": {
"buyerAddressLine1": "String | BT-50",
"buyerAddressLine2": "String | BT-51",
"buyerAddressLine3": "String | BT-163",
"buyerCity": "String | BT-52",
"buyerPostCode": "String | BT-53",
"buyerCountrySubdivision": "String | BT-54",
"buyerCountryCode": "String | BT-55"
},
"buyerContact": {
"buyerContactPoint": "String | BT-56",
"buyerContactTelephoneNumber": "String | BT-57",
"buyerContactEmailAddress": "String | BT-58"
}
},
"payee": {
"payeeName": "String | BT-59",
"payeeIdentifier": "String | BT-60",
"payeeLegalRegistrationIdentifier": "String | BT-61"
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "String | BT-62",
"sellerTaxRepresentativeVatIdentifier": "String | BT-63",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "String | BT-64",
"taxRepresentativeAddressLine2": "String | BT-65",
"taxRepresentativeAddressLine3": "String | BT-164",
"taxRepresentativeCity": "String | BT-66",
"taxRepresentativePostCode": "String | BT-67",
"taxRepresentativeCountrySubdivision": "String | BT-68",
"taxRepresentativeCountryCode": "String | BT-69"
}
},
"deliveryInformation": {
"deliverToPartyName": "String | BT-70",
"deliverToLocationIdentifier": "String | BT-71",
"actualDeliveryDate": "Date | BT-72",
"deliverToAddress": {
"deliverToAddressLine1": "String | BT-75",
"deliverToAddressLine2": "String | BT-76",
"deliverToAddressLine3": "String | BT-165",
"deliverToCity": "String | BT-77",
"deliverToPostCode": "String | BT-78",
"deliverToCountrySubdivision": "String | BT-79",
"deliverToCountryCode": "String | BT-80"
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": "Date | BT-73",
"invoicingPeriodEndDate": "Date | BT-74"
},
"paymentInstructions": {
"paymentMeansTypeCode": "String | BT-81",
"paymentMeansText": "String | BT-82",
"remittanceInformation": "String | BT-83",
"creditTransfer": [
{
"paymentAccountIdentifier": "String | BT-84",
"paymentAccountName": "String | BT-85",
"paymentServiceProviderIdentifier": "String | BT-86"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "String | BT-87",
"paymentCardHolderName": "String | BT-88"
},
"directDebit": {
"mandateReferenceIdentifier": "String | BT-89",
"bankAssignedCreditorIdentifier": "String | BT-90",
"debitedAccountIdentifier": "String | BT-91"
}
},
"documentLevelAllowances": [
{
"documentLevelAllowanceAmount": "Decimal | BT-92",
"documentLevelAllowanceBaseAmount": "Decimal | BT-93",
"documentLevelAllowancePercentage": "Decimal | BT-94",
"documentLevelAllowanceVatCategoryCode": "String | BT-95",
"documentLevelAllowanceVatRate": "Decimal | BT-96",
"documentLevelAllowanceReason": "String | BT-97",
"documentLevelAllowanceReasonCode": "String | BT-98"
}
],
"documentLevelCharges": [
{
"documentLevelChargeAmount": "Decimal | BT-99",
"documentLevelChargeBaseAmount": "Decimal | BT-100",
"documentLevelChargePercentage": "Decimal | BT-101",
"documentLevelChargeVatCategoryCode": "String | BT-102",
"documentLevelChargeVatRate": "Decimal | BT-103",
"documentLevelChargeReason": "String | BT-104",
"documentLevelChargeReasonCode": "String | BT-105"
}
],
"documentTotals": {
"sumOfInvoiceLineNetAmount": "Decimal | BT-106",
"sumOfAllowancesOnDocumentLevel": "Decimal | BT-107",
"sumOfChargesOnDocumentLevel": "Decimal | BT-108",
"invoiceTotalAmountWithoutVat": "Decimal | BT-109",
"invoiceTotalVatAmount": "Decimal | BT-110",
"invoiceTotalVatAmountInAccountingCurrency": "Decimal | BT-111",
"invoiceTotalAmountWithVat": "Decimal | BT-112",
"paidAmount": "Decimal | BT-113",
"roundingAmount": "Decimal | BT-114",
"amountDueForPayment": "Decimal | BT-115"
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": "Decimal | BT-116",
"vatCategoryTaxAmount": "Decimal | BT-117",
"vatCategoryCode": "String | BT-118",
"vatCategoryRate": "Decimal | BT-119",
"vatExemptionReasonText": "String | BT-120",
"vatExemptionReasonCode": "String | BT-121"
}
],
"additionalSupportingDocuments": [
{
"supportingDocumentReference": "String | BT-122",
"supportingDocumentDescription": "String | BT-123",
"externalDocumentLocation": "String | BT-124",
"attachedDocument": "String | BT-125",
"supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
"attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
}
],
"invoiceLine": [
{
"invoiceLineIdentifier": "String | BT-126",
"invoiceLineNote": "String | BT-127",
"invoiceLineObjectIdentifier": "String | BT-128",
"invoicedQuantity": "Decimal | BT-129",
"invoicedQuantityUnitOfMeasureCode": "String | BT-130",
"invoiceLineNetAmount": "Decimal | BT-131",
"referencedPurchaseOrderLineReference": "String | BT-132",
"invoiceLineBuyerAccountingReference": "String | BT-133",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": "Date | BT-134",
"invoiceLinePeriodEndDate": "Date | BT-135"
},
"invoiceLineAllowances": [
{
"invoiceLineAllowanceAmount": "Decimal | BT-136",
"invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
"invoiceLineAllowancePercentage": "Decimal | BT-138",
"invoiceLineAllowanceReason": "String | BT-139",
"invoiceLineAllowanceReasonCode": "String | BT-140"
}
],
"invoiceLineCharges": [
{
"invoiceLineChargeAmount": "Decimal | BT-141",
"invoiceLineChargeBaseAmount": "Decimal | BT-142",
"invoiceLineChargePercentage": "Decimal | BT-143",
"invoiceLineChargeReason": "String | BT-144",
"invoiceLineChargeReasonCode": "String | BT-145"
}
],
"priceDetails": {
"itemNetPrice": "Decimal | BT-146",
"itemPriceDiscount": "Decimal | BT-147",
"itemGrossPrice": "Decimal | BT-148",
"itemPriceBaseQuantity": "Decimal | BT-149",
"itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "String | BT-151",
"invoicedItemVatRate": "Decimal | BT-152"
}
],
"itemInformation": {
"itemName": "String | BT-153",
"itemDescription": "String | BT-154",
"itemSellersIdentifier": "String | BT-155",
"itemBuyersIdentifier": "String | BT-156",
"itemStandardIdentifier": "String | BT-157",
"itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
"itemClassificationIdentifier": [
{
"itemClassificationIdentifier": "String | BT-158",
"itemClassificationIdentifierListIdentifier": "String | BT-158-1",
"itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
}
],
"itemCountryOfOrigin": "String | BT-159",
"itemAttributes": [
{
"itemAttributeName": "String | BT-160",
"itemAttributeValue": "String | BT-161"
}
]
}
}
]
},
"transport": {
"type": "email",
"useTransport": true,
"sender": "rechnung@ihre-domain.de",
"senderName": "Ihre Firma GmbH",
"receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
"cc": "steuerberater@kanzlei.de",
"bcc": "archiv@ihre-domain.de",
"subject": "Rechnung {invoicenumber} vom {invoicedate}",
"message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
"attachments": [
{
"fileName": "Leistungsnachweis.pdf",
"fileBase64": "<base64>"
}
]
}
}Beispielantwort
{
"message": "pdf created, downloaded and not stored in DMS",
"iqDataId": 136951,
"downloadURL": "https://api.rechnungsapi.de/file/get/1793363431_Zk4NpQ8sVtYw2RbJc7XmH5LdFe9GuAo3",
"resendToken": "ttsYDNZrEj9JZO12rSH5w4JwM/w7VJjEEyjcTWHj2sWa/4tV6f72K9PP6YkqkO46/d9aTLWtWAofRJxx70/RVg==",
"fileName": "my-custom-invoice-name.pdf",
"fileExtension": "pdf",
"fileSize": 99288,
"filecontentB64": "JVBERi0xLjcK...",
"zugferdIsValid": true,
"zugferdErrors": []
}Antwortfelder
| Field | Type | Description |
|---|---|---|
message | string | Statustext: `pdf created, downloaded and stored in DMS`, wenn `invoicePassthrough` auf `false` steht, sonst `pdf created, downloaded and not stored in DMS`. |
iqDataId | integer | ID des Eintrags, der in der Rechnungsliste Ihres Kontos angelegt wurde. `0` bei einer Idempotency-Key-Wiederholung. |
downloadURL | string (url) | Link zum erzeugten PDF (`Content-Type: application/pdf`). Er lässt sich ohne Authorization-Header öffnen — jeder, der den Link kennt, kann die Datei herunterladen. Behandeln Sie ihn wie ein Geheimnis. |
resendToken | string | Leerer String `""`, wenn keine E-Mail versendet wurde. Wurde `transport` bei einem gültigen Dokument genutzt, der Token für `sendEmailWithZugferdData` — siehe E-Mail-Versand. Bei einer Idempotency-Key-Wiederholung nicht vorhanden. |
fileName | string | Dateiname des PDFs — Ihr `invoiceFilename`, falls Sie einen mitgeschickt haben. Ohne Angabe erzeugt die API einen Namen, der nicht zum Lesen gedacht ist: Er enthält ein unleserliches Suffix und endet derzeit auf `.pdf.pdf`. Setzen Sie `invoiceFilename`, wenn der Name wichtig ist, z. B. für E-Mail-Anhänge. |
fileExtension | string | Dateiendung, `pdf`. |
fileSize | integer | Größe des PDFs in Bytes. |
filecontentB64 | string (base64) | Das erzeugte ZUGFeRD-PDF, Base64-kodiert. Das ist das Dokument selbst; `downloadURL` verweist auf dieselbe Datei. |
zugferdIsValid | boolean | `true`, wenn die im PDF eingebetteten ZUGFeRD-Daten die Validierung bestanden haben. |
zugferdErrors | array | Validierungsbefunde zum zurückgegebenen Dokument, in derselben Form wie `errorList` in der 412-Antwort; leer, wenn `zugferdIsValid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
zugferdErrors[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
zugferdErrors[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
zugferdErrors[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrors[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrors[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
zugferdErrors[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
Beispielantwort
{
"message": "returned because of same itempotency-key",
"iqDataId": 0,
"documentId": 0,
"fsNodeId": 0,
"fileName": "my-custom-invoice-name.pdf",
"fileExtension": "pdf",
"fileSize": 99288,
"filecontentB64": "JVBERi0xLjcK...",
"downloadURL": "https://api.rechnungsapi.de/file/get/1793363429_Qx7LmN2pVd9RtKs4WbHy8CfJe1ZaGu3o",
"zugferdIsValid": true,
"zugferdErrors": []
}Playground
Diesen Endpunkt live im Browser testen.
E-Mail-Versand
/api/v1/deliveryEigenständigen E-Mail-Versand auslösen
Versendet eine E-Mail an die angegebenen Empfänger — unabhängig von der Erzeugung eines Rechnungsdokuments über einen create...-Endpunkt. Nutzt ein erweitertes transport-Objekt im Vergleich zu den create...-Endpunkten (Felder verschachtelt unter transport.email, plus ein freies content-Objekt für Platzhalter), unter denselben Bedingungen (gebuchter Service, Template-Ersetzungen, Aussehen des Mailbody).
| Field | Type | Required | Description |
|---|---|---|---|
transport.type | string | required | Versandkanal. Derzeit nur "email". |
transport.useTransport | boolean | required | Muss auf true gesetzt sein, damit tatsächlich eine E-Mail versendet wird (siehe Response-Fall „nothing to do" unten). |
transport.email.sender / senderName | string | required | Absender-E-Mail-Adresse und optionaler Anzeigename. |
transport.email.receiver / cc / bcc | string | required | Empfänger; bei mehreren Adressen kommagetrennt. |
transport.email.subject / message | string | required | Betreff und Inhalt (Text oder vollständiges HTML). Beide unterstützen Platzhalter aus content unten — anders als bei den create...-Endpunkten gibt es hier kein invoice-Objekt zur automatischen Befüllung von {invoicenumber}/{invoicedate}/{lastname}, die Werte müssen explizit angegeben werden. |
transport.email.content | object | optional | Freie Schlüssel-Wert-Paare zur Befüllung von Platzhaltern in subject/message – z. B. füllt ein Schlüssel "invoicedate" den Platzhalter {invoicedate}. Es können beliebige eigene Schlüssel/Platzhalter-Namen verwendet werden. |
transport.email.attachments | array | optional | Anhänge als { fileName, fileBase64 }-Objekte. Mehrere Anhänge möglich — anders als bei den create...-Endpunkten gibt es hier kein automatisch generiertes Dokument, das mit angehängt wird. |
Beispiel
{
"transport": {
"type": "email",
"useTransport": true,
"email": {
"sender": "support@rechnungsapi.de",
"senderName": "rechnungsAPI",
"receiver": "empfaenger@domain.de",
"cc": "cc1@domain.de, cc2@domain.de",
"bcc": "bcc1@domain.de, bcc2@domain.de",
"subject": "testrechnung vom {invoicedate}. Rechnungsnummer: {invoicenumber}",
"message": "Hallo {lastname},\nIhre Rechnung {invoicenumber} vom {invoicedate} befindet sich im Anhang.",
"content": {
"invoicedate": "02.09.2026",
"invoicenumber": "RE-2024-001",
"lastname": "Mustermann"
},
"attachments": [
{
"fileBase64": "<BASE64>",
"fileName": "file1.pdf"
}
]
}
}
}Beispielantwort
{
"message": "email sent",
"resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf"
}Beispielantwort
{
"message": "nothing to do. Send option not set to send."
}Playground
Diesen Endpunkt live im Browser testen.
/api/v1/sendEmailWithZugferdDataE-Mail erneut versenden
Versendet die E-Mail mit dem zuvor erzeugten Dokument erneut, ohne das Dokument neu zu generieren. Wird zusammen mit dem resendToken verwendet, den createXinvoiceFromJson, createZugferdFromJson, createInvoicePdfFromJson oder delivery in ihrer Response zurückgeben — vorausgesetzt, die Transport-Option wurde genutzt und es wurde ein gültiges Dokument erzeugt.
| Field | Type | Required | Description |
|---|---|---|---|
resendToken | string | required | Der resendToken aus der Response eines der create...-Endpunkte, oder von delivery. |
Beispiel
{
"resendToken": "<RESENDTOKEN>"
}Beispielantwort
{
"message": "resend"
}Playground
Diesen Endpunkt live im Browser testen.
Extraktion
/api/v1/zugferd/extractXinvoiceFromZugferdToJsonXRechnung aus ZUGFeRD als JSON extrahieren
Extrahiert die eingebettete XRechnungs-XML aus einem ZUGFeRD-PDF und gibt sie als strukturiertes JSON-Objekt für die Weiterverarbeitung zurück.
| Field | Type | Required | Description |
|---|---|---|---|
zugferd64 | string (base64) | required | Das ZUGFeRD-PDF-Dokument als Base64-kodierter String. |
Beispiel
{
"zugferd64": "JVBERi0xLjcKJbe3wvUKMyAwIG9iago8PC9UeXBl..."
}Beispielantwort
{
"extractedInvoice": {
"invoiceNumber": "RE-2025-001",
"invoiceIssueDate": "2026-02-16T00:00:00+01:00",
"invoiceTypeCode": "380",
"invoiceCurrencyCode": "EUR",
"vatAccountingCurrencyCode": null,
"valueAddedTaxPointDate": null,
"valueAddedTaxPointDateCode": "",
"paymentDueDate": "2026-03-02T00:00:00+01:00",
"buyerReference": "BEST-2025-042",
"projectReference": {
"projectReferenceIdentifier": "",
"projectReferenceName": ""
},
"contractReference": "",
"purchaseOrderReference": "",
"salesOrderReference": "",
"receivingAdviceReference": "",
"despatchAdviceReference": "",
"tenderOrLotReference": null,
"invoicedObjectIdentifier": null,
"buyerAccountingReference": "Sachkonto 12000",
"paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
"invoiceNote": [],
"processControl": {
"businessProcessTypeIdentifier": "",
"specificationIdentifier": ""
},
"precedingInvoiceReference": [],
"seller": {
"sellerName": "Ihre Firma GmbH",
"sellerTradingName": "",
"sellerIdentifier": [],
"sellerLegalRegistrationIdentifier": "HRB 67890 B",
"sellerVatIdentifier": "DE123456789",
"sellerTaxRegistrationIdentifier": "12/345/67890",
"sellerAdditionalLegalInformation": "",
"sellerElectronicAddress": "info@ihre-firma.de",
"sellerPostalAddress": {
"sellerAddressLine1": "Musterstraße 1",
"sellerAddressLine2": "",
"sellerAddressLine3": "",
"sellerCity": "Berlin",
"sellerPostCode": "12345",
"sellerCountrySubdivision": "",
"sellerCountryCode": "DE"
},
"sellerContact": {
"sellerContactPoint": "Vertrieb",
"sellerContactTelephoneNumber": "+49 30 9876543",
"sellerContactEmailAddress": "info@ihre-firma.de"
}
},
"buyer": {
"buyerName": "Müller und Mayer GmbH",
"buyerTradingName": "",
"buyerIdentifier": "",
"buyerLegalRegistrationIdentifier": "HRB 12345",
"buyerVatIdentifier": "DE987654321",
"buyerElectronicAddress": "rechnung@mueller-mayer.de",
"buyerPostalAddress": {
"buyerAddressLine1": "Kundenstraße 42",
"buyerAddressLine2": "",
"buyerAddressLine3": "",
"buyerCity": "Berlin",
"buyerPostCode": "10115",
"buyerCountrySubdivision": "",
"buyerCountryCode": "DE"
},
"buyerContact": {
"buyerContactPoint": "",
"buyerContactTelephoneNumber": "+49 30 12345678",
"buyerContactEmailAddress": "rechnung@mueller-mayer.de"
}
},
"payee": {
"payeeName": "",
"payeeIdentifier": "",
"payeeLegalRegistrationIdentifier": ""
},
"sellerTaxRepresentativeParty": {
"sellerTaxRepresentativeName": "",
"sellerTaxRepresentativeVatIdentifier": "",
"sellerTaxRepresentativePostalAddress": {
"taxRepresentativeAddressLine1": "",
"taxRepresentativeAddressLine2": "",
"taxRepresentativeAddressLine3": "",
"taxRepresentativeCity": "",
"taxRepresentativePostCode": "",
"taxRepresentativeCountrySubdivision": "",
"taxRepresentativeCountryCode": ""
}
},
"deliveryInformation": {
"deliverToPartyName": "",
"deliverToLocationIdentifier": null,
"actualDeliveryDate": null,
"deliverToAddress": {
"deliverToAddressLine1": "",
"deliverToAddressLine2": "",
"deliverToAddressLine3": "",
"deliverToCity": "",
"deliverToPostCode": "",
"deliverToCountrySubdivision": null,
"deliverToCountryCode": ""
}
},
"invoicingPeriod": {
"invoicingPeriodStartDate": null,
"invoicingPeriodEndDate": null
},
"paymentInstructions": {
"paymentMeansTypeCode": "58",
"paymentMeansText": "SEPA-Überweisung",
"remittanceInformation": "RE-2025-001",
"creditTransfer": [
{
"paymentAccountIdentifier": "DE89370400440532013000",
"paymentAccountName": "Ihre Firma GmbH",
"paymentServiceProviderIdentifier": "COBADEFFXXX"
}
],
"paymentCardInformation": {
"paymentCardPrimaryAccountNumber": "",
"paymentCardHolderName": ""
},
"directDebit": {
"mandateReferenceIdentifier": "",
"bankAssignedCreditorIdentifier": "",
"debitedAccountIdentifier": ""
}
},
"documentLevelAllowances": [],
"documentLevelCharges": [],
"documentTotals": {
"sumOfInvoiceLineNetAmount": 1799,
"sumOfAllowancesOnDocumentLevel": 0,
"sumOfChargesOnDocumentLevel": 0,
"invoiceTotalAmountWithoutVat": 1799,
"invoiceTotalVatAmount": 341.81,
"invoiceTotalVatAmountInAccountingCurrency": 0,
"invoiceTotalAmountWithVat": 2140.81,
"paidAmount": 0,
"roundingAmount": 0,
"amountDueForPayment": 2140.81
},
"vatBreakdown": [
{
"vatCategoryTaxableAmount": 1799,
"vatCategoryTaxAmount": 341.81,
"vatCategoryCode": "S",
"vatCategoryRate": 19,
"vatExemptionReasonText": "",
"vatExemptionReasonCode": ""
}
],
"additionalSupportingDocuments": [],
"invoiceLine": [
{
"invoiceLineIdentifier": "1",
"invoiceLineNote": "",
"invoiceLineObjectIdentifier": "",
"invoicedQuantity": 10,
"invoicedQuantityUnitOfMeasureCode": "HUR",
"invoiceLineNetAmount": 1200,
"referencedPurchaseOrderLineReference": "",
"invoiceLineBuyerAccountingReference": "",
"invoiceLinePeriod": {
"invoiceLinePeriodStartDate": null,
"invoiceLinePeriodEndDate": null
},
"invoiceLineAllowances": [],
"invoiceLineCharges": [],
"priceDetails": {
"itemNetPrice": 120,
"itemPriceDiscount": 0,
"itemGrossPrice": 120,
"itemPriceBaseQuantity": 1,
"itemPriceBaseQuantityUnitOfMeasure": "HUR"
},
"lineVatInformation": [
{
"invoicedItemVatCategoryCode": "S",
"invoicedItemVatRate": 19
}
],
"itemInformation": {
"itemName": "Beratung & Projektbegleitung",
"itemDescription": "",
"itemSellersIdentifier": "",
"itemBuyersIdentifier": "",
"itemStandardIdentifier": "",
"itemStandardIdentifierSchemeIdentifier": "",
"itemClassificationIdentifier": [],
"itemCountryOfOrigin": "",
"itemAttributes": [
{
"itemAttributeName": null,
"itemAttributeValue": null
}
]
}
}
]
},
"zugferdIsValid": true,
"zugferdErrorlist": []
}Antwortfelder
| Field | Type | Description |
|---|---|---|
extractedInvoice | object | null | Die eingebettete Rechnung als vollständiges Rechnungsobjekt (siehe unten). Jedes Feld ist vorhanden — nicht gesetzte Werte sind `""` oder `null`, nicht gesetzte Listen `[]`; Datumswerte sind ISO-8601-Zeitstempel mit UTC-Offset (z. B. `2026-02-16T00:00:00+01:00`). `null`, wenn das PDF kein lesbares XML enthält. |
zugferdIsValid | boolean | `true`, wenn das eingebettete XML die Validierung bestanden hat. `false` kommt mit HTTP 400 (siehe unten). |
zugferdErrorlist | array | Validierungsbefunde des eingebetteten XML; leer, wenn `zugferdIsValid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
zugferdErrorlist[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
zugferdErrorlist[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
zugferdErrorlist[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrorlist[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrorlist[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
zugferdErrorlist[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
Playground
Diesen Endpunkt live im Browser testen.
Validierung
/api/v1/zugferd/validateXinvoiceXmlXRechnung-XML validieren
Validiert XRechnungs-XML (CII- oder UBL-Syntax) gegen EN 16931 und XRechnung-Business-Regeln. Gibt strukturierte Fehler mit Regel-IDs und Positionen zurück, damit Verstöße vor dem Versand behoben werden können. Besteht ein Dokument diese Regeln, laufen zusätzliche Prüfungen (USt-IdNr. des Verkäufers, Fälligkeitsdatum), und die Antwort weist zusätzlich getrennt aus, ob die IBAN in der Rechnung gültig ist (`isIbanValidInXML`). Welche dieser Felder zurückkommen, hängt davon ab, wie weit die Validierung kam — siehe die Beispielantworten.
| Field | Type | Required | Description |
|---|---|---|---|
xinvoiceXML | string | required | XRechnungs-XML-Inhalt als String. |
Beispiel
{
"xinvoiceXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
}Beispielantwort
{
"message": "validated. (4649)",
"isIbanValidInXML": true,
"valid": true,
"xInvoiceErrors": []
}Antwortfelder
| Field | Type | Description |
|---|---|---|
message | string | `validated. (<n>)`, wenn das Dokument die Schema- und Schematron-Regeln bestanden hat und damit auch die zusätzlichen Prüfungen liefen; `<n>` ist die Länge des übermittelten XML in Zeichen. Andernfalls `validation done` — siehe die Beispiele unten. |
valid | boolean | `true`, wenn `xInvoiceErrors` keine Befunde enthält, sonst `false`. |
isIbanValidInXML | boolean | `true`, wenn die IBAN in der Rechnung gültig ist; `false`, wenn sie ungültig ist oder das Dokument keine IBAN enthält. Wird unabhängig von `valid` ausgewiesen. Eine gültige IBAN bedeutet hier nur, dass Format und Prüfziffern stimmen – nicht, dass das Konto existiert oder wem es gehört. Nur vorhanden, wenn das Dokument die Schema- und Schematron-Regeln bestanden hat (`message: validated. (<n>)`). |
xInvoiceErrors | array | Alle Befunde; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
xInvoiceErrors[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
xInvoiceErrors[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
xInvoiceErrors[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
xInvoiceErrors[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
xInvoiceErrors[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
xInvoiceErrors[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
Beispielantwort
{
"message": "validated. (4544)",
"isIbanValidInXML": true,
"valid": false,
"xInvoiceErrors": [
{
"message": "Verkäufer Vat ID ist ungültig",
"schemaFile": "additional-validation",
"type": "fatal",
"location": "sellerVatId",
"id": "",
"line": ""
},
{
"message": "Fälligkeitsdatum oder Zahlungsbedingungen nicht vorhanden.",
"schemaFile": "additional-validation",
"type": "fatal",
"location": "dueDate",
"id": "",
"line": ""
}
]
}Beispielantwort
{
"message": "validation done",
"xmllength": 4413,
"valid": false,
"xInvoiceErrors": [
{
"message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal",
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
"id": "BR-CO-25",
"line": null
}
]
}Antwortfelder
| Field | Type | Description |
|---|---|---|
xmllength | integer | Länge des übermittelten XML in Zeichen. Nur zusammen mit `message: validation done` vorhanden, sowie in der 412-Antwort. |
Beispielantwort
{
"message": "validation done",
"xmllength": 7,
"valid": false,
"xInvoiceErrors": [
{
"message": "The attached XML content is either corrupt or not parsable.",
"schemaFile": null,
"type": "fatal",
"location": null,
"id": null,
"line": null
}
]
}Playground
Diesen Endpunkt live im Browser testen.
/api/v1/zugferd/validateZugferdPdfZUGFeRD-PDF validieren
Validiert ein bestehendes ZUGFeRD-PDF inkl. eingebettetem XML gegen EN 16931. Liefert ein klares Bestanden/Nicht-bestanden mit einer detaillierten Fehlerliste. Die Antwort weist zusätzlich getrennt aus, ob die IBAN in der Rechnung gültig ist (`isIbanValidInZugferd`).
| Field | Type | Required | Description |
|---|---|---|---|
zugferdFile64 | string (base64) | required | Base64-kodiertes ZUGFeRD-PDF. |
comparePDF2XML | boolean | optional | Wenn true, wird zusätzlich geprüft, ob der sichtbare PDF-Inhalt mit den eingebetteten XML-Rechnungsdaten übereinstimmt. Standard: false. |
Beispiel
{
"zugferdFile64": "JVBERi0xLjQK...",
"comparePDF2XML": true
}Beispielantwort
{
"valid": false,
"message": "File was validated",
"isIbanValidInZugferd": true,
"numberOfZugferdErrors": 10,
"zugferdErrors": [
{
"id": "BR-CO-25",
"line": null,
"location": "/rsm:CrossIndustryInvoice",
"message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal"
}
]
}Antwortfelder
| Field | Type | Description |
|---|---|---|
message | string | `File was validated`, sobald die Validierung lief. Andere Texte gibt es nur in den Sonderfällen unten. |
valid | boolean | `true`, wenn das eingebettete XML keine Befunde in `zugferdErrors` hat, sonst `false`. |
isIbanValidInZugferd | boolean | `true`, wenn die IBAN in der Rechnung gültig ist; `false`, wenn sie ungültig ist. Wird unabhängig von `valid` ausgewiesen: Ein ZUGFeRD-PDF mit ungültiger IBAN kann trotzdem `valid: true` liefern. Eine gültige IBAN bedeutet hier nur, dass Format und Prüfziffern stimmen – nicht, dass das Konto existiert oder wem es gehört. Wird nicht zurückgegeben, wenn `message` `cannot extract data to validate` lautet. |
numberOfZugferdErrors | integer | Anzahl der Befunde im eingebetteten XML. `zugferdErrors` listet sie auf (das Beispiel oben zeigt nur einen der zehn). |
zugferdErrors | array | Alle Befunde; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften. |
zugferdErrors[].message | string | Text der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`. |
zugferdErrors[].id | string | null | Regel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben. |
zugferdErrors[].location | string | null | Fundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrors[].schemaFile | string | null | Regelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte. |
zugferdErrors[].type | string | Art des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen. |
zugferdErrors[].line | null | string | Zeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`. |
Beispielantwort
{
"message": "File was validated",
"valid": true,
"isIbanValidInZugferd": true,
"numberOfZugferdErrors": 0,
"zugferdErrors": []
}Beispielantwort
{
"message": "cannot extract data to validate",
"valid": false,
"numberOfZugferdErrors": 0,
"zugferdErrors": []
}Playground
Diesen Endpunkt live im Browser testen.
Rechnungsobjekt – Referenz
Das Rechnungsobjekt folgt dem europäischen Semantik-Standard EN 16931. Jedes Feld ist einem Business Term (BT-*) oder einer Business Group (BG-*) zugeordnet. Die folgenden Tabellen zeigen, welche Felder Pflicht und welche optional sind – gruppiert nach ihrer Rolle in der Rechnung.
Wie diese Tabellen zu lesen sind
- Pflichtfelder müssen vorhanden sein, damit die Rechnung gegen EN 16931 valide ist.
- Mit „Min. 1 Pflicht“ markierte Arrays müssen mindestens einen Eintrag enthalten (z. B. Rechnungspositionen, USt-Aufschlüsselung).
- Verschachtelte Felder werden mit Punktnotation dargestellt (z. B. sellerPostalAddress.sellerCity).
Pflichtfelder auf einen Blick
Dies sind die Mindest-Pflichtfelder für eine valide EN-16931-Rechnung. Alles Übrige in den Tabellen unten ist optional und kann weggelassen werden.
- BT-1
invoiceNumber - BT-2
invoiceIssueDate - BT-3
invoiceTypeCode - BT-5
invoiceCurrencyCode - BT-10
buyerReference
- BT-27
sellerName - BT-31
sellerVatIdentifier - BT-34
sellerElectronicAddress - BT-37
sellerPostalAddress.sellerCity - BT-38
sellerPostalAddress.sellerPostCode - BT-40
sellerPostalAddress.sellerCountryCode
- BT-44
buyerName - BT-49
buyerElectronicAddress - BT-52
buyerPostalAddress.buyerCity - BT-53
buyerPostalAddress.buyerPostCode - BT-55
buyerPostalAddress.buyerCountryCode
- BT-81
paymentMeansTypeCode
- BT-106
sumOfInvoiceLineNetAmount - BT-109
invoiceTotalAmountWithoutVat - BT-110
invoiceTotalVatAmount - BT-112
invoiceTotalAmountWithVat - BT-115
amountDueForPayment
- BT-116
vatCategoryTaxableAmount - BT-117
vatCategoryTaxAmount - BT-118
vatCategoryCode - BT-119
vatCategoryRate
- BT-126
invoiceLineIdentifier - BT-129
invoicedQuantity - BT-130
invoicedQuantityUnitOfMeasureCode - BT-131
invoiceLineNetAmount - BT-146
priceDetails.itemNetPrice - BT-151
lineVatInformation[].invoicedItemVatCategoryCode - BT-152
lineVatInformation[].invoicedItemVatRate - BT-153
itemInformation.itemName
Kopfdaten (BT-1 bis BT-26)
Top-Level-Rechnungsdaten: Nummer, Datumsangaben, Währung und Referenzen. Diese Felder identifizieren das Dokument und seinen Geschäftskontext.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-1 | invoiceNumber | string | required | Eindeutige Rechnungsnummer des Verkäufers. |
| BT-2 | invoiceIssueDate | date | required | Ausstellungsdatum der Rechnung. Format JJJJMMTT oder JJJJ-MM-TT. |
| BT-3 | invoiceTypeCode | string | required | Rechnungsart: 380 = Rechnung, 381 = Gutschrift, 384 = Korrekturrechnung. |
| BT-5 | invoiceCurrencyCode | string | required | ISO-4217-Währungscode der Rechnung (z. B. EUR). |
| BT-6 | vatAccountingCurrencyCode | string | optional | Währung für die USt-Buchhaltung, falls abweichend von der Rechnungswährung. |
| BT-7 | valueAddedTaxPointDate | date | optional | USt-Stichtag – Datum, an dem die USt fällig wird. |
| BT-8 | valueAddedTaxPointDateCode | string | optional | Code, der angibt, welches Datum den USt-Stichtag bestimmt. |
| BT-9 | paymentDueDate | date | optional | Fälligkeitsdatum der Zahlung. Pflicht, sofern ein offener Betrag und kein Zahlungsbedingungstext vorhanden ist. |
| BT-10 | buyerReference | string | required | Käuferreferenz (Leitweg-ID bei der öffentlichen Verwaltung, sonst eine mit dem Käufer vereinbarte Referenz). |
| BT-11 | projectReference | object | optional | Optionale Projektreferenz (Kennung + Name). |
| BT-12 | contractReference | string | optional | Kennung des zugrunde liegenden Vertrags. |
| BT-13 | purchaseOrderReference | string | optional | Bestellreferenz des Käufers. |
| BT-14 | salesOrderReference | string | optional | Auftragsreferenz des Verkäufers. |
| BT-17 | tenderOrLotReference | string | optional | Ausschreibungs- oder Losreferenz. |
| BT-19 | buyerAccountingReference | string | optional | Buchhaltungsreferenz des Käufers. |
| BT-20 | paymentTerms | string | optional | Zahlungsbedingungen als Freitext. Pflicht, wenn BT-9 fehlt. |
| BT-21/22 | invoiceNote | array | optional | Freitext-Hinweise zur Rechnung, jeweils mit optionalem Themencode. |
| BT-23/24 | processControl | object | optional | Geschäftsprozess- und Spezifikations-Identifikatoren. |
| BT-25/26 | precedingInvoiceReference | array | optional | Referenz auf eine vorhergehende Rechnung (für Korrekturen / Gutschriften). |
Verkäufer (BG-4, BT-27 bis BT-43)
Identifikations- und Kontaktdaten des Rechnungsstellers.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-27 | sellerName | string | required | Eingetragener Firmenname des Verkäufers. |
| BT-28 | sellerTradingName | string | optional | Geschäftsname, falls vom Firmennamen abweichend. |
| BT-29 | sellerIdentifier | string[] | optional | Zusätzliche Verkäufer-Identifikatoren (z. B. GLN). |
| BT-30 | sellerLegalRegistrationIdentifier | string | optional | Handelsregisternummer. |
| BT-31 | sellerVatIdentifier | string | required | Umsatzsteuer-Identifikationsnummer des Verkäufers. |
| BT-32 | sellerTaxRegistrationIdentifier | string | optional | Steuernummer. |
| BT-33 | sellerAdditionalLegalInformation | string | optional | Weitere Rechtsangaben (Geschäftsführer, Registergericht usw.). |
| BT-34 | sellerElectronicAddress | string | required | Elektronische Adresse des Verkäufers (i. d. R. Postfach für E-Rechnungen oder E-Mail). |
| BT-35 | sellerPostalAddress.sellerAddressLine1 | string | optional | Straße und Hausnummer (Zeile 1). |
| BT-37 | sellerPostalAddress.sellerCity | string | required | Ort. |
| BT-38 | sellerPostalAddress.sellerPostCode | string | required | Postleitzahl. |
| BT-40 | sellerPostalAddress.sellerCountryCode | string | required | ISO-3166-1 alpha-2 Ländercode (z. B. DE). |
| BT-41/42/43 | sellerContact | object | optional | Ansprechpartner: Name, Telefon, E-Mail. |
Käufer (BG-7, BT-44 bis BT-58)
Identifikations- und Kontaktdaten des Rechnungsempfängers.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-44 | buyerName | string | required | Eingetragener Firmenname des Käufers. |
| BT-45 | buyerTradingName | string | optional | Geschäftsname, falls vom Firmennamen abweichend. |
| BT-46 | buyerIdentifier | string | optional | Zusätzlicher Käufer-Identifikator. |
| BT-47 | buyerLegalRegistrationIdentifier | string | optional | Handelsregisternummer des Käufers. |
| BT-48 | buyerVatIdentifier | string | optional | Umsatzsteuer-Identifikationsnummer des Käufers. |
| BT-49 | buyerElectronicAddress | string | required | Elektronische Adresse des Käufers. |
| BT-50 | buyerPostalAddress.buyerAddressLine1 | string | optional | Straße und Hausnummer (Zeile 1). |
| BT-52 | buyerPostalAddress.buyerCity | string | required | Ort. |
| BT-53 | buyerPostalAddress.buyerPostCode | string | required | Postleitzahl. |
| BT-55 | buyerPostalAddress.buyerCountryCode | string | required | ISO-3166-1 alpha-2 Ländercode. |
| BT-56/57/58 | buyerContact | object | optional | Ansprechpartner: Name, Telefon, E-Mail. |
Zahlungsanweisungen (BG-16, BT-81 bis BT-91)
Wie der Käufer zahlen soll. Verwenden Sie je nach Zahlungsart-Code entweder Überweisung, Karte oder Lastschrift.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-81 | paymentMeansTypeCode | string | required | UNTDID 4461 Zahlungsmittelcode (z. B. 58 = SEPA-Überweisung, 30 = Überweisung, 48 = Kreditkarte). |
| BT-82 | paymentMeansText | string | optional | Freitext-Zahlungsanweisungen. |
| BT-83 | remittanceInformation | string | optional | Verwendungszweck (vom Käufer bei Zahlung anzugeben). |
| BT-84 | creditTransfer[].paymentAccountIdentifier | string | optional | IBAN oder Kontonummer für die Zahlung. |
| BT-85 | creditTransfer[].paymentAccountName | string | optional | Kontoinhaber. |
| BT-86 | creditTransfer[].paymentServiceProviderIdentifier | string | optional | BIC der Empfängerbank. |
| BT-87/88 | paymentCardInformation | object | optional | Kartenzahlungsinformationen (PAN, Karteninhaber). |
| BT-89/90/91 | directDebit | object | optional | Lastschriftmandat-Informationen. |
Rechnungsbeträge (BG-22, BT-106 bis BT-115)
Beträge auf Dokumentenebene. Diese müssen mit der Summe der Positionen und der USt-Aufschlüsselung übereinstimmen.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-106 | sumOfInvoiceLineNetAmount | decimal | required | Summe der Nettobeträge aller Rechnungspositionen. |
| BT-107 | sumOfAllowancesOnDocumentLevel | decimal | optional | Summe der Nachlässe auf Dokumentenebene. |
| BT-108 | sumOfChargesOnDocumentLevel | decimal | optional | Summe der Zuschläge auf Dokumentenebene. |
| BT-109 | invoiceTotalAmountWithoutVat | decimal | required | Rechnungs-Gesamtbetrag ohne USt (Nettosumme). |
| BT-110 | invoiceTotalVatAmount | decimal | required | Gesamter USt-Betrag. |
| BT-111 | invoiceTotalVatAmountInAccountingCurrency | decimal | optional | Gesamt-USt in der Buchhaltungswährung (BT-6), falls von BT-5 abweichend. |
| BT-112 | invoiceTotalAmountWithVat | decimal | required | Rechnungs-Gesamtbetrag inkl. USt (Bruttosumme). |
| BT-113 | paidAmount | decimal | optional | Bereits bezahlter Betrag. |
| BT-114 | roundingAmount | decimal | optional | Rundungsbetrag. |
| BT-115 | amountDueForPayment | decimal | required | Zu zahlender Betrag (BT-112 − BT-113 + BT-114). |
USt-Aufschlüsselung (BG-23, BT-116 bis BT-121)
Array · Min. 1 PflichtArray mit USt-Zwischensummen. Mindestens ein Eintrag ist Pflicht, mit einer Zeile pro Kombination aus USt-Kategorie und -Satz.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-116 | vatCategoryTaxableAmount | decimal | required | Steuerbarer Betrag für diese USt-Kategorie. |
| BT-117 | vatCategoryTaxAmount | decimal | required | USt-Betrag für diese Kategorie (BT-116 × BT-119 / 100). |
| BT-118 | vatCategoryCode | string | required | USt-Kategorie: S (Standard), Z (Nullsatz), E (Befreit), AE (Umkehr der Steuerschuld), K (Innergemeinschaftlich), G (Ausfuhr), O (Außerhalb), L (Kanarische Inseln), M (Ceuta/Melilla). |
| BT-119 | vatCategoryRate | decimal | required | USt-Satz in Prozent (z. B. 19 für 19 %). |
| BT-120 | vatExemptionReasonText | string | optional | Pflicht bei Steuerbefreiung oder Nullsatz. Freitext-Begründung. |
| BT-121 | vatExemptionReasonCode | string | optional | Kodierte Befreiungsgründe (z. B. VATEX-EU-AE, VATEX-EU-IC). |
Rechnungspositionen (BG-25, BT-126 bis BT-161)
Array · Min. 1 PflichtArray der Rechnungspositionen. Jede Position beschreibt ein Produkt oder eine Leistung und muss Identifikation, Menge, Nettopreis, Positions-Nettobetrag und USt-Zuordnung enthalten.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BT-126 | invoiceLineIdentifier | string | required | Eindeutige Positionsnummer innerhalb der Rechnung. |
| BT-127 | invoiceLineNote | string | optional | Freitext-Hinweis zur Position. |
| BT-128 | invoiceLineObjectIdentifier | string | optional | Objektkennung, auf die die Position verweist. |
| BT-129 | invoicedQuantity | decimal | required | In Rechnung gestellte Menge. |
| BT-130 | invoicedQuantityUnitOfMeasureCode | string | required | UN/ECE Empfehlung 20 Maßeinheit (z. B. H87 = Stück, HUR = Stunde, KGM = Kilogramm). |
| BT-131 | invoiceLineNetAmount | decimal | required | Positions-Nettobetrag (Menge × Nettopreis − Positionsnachlässe + Positionszuschläge). |
| BT-132 | referencedPurchaseOrderLineReference | string | optional | Referenz auf eine Bestellposition des Käufers. |
| BT-133 | invoiceLineBuyerAccountingReference | string | optional | Buchungsreferenz für diese Position. |
| BT-134/135 | invoiceLinePeriod | object | optional | Leistungszeitraum dieser Position (Start/Ende). |
| BT-136 to BT-140 | invoiceLineAllowances | array | optional | Nachlässe/Rabatte auf Positionsebene. |
| BT-141 to BT-145 | invoiceLineCharges | array | optional | Zuschläge auf Positionsebene. |
| BT-146 | priceDetails.itemNetPrice | decimal | required | Netto-Stückpreis (nach Artikel-Preisrabatt). |
| BT-147 | priceDetails.itemPriceDiscount | decimal | optional | Rabatt auf den Brutto-Stückpreis zur Ermittlung des Nettopreises. |
| BT-148 | priceDetails.itemGrossPrice | decimal | optional | Brutto-Stückpreis vor Rabatt. |
| BT-149 | priceDetails.itemPriceBaseQuantity | decimal | optional | Bezugsmenge des Stückpreises (die Menge, auf die sich der Preis bezieht, z. B. 100, wenn der Preis je 100 Stück gilt). |
| BT-150 | priceDetails.itemPriceBaseQuantityUnitOfMeasure | string | optional | Maßeinheit der Bezugsmenge (UN/ECE-Empfehlung-20-Code, z. B. H87, HUR). |
| BT-151 | lineVatInformation[].invoicedItemVatCategoryCode | string | required | USt-Kategorie der Position (passt zu einem Eintrag in vatBreakdown). |
| BT-152 | lineVatInformation[].invoicedItemVatRate | decimal | required | USt-Satz der Position. |
| BT-153 | itemInformation.itemName | string | required | Artikelbezeichnung auf der Rechnung. |
| BT-154 | itemInformation.itemDescription | string | optional | Ausführliche Artikelbeschreibung. |
| BT-155 | itemInformation.itemSellersIdentifier | string | optional | Artikelnummer des Verkäufers. |
| BT-156 | itemInformation.itemBuyersIdentifier | string | optional | Artikelnummer des Käufers. |
| BT-157 | itemInformation.itemStandardIdentifier | string | optional | Standardartikelkennung (z. B. GTIN). Pflicht, wenn BT-157-1 gesetzt ist. |
| BT-157-1 | itemInformation.itemStandardIdentifierSchemeIdentifier | string | optional | ISO-6523-Schema für BT-157. Pflicht, wenn BT-157 gesetzt ist. |
| BT-158 | itemInformation.itemClassificationIdentifier | array | optional | Artikelklassifizierungen (z. B. UNSPSC, eCl@ss) mit Schema und Version. |
| BT-159 | itemInformation.itemCountryOfOrigin | string | optional | ISO-3166-1 alpha-2 Herkunftsland. |
| BT-160/161 | itemInformation.itemAttributes | array | optional | Artikelmerkmale als Name/Wert-Paare (z. B. Farbe, Größe). |
Optionale Parteien, Zeiträume und Anpassungen auf Dokumentenebene
Diese Gruppen sind komplett optional. Verwenden Sie sie nur wenn relevant – ansonsten weglassen. Die internen Felder folgen denselben EN-16931-Mapping-Konventionen.
| BT | Field | Type | Pflicht | Beschreibung |
|---|---|---|---|---|
| BG-10 / BT-59 to BT-61 | payee | object | optional | Zahlungsempfänger, falls vom Verkäufer abweichend. |
| BG-11 / BT-62 to BT-69 | sellerTaxRepresentativeParty | object | optional | Steuervertreter des Verkäufers (üblicherweise für Verkäufer außerhalb der EU). |
| BG-13 / BT-70 to BT-80 | deliveryInformation | object | optional | Lieferpartei, Ort und tatsächliches Lieferdatum. |
| BG-14 / BT-73, BT-74 | invoicingPeriod | object | optional | Leistungszeitraum auf Rechnungsebene. |
| BG-20 / BT-92 to BT-98 | documentLevelAllowances | array | optional | Nachlässe/Rabatte auf Dokumentenebene. |
| BG-21 / BT-99 to BT-105 | documentLevelCharges | array | optional | Zuschläge auf Dokumentenebene. |
| BG-24 / BT-122 to BT-125 | additionalSupportingDocuments | array | optional | Zusätzliche Belege (Stundennachweis, Lieferschein usw.). Entweder externe URL oder Base64-Anhang. Jeder Eintrag: supportingDocumentReference (BT-122), supportingDocumentDescription (BT-123), externalDocumentLocation (BT-124, URL), attachedDocument (BT-125, Base64), attachedDocumentFilename (Dateiname des Anhangs) und supportingDocumentTypeCodex (Ganzzahl, UNTDID-1001-Dokumenttypcode, z. B. 916 = referenziertes Dokument, 130 = Rechnungsdatenblatt). |
E-Mail-Versand (transport)
Erzeugen und versenden in einem Aufruf: Die Erzeugungs-Endpunkte createXinvoiceFromJson, createZugferdFromJson und createInvoicePdfFromJson akzeptieren ein optionales transport-Objekt. Ist es vorhanden, wird die erzeugte Rechnung im selben Vorgang per E-Mail zugestellt – DKIM-signiert, an Empfänger, CC und BCC gleichzeitig, ohne eigene Mailinfrastruktur. Ist es nicht vorhanden, verhalten sich die Endpunkte exakt wie bisher; die Funktion ist vollständig abwärtskompatibel. Für bereits erzeugte ZUGFeRD-Daten gibt es den dedizierten Endpunkt sendEmailWithZugferdData.
Voraussetzungen
Der E-Mail-Versand muss für Ihr Konto freigeschaltet und Ihre Absenderdomain einmalig authentifiziert sein. So richten Sie beides ein: E-Mail-Versand einrichten.
Das transport-Objekt
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
type | string | Pflicht | Versandkanal. Derzeit nur "email". |
useTransport | boolean | Pflicht | Auf true setzen, um die erzeugte Rechnung im selben Aufruf zu versenden. |
sender | string | Pflicht | Absenderadresse auf Ihrer eigenen Domain. Die Domain muss einmalig authentifiziert sein (DKIM/SPF) – siehe die oben verlinkte Einrichtungsanleitung. |
senderName | string | optional | Anzeigename des Absenders. |
receiver | string | Pflicht | Empfängeradresse(n), kommasepariert. Wird vor dem Versand bereinigt. |
cc | string | optional | CC-Adresse(n), kommasepariert. |
bcc | string | optional | BCC-Adresse(n), kommasepariert – z. B. Ihr eigenes Archiv-Postfach für eine Kopie jeder versendeten Rechnung. |
subject | string | Pflicht | E-Mail-Betreff. Unterstützt die Platzhalter {invoicenumber} und {invoicedate} – nicht {lastname}, das nur im message-Feld funktioniert. |
message | string | Pflicht | E-Mail-Text als HTML. Unterstützt {invoicenumber} und {invoicedate} wie der Betreff, zusätzlich {lastname} (invoice.buyer.buyerName) – nur hier, nicht im Betreff. |
attachments | array | optional | Zusätzliche Anhänge als { fileName, fileBase64 }-Objekte. PDF, JPG und PNG werden akzeptiert. |
Beispiel-Request
Ein beliebiger Erzeugungs-Request-Body, ergänzt um das transport-Objekt:
{
"invoice": {
"...": "..."
},
"transport": {
"type": "email",
"useTransport": true,
"sender": "rechnung@ihre-domain.de",
"senderName": "Ihre Firma GmbH",
"receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
"cc": "steuerberater@kanzlei.de",
"bcc": "archiv@ihre-domain.de",
"subject": "Rechnung {invoicenumber} vom {invoicedate}",
"message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
"attachments": [
{
"fileName": "Leistungsnachweis.pdf",
"fileBase64": "<base64>"
}
]
}
}Verwandte Endpunkte
Zwei weitere Endpunkte drehen sich um den E-Mail-Versand, unabhängig vom obigen transport-Objekt:
delivery — versendet eigenständig eine E-Mail, unabhängig von der Erzeugung eines Rechnungsdokuments, mit frei wählbaren Anhängen und Platzhalter-Werten.sendEmailWithZugferdData — versendet eine bereits über transport oder delivery verschickte E-Mail anhand ihres resendToken erneut, ohne das Dokument neu zu erzeugen.Fehler
RechnungsAPI verwendet konventionelle HTTP-Status-Codes für Transport-Fehler. Fachliche Validierungsergebnisse (EN-16931- / XRechnung-Regelverstöße) werden mit HTTP 200 in einer strukturierten Fehlerliste zurückgegeben – siehe Schema unten.
| Code | Bezeichnung | Beschreibung |
|---|---|---|
| 200 | OK | Anfrage verarbeitet. Bei Validierungs- und Erzeugungs-Endpunkten zusätzlich das Feld `valid` prüfen – HTTP 200 bedeutet nicht, dass die Rechnung valide ist. |
| 400 | Ungültige Anfrage | Ungültiges JSON oder ungültige Rechnungsdaten. Der Response-Body listet die betroffenen Felder. |
| 401 | Nicht autorisiert | Fehlender oder ungültiger Authorization-Header / Bearer-Token. |
| 402 | Zahlung erforderlich | Kein aktives Abo oder API-Kontingent aufgebraucht. Bitte Support kontaktieren oder Plan upgraden. |
| 412 | Vorbedingung fehlgeschlagen | Erforderliche Eingabe (PDF, XML oder Rechnungsdaten) fehlt im Request-Body, oder der Rechnung fehlen Pflichtangaben. Der Body ist `{ message }`; bei fehlenden Rechnungsdaten enthält er zusätzlich `noOfMissingData` und `errorlist` – siehe Schema unten. |
| 500 | Serverfehler | Unerwarteter serverseitiger Fehler. Mit exponentiellem Backoff erneut versuchen; bei dauerhaftem Fehler Support mit Request-ID kontaktieren. |
Schema eines Validierungsfehlers
Jeder Eintrag in `xInvoiceErrors` / `xInvoiceErrorList` / `zugferdErrors` / `zugferdErrorList` / `zugferdErrorlist` / `xrechnungErrors` / `errorList` folgt diesem Schema — die Schreibweise des Listennamens unterscheidet sich je Endpunkt, die Einträge nicht. Nutzen Sie `id` und `location`, um zur fehlerhaften Stelle zu springen. `line` ist derzeit immer leer.
{
"id": "BR-CO-25",
"line": null,
"location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
"message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
"schemaFile": "EN16931-CII-validation",
"type": "fatal"
}Befunde aus den zusätzlichen Prüfungen des XML-Validators (`schemaFile: additional-validation`) haben keine Regel-ID: `id` und `line` sind leere Strings und `location` ist ein Feldschlüssel statt eines XPath. Lässt sich die Datei gar nicht lesen, sind `schemaFile`, `location`, `id` und `line` `null`.
{
"id": "",
"line": "",
"location": "sellerVatId",
"message": "Verkäufer Vat ID ist ungültig",
"schemaFile": "additional-validation",
"type": "fatal"
}Schema bei fehlenden Daten (412)
Fehlen Pflichtangaben in der Rechnung, antwortet createXinvoiceFromJson mit 412 und benennt jede Lücke als EN-16931-Business-Term. In diesem Fall wird nichts erzeugt.
{
"message": "Data are missing in input.",
"noOfMissingData": 1,
"errorlist": [
{
"businessTerm": "BT-34",
"businessTermDescription": "BT-34 (sellerElectronicAddress)",
"errormessage": "field is required to be filled with an valid email address"
}
]
}MCP-Server & SDK
RechnungsAPI steht KI-Agenten über einen gehosteten MCP-Server zur Verfügung und Entwicklern als offizielles, typisiertes SDK. Verbinden Sie jeden MCP-Client, der Streamable HTTP mit eigenem Authorization-Header unterstützt (zum Beispiel Claude Code oder Open WebUI), starten Sie denselben Server lokal per npx oder installieren Sie das npm-SDK, um die API aus Ihrem eigenen Code heraus aufzurufen.
KI-Agent verbinden (MCP)
Ein gehosteter MCP-Server läuft unter mcp.rechnungsapi.de. Er spricht Streamable HTTP und authentifiziert jede Anfrage mit Ihrem eigenen Bearer-Token (kein OAuth, keine separate Registrierung). Sie möchten ihn lieber selbst ausführen? Derselbe Server ist als npm-Paket rechnungsapi-mcp für stdio-basierte Clients wie Claude Desktop und Claude Code verfügbar.
{
"mcpServers": {
"rechnungsapi": {
"type": "http",
"url": "https://mcp.rechnungsapi.de/mcp",
"headers": { "Authorization": "Bearer <your-api-token>" }
}
}
}Open WebUI unterstützt entfernte MCP-Server nativ: Legen Sie unter Admin Settings → Integrations eine Verbindung vom Typ MCP (Streamable HTTP) an, wählen Sie als Auth „Bearer“ und fügen Sie Ihren Token ein. Clients, die für entfernte Server ausschließlich OAuth anbieten, können sich noch nicht mit dem gehosteten Endpunkt verbinden – nutzen Sie dann die lokale npx-Variante oder das SDK weiter unten.
Offizielles SDK (npm)
Möchten Sie die API direkt aus Ihrem eigenen Backend aufrufen statt über einen KI-Agenten? rechnungsapi-sdk ist ein typisierter TypeScript/JavaScript-Client für ZUGFeRD/X-Invoice-Erstellung, -Validierung und PDF-Analyse.
npm install rechnungsapi-sdk
Pakete und vollständige Dokumentation auf npm: rechnungsapi-mcp · rechnungsapi-sdk