RechnungsAPIv1.0.10
API-Dokumentation
EN-16931-konforme E-Rechnungen (XRechnung & ZUGFeRD) erzeugen, validieren, extrahieren und analysieren – über eine einfache REST- + JSON-Schnittstelle.
v1.0.10 — Produktiv
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
json
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.
Sicherheitshinweis: Behandeln Sie Ihren API-Token wie ein Passwort. Rotieren Sie ihn bei Verdacht auf Leaks sofort über das Dashboard.
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
POST
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
json
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf...",
"withLineItems": true
}Beispielantwort
json
{
"extractionConfidence": 96,
"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"
}
}
]
}
}Playground
Diesen Endpunkt live im Browser testen.
POST
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
json
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf...",
"withLineItems": true
}Beispielantwort
json
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "processing"
}Playground
Diesen Endpunkt live im Browser testen.
GET
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
json
https://api.v2.rechnungsapi.de/rechnungsapi-invoice-async-status?id=1b2c3d4e-5f6a-7890-abcd-ef1234567890
Beispielantwort
json
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "processing"
}Beispielantwort
json
{
"job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890",
"status": "done",
"result": {
"extractionConfidence": 96,
"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"
}
}
]
}
}
}Beispielantwort
json
{
"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.
POST
/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
json
{
"pdfInvoiceBase64": "JVBERi0xLjQKJf..."
}Beispielantwort
json
{
"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"
}
],
"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
POST
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
json
{
"pdfInvoiceBase64": "JVBERi0xLjQKJc...",
"fileName": "Rechnung-2026-0042.pdf"
}Beispielantwort
json
{
"// 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.
POST
/api/v1/zugferd/createXinvoiceFromJsonXRechnung-XML aus JSON erzeugen
Erzeugt ein EN-16931-konformes XRechnungs-XML-Dokument aus strukturierten JSON-Rechnungsdaten – kein PDF erforderlich.
E-Mail-VersandDieses Payload akzeptiert zusätzlich ein optionales transport-Objekt, um die Rechnung im selben Aufruf per E-Mail zu versenden.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
Beispiel
json
{
"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"
}
],
"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
json
{
"message": "xInvoice generated",
"downloadURL": "https://api.rechnungsapi.de/download/xinvoice_RE-2024-001.xml",
"resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf",
"valid": true,
"numberOfXInvoiceErrors": 0,
"xInvoiceErrors": [],
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}Playground
Diesen Endpunkt live im Browser testen.
POST
/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.
E-Mail-VersandDieses Payload akzeptiert zusätzlich ein optionales transport-Objekt, um die Rechnung im selben Aufruf per E-Mail zu versenden.
| Field | Type | Required | Description |
|---|---|---|---|
invoice | object | required | Rechnungsobjekt. |
invoicePdf64 | string (base64) | required | Base64-kodiertes PDF für die XML-Einbettung. |
Beispiel
json
{
"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"
}
],
"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
json
{
"message": "ZUGFeRD created",
"downloadURL": "https://api.rechnungsapi.de/download/zugferd_RE-2024-001.pdf",
"resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf",
"zugferdValid": false,
"xInvoiceValid": false,
"numberOfZugferdErrors": 1,
"numberOfxInvoiceErrors": 1,
"zugferd": "JVBERi0xLjcKJY/6qbAKMyAwIG9iago8PC9...",
"zugferdErrorList": [],
"xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"xInvoiceErrorList": []
}Playground
Diesen Endpunkt live im Browser testen.
POST
/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
json
{
"xInvoiceXml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
"invoicePdf64": "JVBERi0xLjQK..."
}Beispielantwort
json
{
"valid": false,
"message": "zugferd created",
"numberOfZugferdErrors": 0,
"zugferdFile": "JVBERi0xLjcKJaOIwOMKMyAwIG9iago...",
"zugferdErrors": []
}Playground
Diesen Endpunkt live im Browser testen.
POST
/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.
E-Mail-VersandDieses Payload akzeptiert zusätzlich ein optionales transport-Objekt, um die Rechnung im selben Aufruf per E-Mail zu versenden.
| 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. Bei true wird die Rechnung erzeugt und zurückgegeben, ohne serverseitig etwas zu speichern – sie „durchläuft" Ihr Konto lediglich, ohne dass etwas zurückbehalten wird. Auf false setzen, um die Rechnung zu speichern, sodass sie in Ihrer Rechnungsliste erscheint. Hinweis zur Seite „Rechnung erstellen" im Dashboard: Dort wird dies invertiert als standardmäßig deaktiviertes Kontrollkästchen „Diese Rechnung speichern" dargestellt – bleibt es deaktiviert, wird invoicePassthrough: true gesendet (Standard), bei Aktivierung wird invoicePassthrough: false gesendet. |
Beispiel
json
{
"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"
}
],
"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
json
{
"message": "invoice and pdf created",
"downloadURL": "https://api.rechnungsapi.de/download/inv_2025-12-03-001.pdf",
"resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf",
"iqDataId": 215,
"documentId": 533,
"fsNodeId": 5022,
"fileName": "in-2525-4n4_20250805_1755765122.pdf",
"fileExtension": "pdf",
"fileSize": 78573,
"filecontentB64": "JVBERi0xLjQK..."
}Beispielantwort
json
{
"message": "invoice and pdf created",
"downloadURL": "https://api.rechnungsapi.de/download/inv_2025-12-03-001.pdf",
"resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf",
"iqDataId": 215,
"documentId": 533,
"fsNodeId": 5022,
"fileName": "in-2525-4n4_20250805_1755765122.pdf",
"fileExtension": "pdf",
"fileSize": 78573,
"filecontentB64": "JVBERi0xLjQK..."
}Playground
Diesen Endpunkt live im Browser testen.
E-Mail-Versand
POST
/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
json
{
"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
json
{
"message": "email sent",
"resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf"
}Beispielantwort
json
{
"message": "nothing to do. Send option not set to sent"
}Playground
Diesen Endpunkt live im Browser testen.
POST
/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
json
{
"resendToken": "<RESENDTOKEN>"
}Beispielantwort
json
{
"message": "resend"
}Playground
Diesen Endpunkt live im Browser testen.
Extraktion
POST
/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
json
{
"zugferd64": "JVBERi0xLjcKJbe3wvUKMyAwIG9iago8PC9UeXBl..."
}Beispielantwort
json
{
"extractedInvoice": {
"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"
}
],
"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.
Validierung
POST
/api/v1/zugferd/validateXinvoiceXmlXRechnung-XML validieren
Validiert XRechnungs-XML 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.
| Field | Type | Required | Description |
|---|---|---|---|
xinvoiceXML | string | required | XRechnungs-XML-Inhalt als String. |
Beispiel
json
{
"xinvoiceXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
}Beispielantwort
json
{
"valid": false,
"message": "validated. (7835)",
"xInvoiceErrors": [
{
"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"
}
]
}Playground
Diesen Endpunkt live im Browser testen.
POST
/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.
| 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
json
{
"zugferdFile64": "JVBERi0xLjQK...",
"comparePDF2XML": true
}Beispielantwort
json
{
"valid": false,
"message": "File was validated",
"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"
}
]
}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).
required
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.
Kopfdaten (BT-1 bis BT-26)
- BT-1
invoiceNumber - BT-2
invoiceIssueDate - BT-3
invoiceTypeCode - BT-5
invoiceCurrencyCode - BT-10
buyerReference
Verkäufer (BG-4, BT-27 bis BT-43)
- BT-27
sellerName - BT-31
sellerVatIdentifier - BT-34
sellerElectronicAddress - BT-37
sellerPostalAddress.sellerCity - BT-38
sellerPostalAddress.sellerPostCode - BT-40
sellerPostalAddress.sellerCountryCode
Käufer (BG-7, BT-44 bis BT-58)
- BT-44
buyerName - BT-49
buyerElectronicAddress - BT-52
buyerPostalAddress.buyerCity - BT-53
buyerPostalAddress.buyerPostCode - BT-55
buyerPostalAddress.buyerCountryCode
Zahlungsanweisungen (BG-16, BT-81 bis BT-91)
- BT-81
paymentMeansTypeCode
Rechnungsbeträge (BG-22, BT-106 bis BT-115)
- BT-106
sumOfInvoiceLineNetAmount - BT-109
invoiceTotalAmountWithoutVat - BT-110
invoiceTotalVatAmount - BT-112
invoiceTotalAmountWithVat - BT-115
amountDueForPayment
USt-Aufschlüsselung (BG-23, BT-116 bis BT-121)· ≥ 1
- BT-116
vatCategoryTaxableAmount - BT-117
vatCategoryTaxAmount - BT-118
vatCategoryCode - BT-119
vatCategoryRate
Rechnungspositionen (BG-25, BT-126 bis BT-161)· ≥ 1
- 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/150 | priceDetails.itemPriceBaseQuantity | object | optional | Bezugsmenge des Stückpreises + Maßeinheit. |
| 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. |
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:
json
{
"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. |
| 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` / `zugferdErrors` folgt diesem Schema. Nutzen Sie `id` und `location`, um zur fehlerhaften Stelle zu springen.
json
{
"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"
}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
Sicherheitshinweis: Der Token, den Sie in der Konfiguration eines MCP-Clients hinterlegen, ist derselbe wie überall sonst – behandeln Sie ihn wie ein Passwort. Rotieren Sie ihn bei Verdacht auf Leaks sofort über das Dashboard.