rechnungsapi.de
    Startseite
    Lösungen
    Zielgruppen
    Steuerberater & KanzleienUnternehmen & MittelstandIT-Teams & SoftwareanbieterE-Invoicing-Berater & PartnerStartups & SaaSInternational & Peppol
    ERP-SystemeAptifyClaris FileMakerDocuWareIBM i (AS/400)IFSMicrosoft Dynamics 365 Business CentralMicrosoft Dynamics 365 Finance & OperationsMicrosoft Dynamics NAV (Navision)OdooOnline-Shops (Shopify, WooCommerce, Shopware)Oracle NetSuiteproALPHASage 100 (Office Line)Sage Classic LineSalesforceSAP ECC 6.0SAP S/4HANAWord & Excel
    Produkte
    E-Rechnung per OrdnerPDF in ZUGFeRD umwandelnPeppol-AnbindungRechnung auslesen: PDF zu JSONXRechnung APIZUGFeRD API
    PreiseValidatorXML-ViewerBlogKontakt
    Dokumentation
    DokumentationOrdner-Integration & SFTP, ohne ProgrammierungAPI DocsREST-API-Referenz für Entwickler
    AnmeldenLoslegen
    Für Entwickler und KI-Assistenten:OpenAPI-Spezifikation (JSON)Swagger UIMCP-ServerSDK (npm)
    RechnungsAPIv1.0.10

    Server

    https://api.rechnungsapi.de

    Erste Schritte

    AuthentifizierungSchnellstart

    Endpunkte

    PDF Analyse

    POSTRechnungs-PDF analysieren (V2 — empfohlen)POSTRechnungs-PDF analysieren (Asynchron — Einreichen)GETStatus der asynchronen Analyse abfragenPOSTRechnungs-PDF analysieren (V1 — legacy)

    Rechnungserzeugung

    POSTPDF zu ZUGFeRD konvertieren (ein Aufruf)POSTXRechnung-XML aus JSON erzeugenPOSTZUGFeRD aus JSON + PDF erzeugenPOSTZUGFeRD-PDF aus XRechnung erstellenPOSTZUGFeRD-Rechnungs-PDF aus JSON erzeugen (Template)

    E-Mail-Versand

    POSTEigenständigen E-Mail-Versand auslösenPOSTE-Mail erneut versenden

    Extraktion

    POSTXRechnung aus ZUGFeRD als JSON extrahieren

    Validierung

    POSTXRechnung-XML validierenPOSTZUGFeRD-PDF validieren

    Referenz

    RechnungsobjektE-Mail-VersandFehlerMCP-Server & SDK

    Weitere Dokumentation

    Ordner-Integration & SFTP

    API-Dokumentation

    EN-16931-konforme E-Rechnungen (XRechnung & ZUGFeRD) erzeugen, validieren, extrahieren und analysieren – über eine einfache REST- + JSON-Schnittstelle. Produktüberblick mit Formaten und Preisen: XRechnung API und ZUGFeRD API.

    v1.0.10 — Produktivhttps://api.rechnungsapi.de

    Ohne 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>
    1. Melden Sie sich im Dashboard an unter rechnungsapi.de.
    2. Öffnen Sie Ihr Profil und kopieren Sie unten den API-Token.
    3. 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

    POSThttps://api.v2.rechnungsapi.de/createJSONFromAnalysedPdf

    Rechnungs-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.

    FieldTypeRequiredDescription
    pdfInvoiceBase64stringrequiredBase64-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).
    withLineItemsbooleanoptionalBei 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": 100,
      "invoice": {
        "invoiceNumber": "RE-2026-08-0815",
        "invoiceIssueDate": "24.08.2026",
        "invoiceTypeCode": "380",
        "invoiceCurrencyCode": "EUR",
        "paymentDueDate": "23.09.2026",
        "buyerReference": "04011000-12345-67",
        "purchaseOrderReference": "BST-2026-4471",
        "paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …",
        "seller": {
          "sellerName": "Müller & Söhne Großhandel GmbH",
          "sellerVatIdentifier": "DE812345678"
        },
        "buyer": {
          "buyerName": "Bäckerei Schröder KG"
        },
        "deliveryInformation": {
          "actualDeliveryDate": "31.07.2026"
        },
        "paymentInstructions": {
          "paymentMeansTypeCode": "58",
          "creditTransfer": [
            {
              "paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78",
              "paymentAccountName": "Müller & Söhne Großhandel GmbH",
              "paymentServiceProviderIdentifier": "DUSSDEDDXXX"
            }
          ]
        },
        "documentTotals": {
          "sumOfInvoiceLineNetAmount": 6519.7,
          "invoiceTotalAmountWithoutVat": 6519.7,
          "invoiceTotalVatAmount": 1234.1,
          "invoiceTotalAmountWithVat": 7753.8,
          "amountDueForPayment": 7753.8
        },
        "vatBreakdown": [
          {
            "vatCategoryTaxableAmount": 6481,
            "vatCategoryTaxAmount": 1231.39,
            "vatCategoryCode": "S",
            "vatCategoryRate": 19
          },
          {
            "vatCategoryTaxableAmount": 38.7,
            "vatCategoryTaxAmount": 2.71,
            "vatCategoryCode": "S",
            "vatCategoryRate": 7
          }
        ],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "1",
            "invoicedQuantity": 12,
            "invoicedQuantityUnitOfMeasureCode": "HUR",
            "invoiceLineNetAmount": 1740,
            "priceDetails": {
              "itemNetPrice": 145
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "S",
                "invoicedItemVatRate": 19
              }
            ],
            "itemInformation": {
              "itemName": "Beratungsleistung Softwarearchitektur"
            }
          }
        ]
      },
      "zugferdReady": true,
      "lineItemCheck": {
        "status": "ok",
        "verified": true,
        "lines": 5,
        "linesRecomputed": 5,
        "linesInconsistent": 0,
        "lineSum": 6519.7,
        "sumCheck": "ok",
        "confirmedBy": "printed BT-106",
        "vatCheck": "ok"
      },
      "confidenceBasis": {
        "requirementsChecked": 43,
        "requirementsMet": 43
      },
      "warnings": []
    }

    Antwortfelder

    FieldTypeDescription
    extractionConfidenceinteger (0–100)Wie vollständig die Extraktion ist: der Anteil der geprüften Anforderungen, die sie erfüllt (`confidenceBasis.requirementsMet` von `requirementsChecked`, z. B. 41 von 43 → 95). 100 = vollständig. Alles darunter bedeutet, dass Pflichtangaben fehlen (siehe `mandatoryFieldReport`) und sich die Rechnung so nicht in eine ZUGFeRD-Rechnung umwandeln lässt.
    invoiceobjectDie extrahierte Rechnung (siehe Rechnungsobjekt-Referenz). Felder ohne Wert im Quelldokument werden weggelassen.
    zugferdReadybooleanBereitschafts-Flag für die ZUGFeRD-Erzeugung: `true`, wenn die Extraktion alle geprüften Anforderungen erfüllt hat (siehe `confidenceBasis`), also `extractionConfidence` 100 ist. Sonst `false` — `mandatoryFieldReport` listet dann, was fehlt.
    mandatoryFieldReportarray (only below 100)Die im Dokument fehlenden Pflichtangaben, ein Eintrag je Lücke. Nur vorhanden, wenn `extractionConfidence` unter 100 liegt; bei 100 fehlt die Eigenschaft vollständig — prüfen Sie auf ihr Vorhandensein, gehen Sie nicht von einem leeren Array aus. Diese Lücken senken die Konfidenz und verhindern die ZUGFeRD-Erzeugung: Ergänzen Sie die Angaben im Quelldokument und analysieren Sie es erneut, oder ergänzen Sie sie im extrahierten `invoice`, bevor Sie die ZUGFeRD-Datei erzeugen.
    mandatoryFieldReport[].rulestringDie Regel, die die Angabe verpflichtend macht: eine EN-16931-Geschäftsregel (`BR-09`, `BR-CO-26`) oder eine deutsche XRechnung-Regel (`BR-DE-1`, `BR-DE-16`).
    mandatoryFieldReport[].btstringDer betroffene EN-16931-Business-Term (`BT-40`) bzw. die Business-Gruppe (`BG-16`). Genügen mehrere Terme alternativ der Regel, werden sie mit `/` verbunden, z. B. `BT-29/BT-30/BT-31`.
    mandatoryFieldReport[].fieldstringPunktpfad in `invoice`, an den der fehlende Wert gehört, z. B. `seller.sellerContact.sellerContactTelephoneNumber`. Eine ganze Gruppe wird über ihren Objektnamen angesprochen, z. B. `paymentInstructions`.
    mandatoryFieldReport[].labelstringKurzer deutscher Name der fehlenden Angabe, zur Anzeige. Mit ae/oe/ue statt ä/ö/ü geschrieben (z. B. `Land des Verkaeufers`): zeigen Sie ihn Nutzern an, verwenden Sie im Code aber `field`, `bt` oder `rule`.
    lineItemCheckobjectPlausibilitätsprüfung der extrahierten Positionen gegen die Summen. Eigenschaften unten.
    lineItemCheck.statusstringGesamtergebnis der Positionsprüfung, z. B. `ok`.
    lineItemCheck.verifiedboolean`true`, wenn die Positionen gegen eine aufgedruckte Summe bestätigt werden konnten.
    lineItemCheck.linesintegerAnzahl der gefundenen Positionen.
    lineItemCheck.linesRecomputedintegerAnzahl der Positionen, deren Betrag für die Prüfung nachgerechnet wurde.
    lineItemCheck.linesInconsistentintegerAnzahl der Positionen, deren nachgerechneter Betrag nicht zum extrahierten passte. `0` ist der Idealfall.
    lineItemCheck.lineSumnumberSumme der Positions-Nettobeträge.
    lineItemCheck.sumCheckstringOb `lineSum` mit der Dokumentsumme übereinstimmt, z. B. `ok`.
    lineItemCheck.confirmedBystringWelcher Wert im Dokument die Summe bestätigt hat, z. B. `printed BT-106` (die aufgedruckte Summe der Positions-Nettobeträge).
    lineItemCheck.vatCheckstringOb die Umsatzsteuer-Angaben konsistent sind, z. B. `ok`.
    confidenceBasisobjectWorauf `extractionConfidence` beruht: `requirementsChecked` ist die Zahl der Anforderungen, gegen die die Extraktion geprüft wurde, `requirementsMet` wie viele davon erfüllt sind.
    warningsarray of objectsHinweise auf Werte, die der Analyzer ersetzen oder ableiten musste, damit die Rechnung verarbeitbar bleibt (siehe `code`); leer, wenn es keine gibt. Ein Platzhalter sind keine echten Daten: bitte prüfen.
    warnings[].codestringArt der Warnung. Beobachtet: `PLACEHOLDER_INSERTED` (ein erforderlicher Wert stand nicht im Dokument, es wurde ein Platzhalter eingefügt) und `VALUE_DERIVED` (ein Wert wurde abgeleitet statt gelesen, z. B. Land `DE` für eine inländische Adresse angenommen).
    warnings[].fieldstringDer betroffene Business-Term, z. B. `BT-10`.
    warnings[].messagestringErklärung in Klartext, auf Deutsch.

    Beispielantwort

    json
    {
      "extractionConfidence": 95,
      "invoice": {
        "invoiceNumber": "RE-2026-08-0815",
        "invoiceIssueDate": "24.08.2026",
        "invoiceTypeCode": "380",
        "invoiceCurrencyCode": "EUR",
        "paymentDueDate": "23.09.2026",
        "buyerReference": "04011000-12345-67",
        "purchaseOrderReference": "BST-2026-4471",
        "paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …",
        "seller": {
          "sellerName": "Müller & Söhne Großhandel GmbH",
          "sellerVatIdentifier": "DE812345678"
        },
        "buyer": {
          "buyerName": "Bäckerei Schröder KG"
        },
        "deliveryInformation": {
          "actualDeliveryDate": "31.07.2026"
        },
        "paymentInstructions": {
          "paymentMeansTypeCode": "58",
          "creditTransfer": [
            {
              "paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78",
              "paymentAccountName": "Müller & Söhne Großhandel GmbH",
              "paymentServiceProviderIdentifier": "DUSSDEDDXXX"
            }
          ]
        },
        "documentTotals": {
          "sumOfInvoiceLineNetAmount": 6519.7,
          "invoiceTotalAmountWithoutVat": 6519.7,
          "invoiceTotalVatAmount": 1234.1,
          "invoiceTotalAmountWithVat": 7753.8,
          "amountDueForPayment": 7753.8
        },
        "vatBreakdown": [
          {
            "vatCategoryTaxableAmount": 6481,
            "vatCategoryTaxAmount": 1231.39,
            "vatCategoryCode": "S",
            "vatCategoryRate": 19
          },
          {
            "vatCategoryTaxableAmount": 38.7,
            "vatCategoryTaxAmount": 2.71,
            "vatCategoryCode": "S",
            "vatCategoryRate": 7
          }
        ],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "1",
            "invoicedQuantity": 12,
            "invoicedQuantityUnitOfMeasureCode": "HUR",
            "invoiceLineNetAmount": 1740,
            "priceDetails": {
              "itemNetPrice": 145
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "S",
                "invoicedItemVatRate": 19
              }
            ],
            "itemInformation": {
              "itemName": "Beratungsleistung Softwarearchitektur"
            }
          }
        ]
      },
      "zugferdReady": false,
      "mandatoryFieldReport": [
        {
          "rule": "BR-DE-6",
          "bt": "BT-42",
          "field": "seller.sellerContact.sellerContactTelephoneNumber",
          "label": "Telefon des Verkaeufers"
        },
        {
          "rule": "BR-DE-7",
          "bt": "BT-43",
          "field": "seller.sellerContact.sellerContactEmailAddress",
          "label": "E-Mail des Verkaeufers"
        }
      ],
      "lineItemCheck": {
        "status": "ok",
        "verified": true,
        "lines": 5,
        "linesRecomputed": 5,
        "linesInconsistent": 0,
        "lineSum": 6519.7,
        "sumCheck": "ok",
        "confirmedBy": "printed BT-106",
        "vatCheck": "ok"
      },
      "confidenceBasis": {
        "requirementsChecked": 43,
        "requirementsMet": 41
      },
      "warnings": [
        {
          "code": "VALUE_DERIVED",
          "field": "BT-40/BT-55",
          "message": "Land DE angenommen (inländische Adresse, kein Land gedruckt)"
        },
        {
          "code": "PLACEHOLDER_INSERTED",
          "field": "BT-10",
          "message": "Keine Käuferreferenz / Leitweg-ID gedruckt: Platzhalter \"No BuyerReference provided\" (XRechnung verlangt BT-10)"
        }
      ]
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    POSThttps://api.v2.rechnungsapi.de/createJSONFromAnalysedPdfAsync

    Rechnungs-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.

    FieldTypeRequiredDescription
    pdfInvoiceBase64stringrequiredBase64-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.
    withLineItemsbooleanoptionalBei 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.

    GEThttps://api.v2.rechnungsapi.de/rechnungsapi-invoice-async-status

    Status 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.

    FieldTypeRequiredDescription
    idstring (uuid, query param)requiredDie 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": 100,
        "invoice": {
          "invoiceNumber": "RE-2026-08-0815",
          "invoiceIssueDate": "24.08.2026",
          "invoiceTypeCode": "380",
          "invoiceCurrencyCode": "EUR",
          "paymentDueDate": "23.09.2026",
          "buyerReference": "04011000-12345-67",
          "purchaseOrderReference": "BST-2026-4471",
          "paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …",
          "seller": {
            "sellerName": "Müller & Söhne Großhandel GmbH",
            "sellerVatIdentifier": "DE812345678"
          },
          "buyer": {
            "buyerName": "Bäckerei Schröder KG"
          },
          "deliveryInformation": {
            "actualDeliveryDate": "31.07.2026"
          },
          "paymentInstructions": {
            "paymentMeansTypeCode": "58",
            "creditTransfer": [
              {
                "paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78",
                "paymentAccountName": "Müller & Söhne Großhandel GmbH",
                "paymentServiceProviderIdentifier": "DUSSDEDDXXX"
              }
            ]
          },
          "documentTotals": {
            "sumOfInvoiceLineNetAmount": 6519.7,
            "invoiceTotalAmountWithoutVat": 6519.7,
            "invoiceTotalVatAmount": 1234.1,
            "invoiceTotalAmountWithVat": 7753.8,
            "amountDueForPayment": 7753.8
          },
          "vatBreakdown": [
            {
              "vatCategoryTaxableAmount": 6481,
              "vatCategoryTaxAmount": 1231.39,
              "vatCategoryCode": "S",
              "vatCategoryRate": 19
            },
            {
              "vatCategoryTaxableAmount": 38.7,
              "vatCategoryTaxAmount": 2.71,
              "vatCategoryCode": "S",
              "vatCategoryRate": 7
            }
          ],
          "invoiceLine": [
            {
              "invoiceLineIdentifier": "1",
              "invoicedQuantity": 12,
              "invoicedQuantityUnitOfMeasureCode": "HUR",
              "invoiceLineNetAmount": 1740,
              "priceDetails": {
                "itemNetPrice": 145
              },
              "lineVatInformation": [
                {
                  "invoicedItemVatCategoryCode": "S",
                  "invoicedItemVatRate": 19
                }
              ],
              "itemInformation": {
                "itemName": "Beratungsleistung Softwarearchitektur"
              }
            }
          ]
        },
        "zugferdReady": true,
        "lineItemCheck": {
          "status": "ok",
          "verified": true,
          "lines": 5,
          "linesRecomputed": 5,
          "linesInconsistent": 0,
          "lineSum": 6519.7,
          "sumCheck": "ok",
          "confirmedBy": "printed BT-106",
          "vatCheck": "ok"
        },
        "confidenceBasis": {
          "requirementsChecked": 43,
          "requirementsMet": 43
        },
        "warnings": []
      }
    }

    Beispielantwort

    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/createJSONFromAnalysedPdf

    Rechnungs-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.

    FieldTypeRequiredDescription
    pdfInvoiceBase64stringrequiredBase64-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",
            "supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
            "attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
          }
        ],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "String | BT-126",
            "invoiceLineNote": "String | BT-127",
            "invoiceLineObjectIdentifier": "String | BT-128",
            "invoicedQuantity": "Decimal | BT-129",
            "invoicedQuantityUnitOfMeasureCode": "String | BT-130",
            "invoiceLineNetAmount": "Decimal | BT-131",
            "referencedPurchaseOrderLineReference": "String | BT-132",
            "invoiceLineBuyerAccountingReference": "String | BT-133",
            "invoiceLinePeriod": {
              "invoiceLinePeriodStartDate": "Date | BT-134",
              "invoiceLinePeriodEndDate": "Date | BT-135"
            },
            "invoiceLineAllowances": [
              {
                "invoiceLineAllowanceAmount": "Decimal | BT-136",
                "invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
                "invoiceLineAllowancePercentage": "Decimal | BT-138",
                "invoiceLineAllowanceReason": "String | BT-139",
                "invoiceLineAllowanceReasonCode": "String | BT-140"
              }
            ],
            "invoiceLineCharges": [
              {
                "invoiceLineChargeAmount": "Decimal | BT-141",
                "invoiceLineChargeBaseAmount": "Decimal | BT-142",
                "invoiceLineChargePercentage": "Decimal | BT-143",
                "invoiceLineChargeReason": "String | BT-144",
                "invoiceLineChargeReasonCode": "String | BT-145"
              }
            ],
            "priceDetails": {
              "itemNetPrice": "Decimal | BT-146",
              "itemPriceDiscount": "Decimal | BT-147",
              "itemGrossPrice": "Decimal | BT-148",
              "itemPriceBaseQuantity": "Decimal | BT-149",
              "itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "String | BT-151",
                "invoicedItemVatRate": "Decimal | BT-152"
              }
            ],
            "itemInformation": {
              "itemName": "String | BT-153",
              "itemDescription": "String | BT-154",
              "itemSellersIdentifier": "String | BT-155",
              "itemBuyersIdentifier": "String | BT-156",
              "itemStandardIdentifier": "String | BT-157",
              "itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
              "itemClassificationIdentifier": [
                {
                  "itemClassificationIdentifier": "String | BT-158",
                  "itemClassificationIdentifierListIdentifier": "String | BT-158-1",
                  "itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
                }
              ],
              "itemCountryOfOrigin": "String | BT-159",
              "itemAttributes": [
                {
                  "itemAttributeName": "String | BT-160",
                  "itemAttributeValue": "String | BT-161"
                }
              ]
            }
          }
        ]
      }
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    Rechnungserzeugung

    POSThttps://api.v2.rechnungsapi.de/createZugferdFromPdf

    PDF 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.

    FieldTypeRequiredDescription
    pdfInvoiceBase64string (base64)requiredBase64 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.
    fileNamestringoptionalUrsprü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/createXinvoiceFromJson

    XRechnung-XML aus JSON erzeugen

    Erzeugt ein EN-16931-konformes XRechnungs-XML-Dokument aus strukturierten JSON-Rechnungsdaten – kein PDF erforderlich. Die XML-Syntax ist standardmäßig CII; setzen Sie `xmlFormat` auf `UBL`, um stattdessen ein UBL-Dokument zu erhalten (`xmlFormat: "CII"` liefert CII, wie wenn das Feld fehlt). Das Rechnungs-JSON ist für beide Syntaxen identisch — nur das XML in der Antwort ändert sich. UBL-Ausgabe gibt es nur über diesen Endpunkt; die ZUGFeRD-Endpunkte betten, wie vom ZUGFeRD-Standard verlangt, immer CII-XML ein.

    E-Mail-VersandDieses Payload akzeptiert zusätzlich ein optionales transport-Objekt, um die Rechnung im selben Aufruf per E-Mail zu versenden.
    FieldTypeRequiredDescription
    invoiceobjectrequiredRechnungsobjekt.
    xmlFormatstringoptionalSyntax des erzeugten XML: `CII` (UN/CEFACT Cross Industry Invoice, Standard, wenn das Feld fehlt) oder `UBL` (Universal Business Language, UBL-2.1-`Invoice`). Die Groß-/Kleinschreibung spielt keine Rolle, `ubl` und `UBL` wirken gleich. Das Feld bestimmt das XML in `xInvoice` und unter `downloadURL`; der Aufruf ist sonst unverändert. Beispiel: `{ "invoice": { … }, "xmlFormat": "UBL" }`. Validierungsbefunde nennen das Regelwerk der jeweiligen Syntax (siehe `schemaFile` unten).

    Beispiel

    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",
            "supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
            "attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
          }
        ],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "String | BT-126",
            "invoiceLineNote": "String | BT-127",
            "invoiceLineObjectIdentifier": "String | BT-128",
            "invoicedQuantity": "Decimal | BT-129",
            "invoicedQuantityUnitOfMeasureCode": "String | BT-130",
            "invoiceLineNetAmount": "Decimal | BT-131",
            "referencedPurchaseOrderLineReference": "String | BT-132",
            "invoiceLineBuyerAccountingReference": "String | BT-133",
            "invoiceLinePeriod": {
              "invoiceLinePeriodStartDate": "Date | BT-134",
              "invoiceLinePeriodEndDate": "Date | BT-135"
            },
            "invoiceLineAllowances": [
              {
                "invoiceLineAllowanceAmount": "Decimal | BT-136",
                "invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
                "invoiceLineAllowancePercentage": "Decimal | BT-138",
                "invoiceLineAllowanceReason": "String | BT-139",
                "invoiceLineAllowanceReasonCode": "String | BT-140"
              }
            ],
            "invoiceLineCharges": [
              {
                "invoiceLineChargeAmount": "Decimal | BT-141",
                "invoiceLineChargeBaseAmount": "Decimal | BT-142",
                "invoiceLineChargePercentage": "Decimal | BT-143",
                "invoiceLineChargeReason": "String | BT-144",
                "invoiceLineChargeReasonCode": "String | BT-145"
              }
            ],
            "priceDetails": {
              "itemNetPrice": "Decimal | BT-146",
              "itemPriceDiscount": "Decimal | BT-147",
              "itemGrossPrice": "Decimal | BT-148",
              "itemPriceBaseQuantity": "Decimal | BT-149",
              "itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "String | BT-151",
                "invoicedItemVatRate": "Decimal | BT-152"
              }
            ],
            "itemInformation": {
              "itemName": "String | BT-153",
              "itemDescription": "String | BT-154",
              "itemSellersIdentifier": "String | BT-155",
              "itemBuyersIdentifier": "String | BT-156",
              "itemStandardIdentifier": "String | BT-157",
              "itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
              "itemClassificationIdentifier": [
                {
                  "itemClassificationIdentifier": "String | BT-158",
                  "itemClassificationIdentifierListIdentifier": "String | BT-158-1",
                  "itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
                }
              ],
              "itemCountryOfOrigin": "String | BT-159",
              "itemAttributes": [
                {
                  "itemAttributeName": "String | BT-160",
                  "itemAttributeValue": "String | BT-161"
                }
              ]
            }
          }
        ]
      },
      "xmlFormat": "CII",
      "transport": {
        "type": "email",
        "useTransport": true,
        "sender": "rechnung@ihre-domain.de",
        "senderName": "Ihre Firma GmbH",
        "receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
        "cc": "steuerberater@kanzlei.de",
        "bcc": "archiv@ihre-domain.de",
        "subject": "Rechnung {invoicenumber} vom {invoicedate}",
        "message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
        "attachments": [
          {
            "fileName": "Leistungsnachweis.pdf",
            "fileBase64": "<base64>"
          }
        ]
      }
    }

    Beispielantwort

    json
    {
      "message": "xInvoice generated",
      "valid": true,
      "numberOfXInvoiceErrors": 0,
      "xInvoiceErrors": [],
      "xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793267754_Qx7LmN2pVd9RtKs4WbHy8CfJe1ZaGu3o",
      "resendToken": "",
      "invoice": [
        {
          "invoiceNumber": "RE-2025-001",
          "invoiceIssueDate": "2026-02-16T00:00:00+01:00",
          "invoiceTypeCode": "380",
          "invoiceCurrencyCode": "EUR",
          "vatAccountingCurrencyCode": null,
          "valueAddedTaxPointDate": null,
          "valueAddedTaxPointDateCode": "",
          "paymentDueDate": "2026-03-02T00:00:00+01:00",
          "buyerReference": "BEST-2025-042",
          "projectReference": {
            "projectReferenceIdentifier": "",
            "projectReferenceName": ""
          },
          "contractReference": "",
          "purchaseOrderReference": "",
          "salesOrderReference": "",
          "receivingAdviceReference": "",
          "despatchAdviceReference": "",
          "tenderOrLotReference": null,
          "invoicedObjectIdentifier": null,
          "buyerAccountingReference": "Sachkonto 12000",
          "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
          "invoiceNote": [],
          "processControl": {
            "businessProcessTypeIdentifier": "",
            "specificationIdentifier": ""
          },
          "precedingInvoiceReference": [],
          "seller": {
            "sellerName": "Ihre Firma GmbH",
            "sellerTradingName": "",
            "sellerIdentifier": [],
            "sellerLegalRegistrationIdentifier": "HRB 67890 B",
            "sellerVatIdentifier": "DE123456789",
            "sellerTaxRegistrationIdentifier": "12/345/67890",
            "sellerAdditionalLegalInformation": "",
            "sellerElectronicAddress": "info@ihre-firma.de",
            "sellerPostalAddress": {
              "sellerAddressLine1": "Musterstraße 1",
              "sellerAddressLine2": "",
              "sellerAddressLine3": "",
              "sellerCity": "Berlin",
              "sellerPostCode": "12345",
              "sellerCountrySubdivision": "",
              "sellerCountryCode": "DE"
            },
            "sellerContact": {
              "sellerContactPoint": "Vertrieb",
              "sellerContactTelephoneNumber": "+49 30 9876543",
              "sellerContactEmailAddress": "info@ihre-firma.de"
            }
          },
          "buyer": {
            "buyerName": "Müller und Mayer GmbH",
            "buyerTradingName": "",
            "buyerIdentifier": "",
            "buyerLegalRegistrationIdentifier": "HRB 12345",
            "buyerVatIdentifier": "DE987654321",
            "buyerElectronicAddress": "rechnung@mueller-mayer.de",
            "buyerPostalAddress": {
              "buyerAddressLine1": "Kundenstraße 42",
              "buyerAddressLine2": "",
              "buyerAddressLine3": "",
              "buyerCity": "Berlin",
              "buyerPostCode": "10115",
              "buyerCountrySubdivision": "",
              "buyerCountryCode": "DE"
            },
            "buyerContact": {
              "buyerContactPoint": "",
              "buyerContactTelephoneNumber": "+49 30 12345678",
              "buyerContactEmailAddress": "rechnung@mueller-mayer.de"
            }
          },
          "payee": {
            "payeeName": "",
            "payeeIdentifier": "",
            "payeeLegalRegistrationIdentifier": ""
          },
          "sellerTaxRepresentativeParty": {
            "sellerTaxRepresentativeName": "",
            "sellerTaxRepresentativeVatIdentifier": "",
            "sellerTaxRepresentativePostalAddress": {
              "taxRepresentativeAddressLine1": "",
              "taxRepresentativeAddressLine2": "",
              "taxRepresentativeAddressLine3": "",
              "taxRepresentativeCity": "",
              "taxRepresentativePostCode": "",
              "taxRepresentativeCountrySubdivision": "",
              "taxRepresentativeCountryCode": ""
            }
          },
          "deliveryInformation": null,
          "invoicingPeriod": {
            "invoicingPeriodStartDate": null,
            "invoicingPeriodEndDate": null
          },
          "paymentInstructions": {
            "paymentMeansTypeCode": "58",
            "paymentMeansText": "SEPA-Überweisung",
            "remittanceInformation": "RE-2025-001",
            "creditTransfer": [
              {
                "paymentAccountIdentifier": "DE89370400440532013000",
                "paymentAccountName": "Ihre Firma GmbH",
                "paymentServiceProviderIdentifier": "COBADEFFXXX"
              }
            ],
            "paymentCardInformation": {
              "paymentCardPrimaryAccountNumber": "",
              "paymentCardHolderName": ""
            },
            "directDebit": {
              "mandateReferenceIdentifier": "",
              "bankAssignedCreditorIdentifier": "",
              "debitedAccountIdentifier": ""
            }
          },
          "documentLevelAllowances": [],
          "documentLevelCharges": [],
          "documentTotals": {
            "sumOfInvoiceLineNetAmount": 1799,
            "sumOfAllowancesOnDocumentLevel": 0,
            "sumOfChargesOnDocumentLevel": 0,
            "invoiceTotalAmountWithoutVat": 1799,
            "invoiceTotalVatAmount": 341.81,
            "invoiceTotalVatAmountInAccountingCurrency": 0,
            "invoiceTotalAmountWithVat": 2140.81,
            "paidAmount": 0,
            "roundingAmount": 0,
            "amountDueForPayment": 2140.81
          },
          "vatBreakdown": [
            {
              "vatCategoryTaxableAmount": 1799,
              "vatCategoryTaxAmount": 341.81,
              "vatCategoryCode": "S",
              "vatCategoryRate": 19,
              "vatExemptionReasonText": "",
              "vatExemptionReasonCode": ""
            }
          ],
          "additionalSupportingDocuments": [],
          "invoiceLine": [
            {
              "invoiceLineIdentifier": "1",
              "invoiceLineNote": "",
              "invoiceLineObjectIdentifier": "",
              "invoicedQuantity": 10,
              "invoicedQuantityUnitOfMeasureCode": "HUR",
              "invoiceLineNetAmount": 1200,
              "referencedPurchaseOrderLineReference": "",
              "invoiceLineBuyerAccountingReference": "",
              "invoiceLinePeriod": {
                "invoiceLinePeriodStartDate": null,
                "invoiceLinePeriodEndDate": null
              },
              "invoiceLineAllowances": [],
              "invoiceLineCharges": [],
              "priceDetails": {
                "itemNetPrice": 120,
                "itemPriceDiscount": 0,
                "itemGrossPrice": 120,
                "itemPriceBaseQuantity": 1,
                "itemPriceBaseQuantityUnitOfMeasure": "HUR"
              },
              "lineVatInformation": [
                {
                  "invoicedItemVatCategoryCode": "S",
                  "invoicedItemVatRate": 19
                }
              ],
              "itemInformation": {
                "itemName": "Beratung & Projektbegleitung",
                "itemDescription": "",
                "itemSellersIdentifier": "",
                "itemBuyersIdentifier": "",
                "itemStandardIdentifier": "",
                "itemStandardIdentifierSchemeIdentifier": "",
                "itemClassificationIdentifier": [],
                "itemCountryOfOrigin": "",
                "itemAttributes": []
              }
            }
          ]
        }
      ]
    }

    Antwortfelder

    FieldTypeDescription
    messagestringStatustext, `xInvoice generated`.
    validboolean`true`, wenn das erzeugte XML die Validierung bestanden hat (`xInvoiceErrors` ist leer). Das XML wird in jedem Fall zurückgegeben.
    numberOfXInvoiceErrorsintegerAnzahl der Einträge in `xInvoiceErrors`.
    xInvoiceErrorsarrayValidierungsbefunde zum erzeugten XML; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    xInvoiceErrors[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    xInvoiceErrors[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    xInvoiceErrors[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    xInvoiceErrors[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    xInvoiceErrors[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    xInvoiceErrors[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.
    xInvoicestringDas erzeugte XRechnungs-XML (UTF-8) in der mit `xmlFormat` angeforderten Syntax — standardmäßig CII, auf Wunsch UBL —, inline zurückgegeben, auch wenn `valid` `false` ist.
    downloadURLstring (url)Link zum erzeugten XML (`Content-Type: application/xml`). Er lässt sich ohne Authorization-Header öffnen — jeder, der den Link kennt, kann die Datei herunterladen. Behandeln Sie ihn wie ein Geheimnis.
    resendTokenstringLeerer String `""`, wenn keine E-Mail versendet wurde. Wurde `transport` bei einem gültigen Dokument genutzt, der Token für `sendEmailWithZugferdData` — siehe E-Mail-Versand.
    invoicearrayEin Array mit einem Element: die Rechnung, wie das System sie verstanden hat — das vollständige Rechnungsobjekt (siehe unten), normalisiert. Jedes Feld ist vorhanden — nicht gesetzte Textfelder sind `""`, nicht gesetzte Datumswerte und Objekte `null`, nicht gesetzte Listen `[]`; Datumswerte sind ISO-8601-Zeitstempel mit UTC-Offset (z. B. `2026-02-16T00:00:00+01:00`). Weggelassene Preisangaben werden mit `0` befüllt.

    Beispielantwort

    json
    {
      "message": "xInvoice generated",
      "valid": true,
      "numberOfXInvoiceErrors": 0,
      "xInvoiceErrors": [],
      "xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ubl:Invoice xmlns:ubl=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\" xmlns:cac=\"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2\" xmlns:cbc=\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\">...</ubl:Invoice>",
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793267803_Wd5TrB1nXcQ8LsKy3MzHp6EvAj2UfGo9",
      "resendToken": "",
      "invoice": [
        {
          "invoiceNumber": "RE-2025-001",
          "invoiceIssueDate": "2026-02-16T00:00:00+01:00",
          "invoiceTypeCode": "380",
          "invoiceCurrencyCode": "EUR",
          "vatAccountingCurrencyCode": null,
          "valueAddedTaxPointDate": null,
          "valueAddedTaxPointDateCode": "",
          "paymentDueDate": "2026-03-02T00:00:00+01:00",
          "buyerReference": "BEST-2025-042",
          "projectReference": {
            "projectReferenceIdentifier": "",
            "projectReferenceName": ""
          },
          "contractReference": "",
          "purchaseOrderReference": "",
          "salesOrderReference": "",
          "receivingAdviceReference": "",
          "despatchAdviceReference": "",
          "tenderOrLotReference": null,
          "invoicedObjectIdentifier": null,
          "buyerAccountingReference": "Sachkonto 12000",
          "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
          "invoiceNote": [],
          "processControl": {
            "businessProcessTypeIdentifier": "",
            "specificationIdentifier": ""
          },
          "precedingInvoiceReference": [],
          "seller": {
            "sellerName": "Ihre Firma GmbH",
            "sellerTradingName": "",
            "sellerIdentifier": [],
            "sellerLegalRegistrationIdentifier": "HRB 67890 B",
            "sellerVatIdentifier": "DE123456789",
            "sellerTaxRegistrationIdentifier": "12/345/67890",
            "sellerAdditionalLegalInformation": "",
            "sellerElectronicAddress": "info@ihre-firma.de",
            "sellerPostalAddress": {
              "sellerAddressLine1": "Musterstraße 1",
              "sellerAddressLine2": "",
              "sellerAddressLine3": "",
              "sellerCity": "Berlin",
              "sellerPostCode": "12345",
              "sellerCountrySubdivision": "",
              "sellerCountryCode": "DE"
            },
            "sellerContact": {
              "sellerContactPoint": "Vertrieb",
              "sellerContactTelephoneNumber": "+49 30 9876543",
              "sellerContactEmailAddress": "info@ihre-firma.de"
            }
          },
          "buyer": {
            "buyerName": "Müller und Mayer GmbH",
            "buyerTradingName": "",
            "buyerIdentifier": "",
            "buyerLegalRegistrationIdentifier": "HRB 12345",
            "buyerVatIdentifier": "DE987654321",
            "buyerElectronicAddress": "rechnung@mueller-mayer.de",
            "buyerPostalAddress": {
              "buyerAddressLine1": "Kundenstraße 42",
              "buyerAddressLine2": "",
              "buyerAddressLine3": "",
              "buyerCity": "Berlin",
              "buyerPostCode": "10115",
              "buyerCountrySubdivision": "",
              "buyerCountryCode": "DE"
            },
            "buyerContact": {
              "buyerContactPoint": "",
              "buyerContactTelephoneNumber": "+49 30 12345678",
              "buyerContactEmailAddress": "rechnung@mueller-mayer.de"
            }
          },
          "payee": {
            "payeeName": "",
            "payeeIdentifier": "",
            "payeeLegalRegistrationIdentifier": ""
          },
          "sellerTaxRepresentativeParty": {
            "sellerTaxRepresentativeName": "",
            "sellerTaxRepresentativeVatIdentifier": "",
            "sellerTaxRepresentativePostalAddress": {
              "taxRepresentativeAddressLine1": "",
              "taxRepresentativeAddressLine2": "",
              "taxRepresentativeAddressLine3": "",
              "taxRepresentativeCity": "",
              "taxRepresentativePostCode": "",
              "taxRepresentativeCountrySubdivision": "",
              "taxRepresentativeCountryCode": ""
            }
          },
          "deliveryInformation": null,
          "invoicingPeriod": {
            "invoicingPeriodStartDate": null,
            "invoicingPeriodEndDate": null
          },
          "paymentInstructions": {
            "paymentMeansTypeCode": "58",
            "paymentMeansText": "SEPA-Überweisung",
            "remittanceInformation": "RE-2025-001",
            "creditTransfer": [
              {
                "paymentAccountIdentifier": "DE89370400440532013000",
                "paymentAccountName": "Ihre Firma GmbH",
                "paymentServiceProviderIdentifier": "COBADEFFXXX"
              }
            ],
            "paymentCardInformation": {
              "paymentCardPrimaryAccountNumber": "",
              "paymentCardHolderName": ""
            },
            "directDebit": {
              "mandateReferenceIdentifier": "",
              "bankAssignedCreditorIdentifier": "",
              "debitedAccountIdentifier": ""
            }
          },
          "documentLevelAllowances": [],
          "documentLevelCharges": [],
          "documentTotals": {
            "sumOfInvoiceLineNetAmount": 1799,
            "sumOfAllowancesOnDocumentLevel": 0,
            "sumOfChargesOnDocumentLevel": 0,
            "invoiceTotalAmountWithoutVat": 1799,
            "invoiceTotalVatAmount": 341.81,
            "invoiceTotalVatAmountInAccountingCurrency": 0,
            "invoiceTotalAmountWithVat": 2140.81,
            "paidAmount": 0,
            "roundingAmount": 0,
            "amountDueForPayment": 2140.81
          },
          "vatBreakdown": [
            {
              "vatCategoryTaxableAmount": 1799,
              "vatCategoryTaxAmount": 341.81,
              "vatCategoryCode": "S",
              "vatCategoryRate": 19,
              "vatExemptionReasonText": "",
              "vatExemptionReasonCode": ""
            }
          ],
          "additionalSupportingDocuments": [],
          "invoiceLine": [
            {
              "invoiceLineIdentifier": "1",
              "invoiceLineNote": "",
              "invoiceLineObjectIdentifier": "",
              "invoicedQuantity": 10,
              "invoicedQuantityUnitOfMeasureCode": "HUR",
              "invoiceLineNetAmount": 1200,
              "referencedPurchaseOrderLineReference": "",
              "invoiceLineBuyerAccountingReference": "",
              "invoiceLinePeriod": {
                "invoiceLinePeriodStartDate": null,
                "invoiceLinePeriodEndDate": null
              },
              "invoiceLineAllowances": [],
              "invoiceLineCharges": [],
              "priceDetails": {
                "itemNetPrice": 120,
                "itemPriceDiscount": 0,
                "itemGrossPrice": 120,
                "itemPriceBaseQuantity": 1,
                "itemPriceBaseQuantityUnitOfMeasure": "HUR"
              },
              "lineVatInformation": [
                {
                  "invoicedItemVatCategoryCode": "S",
                  "invoicedItemVatRate": 19
                }
              ],
              "itemInformation": {
                "itemName": "Beratung & Projektbegleitung",
                "itemDescription": "",
                "itemSellersIdentifier": "",
                "itemBuyersIdentifier": "",
                "itemStandardIdentifier": "",
                "itemStandardIdentifierSchemeIdentifier": "",
                "itemClassificationIdentifier": [],
                "itemCountryOfOrigin": "",
                "itemAttributes": []
              }
            }
          ]
        }
      ]
    }

    Beispielantwort

    json
    {
      "message": "xInvoice generated",
      "valid": false,
      "numberOfXInvoiceErrors": 10,
      "xInvoiceErrors": [
        {
          "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
          "schemaFile": "EN16931-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
          "id": "BR-CO-25",
          "line": null
        },
        {
          "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
          "schemaFile": "XRechnung-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
          "id": "BR-DE-15",
          "line": null
        }
      ],
      "xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793267782_Hk3VnB8sQwXc5MtYj2PdLr7EaUf9ZoGi",
      "resendToken": "",
      "invoice": [
        {
          "invoiceNumber": "RE-2025-002",
          "invoiceIssueDate": "2026-02-16T00:00:00+01:00",
          "…": "the complete normalised invoice, same structure as in the response above"
        }
      ]
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    POST/api/v1/zugferd/createZugferdFromJson

    ZUGFeRD 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.
    FieldTypeRequiredDescription
    invoiceobjectrequiredRechnungsobjekt.
    invoicePdf64string (base64)requiredBase64-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",
            "supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
            "attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
          }
        ],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "String | BT-126",
            "invoiceLineNote": "String | BT-127",
            "invoiceLineObjectIdentifier": "String | BT-128",
            "invoicedQuantity": "Decimal | BT-129",
            "invoicedQuantityUnitOfMeasureCode": "String | BT-130",
            "invoiceLineNetAmount": "Decimal | BT-131",
            "referencedPurchaseOrderLineReference": "String | BT-132",
            "invoiceLineBuyerAccountingReference": "String | BT-133",
            "invoiceLinePeriod": {
              "invoiceLinePeriodStartDate": "Date | BT-134",
              "invoiceLinePeriodEndDate": "Date | BT-135"
            },
            "invoiceLineAllowances": [
              {
                "invoiceLineAllowanceAmount": "Decimal | BT-136",
                "invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
                "invoiceLineAllowancePercentage": "Decimal | BT-138",
                "invoiceLineAllowanceReason": "String | BT-139",
                "invoiceLineAllowanceReasonCode": "String | BT-140"
              }
            ],
            "invoiceLineCharges": [
              {
                "invoiceLineChargeAmount": "Decimal | BT-141",
                "invoiceLineChargeBaseAmount": "Decimal | BT-142",
                "invoiceLineChargePercentage": "Decimal | BT-143",
                "invoiceLineChargeReason": "String | BT-144",
                "invoiceLineChargeReasonCode": "String | BT-145"
              }
            ],
            "priceDetails": {
              "itemNetPrice": "Decimal | BT-146",
              "itemPriceDiscount": "Decimal | BT-147",
              "itemGrossPrice": "Decimal | BT-148",
              "itemPriceBaseQuantity": "Decimal | BT-149",
              "itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "String | BT-151",
                "invoicedItemVatRate": "Decimal | BT-152"
              }
            ],
            "itemInformation": {
              "itemName": "String | BT-153",
              "itemDescription": "String | BT-154",
              "itemSellersIdentifier": "String | BT-155",
              "itemBuyersIdentifier": "String | BT-156",
              "itemStandardIdentifier": "String | BT-157",
              "itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
              "itemClassificationIdentifier": [
                {
                  "itemClassificationIdentifier": "String | BT-158",
                  "itemClassificationIdentifierListIdentifier": "String | BT-158-1",
                  "itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
                }
              ],
              "itemCountryOfOrigin": "String | BT-159",
              "itemAttributes": [
                {
                  "itemAttributeName": "String | BT-160",
                  "itemAttributeValue": "String | BT-161"
                }
              ]
            }
          }
        ]
      },
      "invoicePdf64": "JVBERi0xLjQK...",
      "transport": {
        "type": "email",
        "useTransport": true,
        "sender": "rechnung@ihre-domain.de",
        "senderName": "Ihre Firma GmbH",
        "receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
        "cc": "steuerberater@kanzlei.de",
        "bcc": "archiv@ihre-domain.de",
        "subject": "Rechnung {invoicenumber} vom {invoicedate}",
        "message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
        "attachments": [
          {
            "fileName": "Leistungsnachweis.pdf",
            "fileBase64": "<base64>"
          }
        ]
      }
    }

    Beispielantwort

    json
    {
      "message": "ZUGFeRD created",
      "xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
      "zugferd": "JVBERi0xLjcKJaLN+vwK...",
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793359631_NbRS0bMYy68cicTsBocYzDK8MHCAFIz0",
      "resendToken": "",
      "xInvoiceValid": true,
      "zugferdValid": true,
      "numberOfxInvoiceErrors": 0,
      "numberOfZugferdErrors": 0,
      "xInvoiceErrorList": [],
      "zugferdErrorList": [],
      "invoiceJson": [
        {
          "invoiceNumber": "RE-2025-001",
          "invoiceIssueDate": "2026-02-16T00:00:00+01:00",
          "invoiceTypeCode": "380",
          "invoiceCurrencyCode": "EUR",
          "vatAccountingCurrencyCode": null,
          "valueAddedTaxPointDate": null,
          "valueAddedTaxPointDateCode": "",
          "paymentDueDate": "2026-03-02T00:00:00+01:00",
          "buyerReference": "BEST-2025-042",
          "projectReference": {
            "projectReferenceIdentifier": "",
            "projectReferenceName": ""
          },
          "contractReference": "",
          "purchaseOrderReference": "",
          "salesOrderReference": "",
          "receivingAdviceReference": "",
          "despatchAdviceReference": "",
          "tenderOrLotReference": null,
          "invoicedObjectIdentifier": null,
          "buyerAccountingReference": "Sachkonto 12000",
          "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
          "invoiceNote": [],
          "processControl": {
            "businessProcessTypeIdentifier": "",
            "specificationIdentifier": ""
          },
          "precedingInvoiceReference": [],
          "seller": {
            "sellerName": "Ihre Firma GmbH",
            "sellerTradingName": "",
            "sellerIdentifier": [],
            "sellerLegalRegistrationIdentifier": "HRB 67890 B",
            "sellerVatIdentifier": "DE123456789",
            "sellerTaxRegistrationIdentifier": "12/345/67890",
            "sellerAdditionalLegalInformation": "",
            "sellerElectronicAddress": "info@ihre-firma.de",
            "sellerPostalAddress": {
              "sellerAddressLine1": "Musterstraße 1",
              "sellerAddressLine2": "",
              "sellerAddressLine3": "",
              "sellerCity": "Berlin",
              "sellerPostCode": "12345",
              "sellerCountrySubdivision": "",
              "sellerCountryCode": "DE"
            },
            "sellerContact": {
              "sellerContactPoint": "Vertrieb",
              "sellerContactTelephoneNumber": "+49 30 9876543",
              "sellerContactEmailAddress": "info@ihre-firma.de"
            }
          },
          "buyer": {
            "buyerName": "Müller und Mayer GmbH",
            "buyerTradingName": "",
            "buyerIdentifier": "",
            "buyerLegalRegistrationIdentifier": "HRB 12345",
            "buyerVatIdentifier": "DE987654321",
            "buyerElectronicAddress": "rechnung@mueller-mayer.de",
            "buyerPostalAddress": {
              "buyerAddressLine1": "Kundenstraße 42",
              "buyerAddressLine2": "",
              "buyerAddressLine3": "",
              "buyerCity": "Berlin",
              "buyerPostCode": "10115",
              "buyerCountrySubdivision": "",
              "buyerCountryCode": "DE"
            },
            "buyerContact": {
              "buyerContactPoint": "",
              "buyerContactTelephoneNumber": "+49 30 12345678",
              "buyerContactEmailAddress": "rechnung@mueller-mayer.de"
            }
          },
          "payee": {
            "payeeName": "",
            "payeeIdentifier": "",
            "payeeLegalRegistrationIdentifier": ""
          },
          "sellerTaxRepresentativeParty": {
            "sellerTaxRepresentativeName": "",
            "sellerTaxRepresentativeVatIdentifier": "",
            "sellerTaxRepresentativePostalAddress": {
              "taxRepresentativeAddressLine1": "",
              "taxRepresentativeAddressLine2": "",
              "taxRepresentativeAddressLine3": "",
              "taxRepresentativeCity": "",
              "taxRepresentativePostCode": "",
              "taxRepresentativeCountrySubdivision": "",
              "taxRepresentativeCountryCode": ""
            }
          },
          "deliveryInformation": null,
          "invoicingPeriod": {
            "invoicingPeriodStartDate": null,
            "invoicingPeriodEndDate": null
          },
          "paymentInstructions": {
            "paymentMeansTypeCode": "58",
            "paymentMeansText": "SEPA-Überweisung",
            "remittanceInformation": "RE-2025-001",
            "creditTransfer": [
              {
                "paymentAccountIdentifier": "DE89370400440532013000",
                "paymentAccountName": "Ihre Firma GmbH",
                "paymentServiceProviderIdentifier": "COBADEFFXXX"
              }
            ],
            "paymentCardInformation": {
              "paymentCardPrimaryAccountNumber": "",
              "paymentCardHolderName": ""
            },
            "directDebit": {
              "mandateReferenceIdentifier": "",
              "bankAssignedCreditorIdentifier": "",
              "debitedAccountIdentifier": ""
            }
          },
          "documentLevelAllowances": [],
          "documentLevelCharges": [],
          "documentTotals": {
            "sumOfInvoiceLineNetAmount": 1799,
            "sumOfAllowancesOnDocumentLevel": 0,
            "sumOfChargesOnDocumentLevel": 0,
            "invoiceTotalAmountWithoutVat": 1799,
            "invoiceTotalVatAmount": 341.81,
            "invoiceTotalVatAmountInAccountingCurrency": 0,
            "invoiceTotalAmountWithVat": 2140.81,
            "paidAmount": 0,
            "roundingAmount": 0,
            "amountDueForPayment": 2140.81
          },
          "vatBreakdown": [
            {
              "vatCategoryTaxableAmount": 1799,
              "vatCategoryTaxAmount": 341.81,
              "vatCategoryCode": "S",
              "vatCategoryRate": 19,
              "vatExemptionReasonText": "",
              "vatExemptionReasonCode": ""
            }
          ],
          "additionalSupportingDocuments": [],
          "invoiceLine": [
            {
              "invoiceLineIdentifier": "1",
              "invoiceLineNote": "",
              "invoiceLineObjectIdentifier": "",
              "invoicedQuantity": 10,
              "invoicedQuantityUnitOfMeasureCode": "HUR",
              "invoiceLineNetAmount": 1200,
              "referencedPurchaseOrderLineReference": "",
              "invoiceLineBuyerAccountingReference": "",
              "invoiceLinePeriod": {
                "invoiceLinePeriodStartDate": null,
                "invoiceLinePeriodEndDate": null
              },
              "invoiceLineAllowances": [],
              "invoiceLineCharges": [],
              "priceDetails": {
                "itemNetPrice": 120,
                "itemPriceDiscount": 0,
                "itemGrossPrice": 120,
                "itemPriceBaseQuantity": 1,
                "itemPriceBaseQuantityUnitOfMeasure": "HUR"
              },
              "lineVatInformation": [
                {
                  "invoicedItemVatCategoryCode": "S",
                  "invoicedItemVatRate": 19
                }
              ],
              "itemInformation": {
                "itemName": "Beratung & Projektbegleitung",
                "itemDescription": "",
                "itemSellersIdentifier": "",
                "itemBuyersIdentifier": "",
                "itemStandardIdentifier": "",
                "itemStandardIdentifierSchemeIdentifier": "",
                "itemClassificationIdentifier": [],
                "itemCountryOfOrigin": "",
                "itemAttributes": []
              }
            }
          ]
        }
      ],
      "invoice": [
        {
          "invoiceNumber": "RE-2025-001",
          "invoiceIssueDate": "2026-02-16T00:00:00+01:00",
          "invoiceTypeCode": "380",
          "invoiceCurrencyCode": "EUR",
          "vatAccountingCurrencyCode": null,
          "valueAddedTaxPointDate": null,
          "valueAddedTaxPointDateCode": "",
          "paymentDueDate": "2026-03-02T00:00:00+01:00",
          "buyerReference": "BEST-2025-042",
          "projectReference": {
            "projectReferenceIdentifier": "",
            "projectReferenceName": ""
          },
          "contractReference": "",
          "purchaseOrderReference": "",
          "salesOrderReference": "",
          "receivingAdviceReference": "",
          "despatchAdviceReference": "",
          "tenderOrLotReference": null,
          "invoicedObjectIdentifier": null,
          "buyerAccountingReference": "Sachkonto 12000",
          "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
          "invoiceNote": [],
          "processControl": {
            "businessProcessTypeIdentifier": "",
            "specificationIdentifier": ""
          },
          "precedingInvoiceReference": [],
          "seller": {
            "sellerName": "Ihre Firma GmbH",
            "sellerTradingName": "",
            "sellerIdentifier": [],
            "sellerLegalRegistrationIdentifier": "HRB 67890 B",
            "sellerVatIdentifier": "DE123456789",
            "sellerTaxRegistrationIdentifier": "12/345/67890",
            "sellerAdditionalLegalInformation": "",
            "sellerElectronicAddress": "info@ihre-firma.de",
            "sellerPostalAddress": {
              "sellerAddressLine1": "Musterstraße 1",
              "sellerAddressLine2": "",
              "sellerAddressLine3": "",
              "sellerCity": "Berlin",
              "sellerPostCode": "12345",
              "sellerCountrySubdivision": "",
              "sellerCountryCode": "DE"
            },
            "sellerContact": {
              "sellerContactPoint": "Vertrieb",
              "sellerContactTelephoneNumber": "+49 30 9876543",
              "sellerContactEmailAddress": "info@ihre-firma.de"
            }
          },
          "buyer": {
            "buyerName": "Müller und Mayer GmbH",
            "buyerTradingName": "",
            "buyerIdentifier": "",
            "buyerLegalRegistrationIdentifier": "HRB 12345",
            "buyerVatIdentifier": "DE987654321",
            "buyerElectronicAddress": "rechnung@mueller-mayer.de",
            "buyerPostalAddress": {
              "buyerAddressLine1": "Kundenstraße 42",
              "buyerAddressLine2": "",
              "buyerAddressLine3": "",
              "buyerCity": "Berlin",
              "buyerPostCode": "10115",
              "buyerCountrySubdivision": "",
              "buyerCountryCode": "DE"
            },
            "buyerContact": {
              "buyerContactPoint": "",
              "buyerContactTelephoneNumber": "+49 30 12345678",
              "buyerContactEmailAddress": "rechnung@mueller-mayer.de"
            }
          },
          "payee": {
            "payeeName": "",
            "payeeIdentifier": "",
            "payeeLegalRegistrationIdentifier": ""
          },
          "sellerTaxRepresentativeParty": {
            "sellerTaxRepresentativeName": "",
            "sellerTaxRepresentativeVatIdentifier": "",
            "sellerTaxRepresentativePostalAddress": {
              "taxRepresentativeAddressLine1": "",
              "taxRepresentativeAddressLine2": "",
              "taxRepresentativeAddressLine3": "",
              "taxRepresentativeCity": "",
              "taxRepresentativePostCode": "",
              "taxRepresentativeCountrySubdivision": "",
              "taxRepresentativeCountryCode": ""
            }
          },
          "deliveryInformation": null,
          "invoicingPeriod": {
            "invoicingPeriodStartDate": null,
            "invoicingPeriodEndDate": null
          },
          "paymentInstructions": {
            "paymentMeansTypeCode": "58",
            "paymentMeansText": "SEPA-Überweisung",
            "remittanceInformation": "RE-2025-001",
            "creditTransfer": [
              {
                "paymentAccountIdentifier": "DE89370400440532013000",
                "paymentAccountName": "Ihre Firma GmbH",
                "paymentServiceProviderIdentifier": "COBADEFFXXX"
              }
            ],
            "paymentCardInformation": {
              "paymentCardPrimaryAccountNumber": "",
              "paymentCardHolderName": ""
            },
            "directDebit": {
              "mandateReferenceIdentifier": "",
              "bankAssignedCreditorIdentifier": "",
              "debitedAccountIdentifier": ""
            }
          },
          "documentLevelAllowances": [],
          "documentLevelCharges": [],
          "documentTotals": {
            "sumOfInvoiceLineNetAmount": 1799,
            "sumOfAllowancesOnDocumentLevel": 0,
            "sumOfChargesOnDocumentLevel": 0,
            "invoiceTotalAmountWithoutVat": 1799,
            "invoiceTotalVatAmount": 341.81,
            "invoiceTotalVatAmountInAccountingCurrency": 0,
            "invoiceTotalAmountWithVat": 2140.81,
            "paidAmount": 0,
            "roundingAmount": 0,
            "amountDueForPayment": 2140.81
          },
          "vatBreakdown": [
            {
              "vatCategoryTaxableAmount": 1799,
              "vatCategoryTaxAmount": 341.81,
              "vatCategoryCode": "S",
              "vatCategoryRate": 19,
              "vatExemptionReasonText": "",
              "vatExemptionReasonCode": ""
            }
          ],
          "additionalSupportingDocuments": [],
          "invoiceLine": [
            {
              "invoiceLineIdentifier": "1",
              "invoiceLineNote": "",
              "invoiceLineObjectIdentifier": "",
              "invoicedQuantity": 10,
              "invoicedQuantityUnitOfMeasureCode": "HUR",
              "invoiceLineNetAmount": 1200,
              "referencedPurchaseOrderLineReference": "",
              "invoiceLineBuyerAccountingReference": "",
              "invoiceLinePeriod": {
                "invoiceLinePeriodStartDate": null,
                "invoiceLinePeriodEndDate": null
              },
              "invoiceLineAllowances": [],
              "invoiceLineCharges": [],
              "priceDetails": {
                "itemNetPrice": 120,
                "itemPriceDiscount": 0,
                "itemGrossPrice": 120,
                "itemPriceBaseQuantity": 1,
                "itemPriceBaseQuantityUnitOfMeasure": "HUR"
              },
              "lineVatInformation": [
                {
                  "invoicedItemVatCategoryCode": "S",
                  "invoicedItemVatRate": 19
                }
              ],
              "itemInformation": {
                "itemName": "Beratung & Projektbegleitung",
                "itemDescription": "",
                "itemSellersIdentifier": "",
                "itemBuyersIdentifier": "",
                "itemStandardIdentifier": "",
                "itemStandardIdentifierSchemeIdentifier": "",
                "itemClassificationIdentifier": [],
                "itemCountryOfOrigin": "",
                "itemAttributes": []
              }
            }
          ]
        }
      ]
    }

    Antwortfelder

    FieldTypeDescription
    messagestringStatustext, `ZUGFeRD created`.
    xInvoicestringDas aus Ihren Rechnungsdaten erzeugte und ins PDF eingebettete XRechnungs-XML (UTF-8), inline zurückgegeben.
    zugferdstring (base64)Das ZUGFeRD-PDF/A-3, Base64-kodiert — auch wenn die Validierung Fehler gefunden hat.
    downloadURLstring (url)Link zur erzeugten Datei. Er lässt sich ohne Authorization-Header öffnen — jeder, der den Link kennt, kann sie herunterladen. Behandeln Sie ihn wie ein Geheimnis.
    resendTokenstringLeerer String `""`, wenn keine E-Mail versendet wurde. Wurde `transport` bei einem gültigen Dokument genutzt, der Token für `sendEmailWithZugferdData` — siehe E-Mail-Versand.
    xInvoiceValidboolean`true`, wenn das erzeugte XML die Validierung bestanden hat (`xInvoiceErrorList` ist leer).
    zugferdValidboolean`true`, wenn das fertige ZUGFeRD-PDF die Validierung bestanden hat (`zugferdErrorList` ist leer).
    numberOfxInvoiceErrorsintegerAnzahl der Einträge in `xInvoiceErrorList`. Beachten Sie das kleine `x` in diesem Namen.
    numberOfZugferdErrorsintegerAnzahl der Einträge in `zugferdErrorList`.
    xInvoiceErrorListarrayValidierungsbefunde zum erzeugten XML; leer, wenn `xInvoiceValid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    xInvoiceErrorList[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    xInvoiceErrorList[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    xInvoiceErrorList[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    xInvoiceErrorList[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    xInvoiceErrorList[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    xInvoiceErrorList[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.
    zugferdErrorListarrayValidierungsbefunde zum fertigen ZUGFeRD-PDF; leer, wenn `zugferdValid` `true` ist. Dieselben Eigenschaften wie oben.
    invoiceJsonarrayEin Array mit einem Element: die Rechnung, wie das System sie verstanden hat — das vollständige Rechnungsobjekt, normalisiert (siehe `createXinvoiceFromJson`). Identisch mit `invoice`.
    invoicearrayDieselbe normalisierte Rechnung wie in `invoiceJson`, unter dem Namen wiederholt, den auch `createXinvoiceFromJson` verwendet.

    Beispielantwort

    json
    {
      "message": "ZUGFeRD created",
      "xInvoice": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>",
      "zugferd": "JVBERi0xLjcKJaLN+vwK...",
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793364463_3uLBx0wWp4ABuFRtYQFzpqzQ0MGthdNV",
      "resendToken": "",
      "xInvoiceValid": false,
      "zugferdValid": false,
      "numberOfxInvoiceErrors": 3,
      "numberOfZugferdErrors": 3,
      "xInvoiceErrorList": [
        {
          "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
          "schemaFile": "XRechnung-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
          "id": "BR-DE-15",
          "line": null
        },
        {
          "message": "[BR-DE-6] Das Element \"Seller contact telephone number\" (BT-42) muss übermittelt werden.",
          "schemaFile": "XRechnung-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeAgreement[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}SellerTradeParty[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}DefinedTradeContact[1]",
          "id": "BR-DE-6",
          "line": null
        }
      ],
      "zugferdErrorList": [
        {
          "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
          "schemaFile": "XRechnung-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
          "id": "BR-DE-15",
          "line": null
        }
      ],
      "invoiceJson": [
        {
          "invoiceNumber": "RE-2025-002",
          "…": "the complete normalised invoice, same structure as in the response above"
        }
      ],
      "invoice": [
        {
          "invoiceNumber": "RE-2025-002",
          "…": "the complete normalised invoice, same structure as in the response above"
        }
      ]
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    POST/api/v1/zugferd/createZugferdPdfFromXinvoice

    ZUGFeRD-PDF aus XRechnung erstellen

    Erstellt ein ZUGFeRD-konformes PDF/A-3, indem eine vorhandene XRechnungs-XML in ein PDF-Dokument eingebettet wird.

    FieldTypeRequiredDescription
    xInvoiceXmlstringrequiredXRechnungs-XML als String.
    invoicePdf64string (base64)requiredBase64-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
    {
      "message": "zugferd created",
      "valid": false,
      "numberOfZugferdErrors": 1,
      "zugferdErrors": [
        {
          "message": "[PEPPOL-EN16931-R008]-Document MUST not contain empty elements.",
          "schemaFile": "XRechnung-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeDelivery[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ShipToTradeParty[1]",
          "id": "PEPPOL-EN16931-R008",
          "line": null
        }
      ],
      "zugferdFile": "JVBERi0xLjcKJaOIwOMKMyAwIG9iago...",
      "createdInvoice": [
        {
          "invoiceNumber": "RE-2025-001",
          "…": "the complete invoice the PDF was built from — same structure as the Invoice Object"
        }
      ],
      "extractedInvoice": [
        {
          "invoiceNumber": "RE-2025-001",
          "…": "the complete invoice read back from the finished ZUGFeRD — same structure as `extractedInvoice` of extractXInvoiceFromZugferdToJson, but wrapped in an array"
        }
      ],
      "validXRechnung": true,
      "xrechnungErrors": []
    }

    Antwortfelder

    FieldTypeDescription
    messagestringStatustext, `zugferd created`.
    validboolean`true`, wenn das fertige ZUGFeRD-PDF die Validierung bestanden hat (`zugferdErrors` ist leer). Das PDF wird in jedem Fall zurückgegeben.
    numberOfZugferdErrorsintegerAnzahl der Einträge in `zugferdErrors`.
    zugferdErrorsarrayValidierungsbefunde zum fertigen ZUGFeRD-PDF; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    zugferdErrors[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    zugferdErrors[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    zugferdErrors[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrors[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrors[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    zugferdErrors[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.
    zugferdFilestring (base64)Das ZUGFeRD-PDF/A-3, Base64-kodiert.
    createdInvoicearrayEin Array mit einem Element: die Rechnungsdaten, aus denen das PDF gebaut wurde, d. h. Ihr XML, geparst in die Struktur des Rechnungsobjekts.
    extractedInvoicearrayEin Array mit einem Element: die aus dem fertigen ZUGFeRD zurückgelesenen Rechnungsdaten, in derselben Form wie das `extractedInvoice` von `extractXInvoiceFromZugferdToJson` — hier aber in ein Array verpackt.
    validXRechnungboolean`true`, wenn das von Ihnen übergebene XML die XRechnung-Validierung bestanden hat (`xrechnungErrors` ist leer).
    xrechnungErrorsarrayValidierungsbefunde zum übergebenen XML, in derselben Form wie `zugferdErrors`; leer, wenn `validXRechnung` `true` ist.

    Playground

    Diesen Endpunkt live im Browser testen.

    POST/api/v1/zugferd/createInvoicePdfFromJson

    ZUGFeRD-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.
    FieldTypeRequiredDescription
    invoiceobjectrequiredRechnungsobjekt.
    templateIdstringrequiredID des Templates für die PDF-Erzeugung.
    invoiceFilenamestringoptionalEigener 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.
    invoicePassthroughbooleanoptionalStandardmäßig true. Jede erzeugte Rechnung erhält einen Eintrag in der Rechnungsliste Ihres Kontos. Bei true wird das Dokument selbst nicht gespeichert – es wird nur in der Response zurückgegeben, speichern Sie es von dort. Auf false setzen, um zusätzlich das Dokument zu speichern, sodass es später in der Rechnungsliste angesehen und heruntergeladen werden kann. Hinweis zur Seite „Rechnung erstellen" im Dashboard: Dort wird dies als Frage „Möchten Sie das Rechnungsdokument speichern?" mit Ja/Nein dargestellt (Nein vorausgewählt) – „Nein“ sendet invoicePassthrough: true (Standard), „Ja“ sendet invoicePassthrough: false.

    Beispiel

    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",
            "supportingDocumentTypeCodex": "Integer | UNTDID 1001 document type code, e.g. 916",
            "attachedDocumentFilename": "String | File name of attachedDocument (BT-125)"
          }
        ],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "String | BT-126",
            "invoiceLineNote": "String | BT-127",
            "invoiceLineObjectIdentifier": "String | BT-128",
            "invoicedQuantity": "Decimal | BT-129",
            "invoicedQuantityUnitOfMeasureCode": "String | BT-130",
            "invoiceLineNetAmount": "Decimal | BT-131",
            "referencedPurchaseOrderLineReference": "String | BT-132",
            "invoiceLineBuyerAccountingReference": "String | BT-133",
            "invoiceLinePeriod": {
              "invoiceLinePeriodStartDate": "Date | BT-134",
              "invoiceLinePeriodEndDate": "Date | BT-135"
            },
            "invoiceLineAllowances": [
              {
                "invoiceLineAllowanceAmount": "Decimal | BT-136",
                "invoiceLineAllowanceBaseAmount": "Decimal | BT-137",
                "invoiceLineAllowancePercentage": "Decimal | BT-138",
                "invoiceLineAllowanceReason": "String | BT-139",
                "invoiceLineAllowanceReasonCode": "String | BT-140"
              }
            ],
            "invoiceLineCharges": [
              {
                "invoiceLineChargeAmount": "Decimal | BT-141",
                "invoiceLineChargeBaseAmount": "Decimal | BT-142",
                "invoiceLineChargePercentage": "Decimal | BT-143",
                "invoiceLineChargeReason": "String | BT-144",
                "invoiceLineChargeReasonCode": "String | BT-145"
              }
            ],
            "priceDetails": {
              "itemNetPrice": "Decimal | BT-146",
              "itemPriceDiscount": "Decimal | BT-147",
              "itemGrossPrice": "Decimal | BT-148",
              "itemPriceBaseQuantity": "Decimal | BT-149",
              "itemPriceBaseQuantityUnitOfMeasure": "String | BT-150"
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "String | BT-151",
                "invoicedItemVatRate": "Decimal | BT-152"
              }
            ],
            "itemInformation": {
              "itemName": "String | BT-153",
              "itemDescription": "String | BT-154",
              "itemSellersIdentifier": "String | BT-155",
              "itemBuyersIdentifier": "String | BT-156",
              "itemStandardIdentifier": "String | BT-157",
              "itemStandardIdentifierSchemeIdentifier": "String | BT-157-1",
              "itemClassificationIdentifier": [
                {
                  "itemClassificationIdentifier": "String | BT-158",
                  "itemClassificationIdentifierListIdentifier": "String | BT-158-1",
                  "itemClassificationIdentifierListVersionIdentifier": "String | BT-158-2"
                }
              ],
              "itemCountryOfOrigin": "String | BT-159",
              "itemAttributes": [
                {
                  "itemAttributeName": "String | BT-160",
                  "itemAttributeValue": "String | BT-161"
                }
              ]
            }
          }
        ]
      },
      "transport": {
        "type": "email",
        "useTransport": true,
        "sender": "rechnung@ihre-domain.de",
        "senderName": "Ihre Firma GmbH",
        "receiver": "buchhaltung@kunde.de, rechnungen@kunde.de",
        "cc": "steuerberater@kanzlei.de",
        "bcc": "archiv@ihre-domain.de",
        "subject": "Rechnung {invoicenumber} vom {invoicedate}",
        "message": "<p>Guten Tag,</p><p>anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.</p>",
        "attachments": [
          {
            "fileName": "Leistungsnachweis.pdf",
            "fileBase64": "<base64>"
          }
        ]
      }
    }

    Beispielantwort

    json
    {
      "message": "pdf created, downloaded and not stored in DMS",
      "iqDataId": 136951,
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793363431_Zk4NpQ8sVtYw2RbJc7XmH5LdFe9GuAo3",
      "resendToken": "ttsYDNZrEj9JZO12rSH5w4JwM/w7VJjEEyjcTWHj2sWa/4tV6f72K9PP6YkqkO46/d9aTLWtWAofRJxx70/RVg==",
      "fileName": "my-custom-invoice-name.pdf",
      "fileExtension": "pdf",
      "fileSize": 99288,
      "filecontentB64": "JVBERi0xLjcK...",
      "zugferdIsValid": true,
      "zugferdErrors": []
    }

    Antwortfelder

    FieldTypeDescription
    messagestringStatustext: `pdf created, downloaded and stored in DMS`, wenn `invoicePassthrough` auf `false` steht, sonst `pdf created, downloaded and not stored in DMS`.
    iqDataIdintegerID des Eintrags, der in der Rechnungsliste Ihres Kontos angelegt wurde. `0` bei einer Idempotency-Key-Wiederholung.
    downloadURLstring (url)Link zum erzeugten PDF (`Content-Type: application/pdf`). Er lässt sich ohne Authorization-Header öffnen — jeder, der den Link kennt, kann die Datei herunterladen. Behandeln Sie ihn wie ein Geheimnis.
    resendTokenstringLeerer String `""`, wenn keine E-Mail versendet wurde. Wurde `transport` bei einem gültigen Dokument genutzt, der Token für `sendEmailWithZugferdData` — siehe E-Mail-Versand. Bei einer Idempotency-Key-Wiederholung nicht vorhanden.
    fileNamestringDateiname des PDFs — Ihr `invoiceFilename`, falls Sie einen mitgeschickt haben. Ohne Angabe erzeugt die API einen Namen, der nicht zum Lesen gedacht ist: Er enthält ein unleserliches Suffix und endet derzeit auf `.pdf.pdf`. Setzen Sie `invoiceFilename`, wenn der Name wichtig ist, z. B. für E-Mail-Anhänge.
    fileExtensionstringDateiendung, `pdf`.
    fileSizeintegerGröße des PDFs in Bytes.
    filecontentB64string (base64)Das erzeugte ZUGFeRD-PDF, Base64-kodiert. Das ist das Dokument selbst; `downloadURL` verweist auf dieselbe Datei.
    zugferdIsValidboolean`true`, wenn die im PDF eingebetteten ZUGFeRD-Daten die Validierung bestanden haben.
    zugferdErrorsarrayValidierungsbefunde zum zurückgegebenen Dokument, in derselben Form wie `errorList` in der 412-Antwort; leer, wenn `zugferdIsValid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    zugferdErrors[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    zugferdErrors[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    zugferdErrors[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrors[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrors[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    zugferdErrors[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.

    Beispielantwort

    json
    {
      "message": "returned because of same itempotency-key",
      "iqDataId": 0,
      "documentId": 0,
      "fsNodeId": 0,
      "fileName": "my-custom-invoice-name.pdf",
      "fileExtension": "pdf",
      "fileSize": 99288,
      "filecontentB64": "JVBERi0xLjcK...",
      "downloadURL": "https://api.rechnungsapi.de/file/get/1793363429_Qx7LmN2pVd9RtKs4WbHy8CfJe1ZaGu3o",
      "zugferdIsValid": true,
      "zugferdErrors": []
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    E-Mail-Versand

    POST/api/v1/delivery

    Eigenstä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).

    FieldTypeRequiredDescription
    transport.typestringrequiredVersandkanal. Derzeit nur "email".
    transport.useTransportbooleanrequiredMuss auf true gesetzt sein, damit tatsächlich eine E-Mail versendet wird (siehe Response-Fall „nothing to do" unten).
    transport.email.sender / senderNamestringrequiredAbsender-E-Mail-Adresse und optionaler Anzeigename.
    transport.email.receiver / cc / bccstringrequiredEmpfänger; bei mehreren Adressen kommagetrennt.
    transport.email.subject / messagestringrequiredBetreff 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.contentobjectoptionalFreie 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.attachmentsarrayoptionalAnhä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 send."
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    POST/api/v1/sendEmailWithZugferdData

    E-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.

    FieldTypeRequiredDescription
    resendTokenstringrequiredDer 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/extractXinvoiceFromZugferdToJson

    XRechnung 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.

    FieldTypeRequiredDescription
    zugferd64string (base64)requiredDas ZUGFeRD-PDF-Dokument als Base64-kodierter String.

    Beispiel

    json
    {
      "zugferd64": "JVBERi0xLjcKJbe3wvUKMyAwIG9iago8PC9UeXBl..."
    }

    Beispielantwort

    json
    {
      "extractedInvoice": {
        "invoiceNumber": "RE-2025-001",
        "invoiceIssueDate": "2026-02-16T00:00:00+01:00",
        "invoiceTypeCode": "380",
        "invoiceCurrencyCode": "EUR",
        "vatAccountingCurrencyCode": null,
        "valueAddedTaxPointDate": null,
        "valueAddedTaxPointDateCode": "",
        "paymentDueDate": "2026-03-02T00:00:00+01:00",
        "buyerReference": "BEST-2025-042",
        "projectReference": {
          "projectReferenceIdentifier": "",
          "projectReferenceName": ""
        },
        "contractReference": "",
        "purchaseOrderReference": "",
        "salesOrderReference": "",
        "receivingAdviceReference": "",
        "despatchAdviceReference": "",
        "tenderOrLotReference": null,
        "invoicedObjectIdentifier": null,
        "buyerAccountingReference": "Sachkonto 12000",
        "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.",
        "invoiceNote": [],
        "processControl": {
          "businessProcessTypeIdentifier": "",
          "specificationIdentifier": ""
        },
        "precedingInvoiceReference": [],
        "seller": {
          "sellerName": "Ihre Firma GmbH",
          "sellerTradingName": "",
          "sellerIdentifier": [],
          "sellerLegalRegistrationIdentifier": "HRB 67890 B",
          "sellerVatIdentifier": "DE123456789",
          "sellerTaxRegistrationIdentifier": "12/345/67890",
          "sellerAdditionalLegalInformation": "",
          "sellerElectronicAddress": "info@ihre-firma.de",
          "sellerPostalAddress": {
            "sellerAddressLine1": "Musterstraße 1",
            "sellerAddressLine2": "",
            "sellerAddressLine3": "",
            "sellerCity": "Berlin",
            "sellerPostCode": "12345",
            "sellerCountrySubdivision": "",
            "sellerCountryCode": "DE"
          },
          "sellerContact": {
            "sellerContactPoint": "Vertrieb",
            "sellerContactTelephoneNumber": "+49 30 9876543",
            "sellerContactEmailAddress": "info@ihre-firma.de"
          }
        },
        "buyer": {
          "buyerName": "Müller und Mayer GmbH",
          "buyerTradingName": "",
          "buyerIdentifier": "",
          "buyerLegalRegistrationIdentifier": "HRB 12345",
          "buyerVatIdentifier": "DE987654321",
          "buyerElectronicAddress": "rechnung@mueller-mayer.de",
          "buyerPostalAddress": {
            "buyerAddressLine1": "Kundenstraße 42",
            "buyerAddressLine2": "",
            "buyerAddressLine3": "",
            "buyerCity": "Berlin",
            "buyerPostCode": "10115",
            "buyerCountrySubdivision": "",
            "buyerCountryCode": "DE"
          },
          "buyerContact": {
            "buyerContactPoint": "",
            "buyerContactTelephoneNumber": "+49 30 12345678",
            "buyerContactEmailAddress": "rechnung@mueller-mayer.de"
          }
        },
        "payee": {
          "payeeName": "",
          "payeeIdentifier": "",
          "payeeLegalRegistrationIdentifier": ""
        },
        "sellerTaxRepresentativeParty": {
          "sellerTaxRepresentativeName": "",
          "sellerTaxRepresentativeVatIdentifier": "",
          "sellerTaxRepresentativePostalAddress": {
            "taxRepresentativeAddressLine1": "",
            "taxRepresentativeAddressLine2": "",
            "taxRepresentativeAddressLine3": "",
            "taxRepresentativeCity": "",
            "taxRepresentativePostCode": "",
            "taxRepresentativeCountrySubdivision": "",
            "taxRepresentativeCountryCode": ""
          }
        },
        "deliveryInformation": {
          "deliverToPartyName": "",
          "deliverToLocationIdentifier": null,
          "actualDeliveryDate": null,
          "deliverToAddress": {
            "deliverToAddressLine1": "",
            "deliverToAddressLine2": "",
            "deliverToAddressLine3": "",
            "deliverToCity": "",
            "deliverToPostCode": "",
            "deliverToCountrySubdivision": null,
            "deliverToCountryCode": ""
          }
        },
        "invoicingPeriod": {
          "invoicingPeriodStartDate": null,
          "invoicingPeriodEndDate": null
        },
        "paymentInstructions": {
          "paymentMeansTypeCode": "58",
          "paymentMeansText": "SEPA-Überweisung",
          "remittanceInformation": "RE-2025-001",
          "creditTransfer": [
            {
              "paymentAccountIdentifier": "DE89370400440532013000",
              "paymentAccountName": "Ihre Firma GmbH",
              "paymentServiceProviderIdentifier": "COBADEFFXXX"
            }
          ],
          "paymentCardInformation": {
            "paymentCardPrimaryAccountNumber": "",
            "paymentCardHolderName": ""
          },
          "directDebit": {
            "mandateReferenceIdentifier": "",
            "bankAssignedCreditorIdentifier": "",
            "debitedAccountIdentifier": ""
          }
        },
        "documentLevelAllowances": [],
        "documentLevelCharges": [],
        "documentTotals": {
          "sumOfInvoiceLineNetAmount": 1799,
          "sumOfAllowancesOnDocumentLevel": 0,
          "sumOfChargesOnDocumentLevel": 0,
          "invoiceTotalAmountWithoutVat": 1799,
          "invoiceTotalVatAmount": 341.81,
          "invoiceTotalVatAmountInAccountingCurrency": 0,
          "invoiceTotalAmountWithVat": 2140.81,
          "paidAmount": 0,
          "roundingAmount": 0,
          "amountDueForPayment": 2140.81
        },
        "vatBreakdown": [
          {
            "vatCategoryTaxableAmount": 1799,
            "vatCategoryTaxAmount": 341.81,
            "vatCategoryCode": "S",
            "vatCategoryRate": 19,
            "vatExemptionReasonText": "",
            "vatExemptionReasonCode": ""
          }
        ],
        "additionalSupportingDocuments": [],
        "invoiceLine": [
          {
            "invoiceLineIdentifier": "1",
            "invoiceLineNote": "",
            "invoiceLineObjectIdentifier": "",
            "invoicedQuantity": 10,
            "invoicedQuantityUnitOfMeasureCode": "HUR",
            "invoiceLineNetAmount": 1200,
            "referencedPurchaseOrderLineReference": "",
            "invoiceLineBuyerAccountingReference": "",
            "invoiceLinePeriod": {
              "invoiceLinePeriodStartDate": null,
              "invoiceLinePeriodEndDate": null
            },
            "invoiceLineAllowances": [],
            "invoiceLineCharges": [],
            "priceDetails": {
              "itemNetPrice": 120,
              "itemPriceDiscount": 0,
              "itemGrossPrice": 120,
              "itemPriceBaseQuantity": 1,
              "itemPriceBaseQuantityUnitOfMeasure": "HUR"
            },
            "lineVatInformation": [
              {
                "invoicedItemVatCategoryCode": "S",
                "invoicedItemVatRate": 19
              }
            ],
            "itemInformation": {
              "itemName": "Beratung & Projektbegleitung",
              "itemDescription": "",
              "itemSellersIdentifier": "",
              "itemBuyersIdentifier": "",
              "itemStandardIdentifier": "",
              "itemStandardIdentifierSchemeIdentifier": "",
              "itemClassificationIdentifier": [],
              "itemCountryOfOrigin": "",
              "itemAttributes": [
                {
                  "itemAttributeName": null,
                  "itemAttributeValue": null
                }
              ]
            }
          }
        ]
      },
      "zugferdIsValid": true,
      "zugferdErrorlist": []
    }

    Antwortfelder

    FieldTypeDescription
    extractedInvoiceobject | nullDie eingebettete Rechnung als vollständiges Rechnungsobjekt (siehe unten). Jedes Feld ist vorhanden — nicht gesetzte Werte sind `""` oder `null`, nicht gesetzte Listen `[]`; Datumswerte sind ISO-8601-Zeitstempel mit UTC-Offset (z. B. `2026-02-16T00:00:00+01:00`). `null`, wenn das PDF kein lesbares XML enthält.
    zugferdIsValidboolean`true`, wenn das eingebettete XML die Validierung bestanden hat. `false` kommt mit HTTP 400 (siehe unten).
    zugferdErrorlistarrayValidierungsbefunde des eingebetteten XML; leer, wenn `zugferdIsValid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    zugferdErrorlist[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    zugferdErrorlist[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    zugferdErrorlist[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrorlist[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrorlist[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    zugferdErrorlist[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.

    Playground

    Diesen Endpunkt live im Browser testen.

    Validierung

    POST/api/v1/zugferd/validateXinvoiceXml

    XRechnung-XML validieren

    Validiert XRechnungs-XML (CII- oder UBL-Syntax) gegen EN 16931 und XRechnung-Business-Regeln. Gibt strukturierte Fehler mit Regel-IDs und Positionen zurück, damit Verstöße vor dem Versand behoben werden können. Besteht ein Dokument diese Regeln, laufen zusätzliche Prüfungen (USt-IdNr. des Verkäufers, Fälligkeitsdatum), und die Antwort weist zusätzlich getrennt aus, ob die IBAN in der Rechnung gültig ist (`isIbanValidInXML`). Welche dieser Felder zurückkommen, hängt davon ab, wie weit die Validierung kam — siehe die Beispielantworten.

    FieldTypeRequiredDescription
    xinvoiceXMLstringrequiredXRechnungs-XML-Inhalt als String.

    Beispiel

    json
    {
      "xinvoiceXML": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
    }

    Beispielantwort

    json
    {
      "message": "validated. (4649)",
      "isIbanValidInXML": true,
      "valid": true,
      "xInvoiceErrors": []
    }

    Antwortfelder

    FieldTypeDescription
    messagestring`validated. (<n>)`, wenn das Dokument die Schema- und Schematron-Regeln bestanden hat und damit auch die zusätzlichen Prüfungen liefen; `<n>` ist die Länge des übermittelten XML in Zeichen. Andernfalls `validation done` — siehe die Beispiele unten.
    validboolean`true`, wenn `xInvoiceErrors` keine Befunde enthält, sonst `false`.
    isIbanValidInXMLboolean`true`, wenn die IBAN in der Rechnung gültig ist; `false`, wenn sie ungültig ist oder das Dokument keine IBAN enthält. Wird unabhängig von `valid` ausgewiesen. Eine gültige IBAN bedeutet hier nur, dass Format und Prüfziffern stimmen – nicht, dass das Konto existiert oder wem es gehört. Nur vorhanden, wenn das Dokument die Schema- und Schematron-Regeln bestanden hat (`message: validated. (<n>)`).
    xInvoiceErrorsarrayAlle Befunde; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    xInvoiceErrors[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    xInvoiceErrors[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    xInvoiceErrors[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    xInvoiceErrors[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    xInvoiceErrors[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    xInvoiceErrors[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.

    Beispielantwort

    json
    {
      "message": "validated. (4544)",
      "isIbanValidInXML": true,
      "valid": false,
      "xInvoiceErrors": [
        {
          "message": "Verkäufer Vat ID ist ungültig",
          "schemaFile": "additional-validation",
          "type": "fatal",
          "location": "sellerVatId",
          "id": "",
          "line": ""
        },
        {
          "message": "Fälligkeitsdatum oder Zahlungsbedingungen nicht vorhanden.",
          "schemaFile": "additional-validation",
          "type": "fatal",
          "location": "dueDate",
          "id": "",
          "line": ""
        }
      ]
    }

    Beispielantwort

    json
    {
      "message": "validation done",
      "xmllength": 4413,
      "valid": false,
      "xInvoiceErrors": [
        {
          "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
          "schemaFile": "EN16931-CII-validation",
          "type": "fatal",
          "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
          "id": "BR-CO-25",
          "line": null
        }
      ]
    }

    Antwortfelder

    FieldTypeDescription
    xmllengthintegerLänge des übermittelten XML in Zeichen. Nur zusammen mit `message: validation done` vorhanden, sowie in der 412-Antwort.

    Beispielantwort

    json
    {
      "message": "validation done",
      "xmllength": 7,
      "valid": false,
      "xInvoiceErrors": [
        {
          "message": "The attached XML content is either corrupt or not parsable.",
          "schemaFile": null,
          "type": "fatal",
          "location": null,
          "id": null,
          "line": null
        }
      ]
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    POST/api/v1/zugferd/validateZugferdPdf

    ZUGFeRD-PDF validieren

    Validiert ein bestehendes ZUGFeRD-PDF inkl. eingebettetem XML gegen EN 16931. Liefert ein klares Bestanden/Nicht-bestanden mit einer detaillierten Fehlerliste. Die Antwort weist zusätzlich getrennt aus, ob die IBAN in der Rechnung gültig ist (`isIbanValidInZugferd`).

    FieldTypeRequiredDescription
    zugferdFile64string (base64)requiredBase64-kodiertes ZUGFeRD-PDF.
    comparePDF2XMLbooleanoptionalWenn 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",
      "isIbanValidInZugferd": true,
      "numberOfZugferdErrors": 10,
      "zugferdErrors": [
        {
          "id": "BR-CO-25",
          "line": null,
          "location": "/rsm:CrossIndustryInvoice",
          "message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
          "schemaFile": "EN16931-CII-validation",
          "type": "fatal"
        }
      ]
    }

    Antwortfelder

    FieldTypeDescription
    messagestring`File was validated`, sobald die Validierung lief. Andere Texte gibt es nur in den Sonderfällen unten.
    validboolean`true`, wenn das eingebettete XML keine Befunde in `zugferdErrors` hat, sonst `false`.
    isIbanValidInZugferdboolean`true`, wenn die IBAN in der Rechnung gültig ist; `false`, wenn sie ungültig ist. Wird unabhängig von `valid` ausgewiesen: Ein ZUGFeRD-PDF mit ungültiger IBAN kann trotzdem `valid: true` liefern. Eine gültige IBAN bedeutet hier nur, dass Format und Prüfziffern stimmen – nicht, dass das Konto existiert oder wem es gehört. Wird nicht zurückgegeben, wenn `message` `cannot extract data to validate` lautet.
    numberOfZugferdErrorsintegerAnzahl der Befunde im eingebetteten XML. `zugferdErrors` listet sie auf (das Beispiel oben zeigt nur einen der zehn).
    zugferdErrorsarrayAlle Befunde; leer, wenn `valid` `true` ist. Jeder Eintrag hat die unten aufgeführten Eigenschaften.
    zugferdErrors[].messagestringText der verletzten Regel. EN-16931- und PEPPOL-Regeln kommen auf Englisch, XRechnung-Regeln (BR-DE-*) und `additional-validation`-Befunde auf Deutsch. Regeltexte tragen häufig die Regel-ID in eckigen Klammern als Präfix, z. B. `[BR-CO-25]-…`.
    zugferdErrors[].idstring | nullRegel-ID, z. B. `BR-CO-25`, `BR-DE-15` oder `PEPPOL-EN16931-R008`. `null`, wenn die Datei nicht gelesen werden konnte; leerer String `""` bei `additional-validation`-Befunden, die keine Regel-ID haben.
    zugferdErrors[].locationstring | nullFundstelle: ein XPath in `Q{Namespace}`-Schreibweise bei Schema- und Schematron-Befunden, bzw. ein Feldschlüssel wie `sellerVatId` oder `dueDate` bei `additional-validation`-Befunden. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrors[].schemaFilestring | nullRegelwerk, das den Befund erzeugt hat. CII-Dokumente: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL-Dokumente: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. Befunde der XML-Schema-Prüfung (XSD) nennen das Schema, z. B. `UBL-Invoice-2.1`. Dazu `additional-validation` für die zusätzlichen Prüfungen. `null`, wenn die Datei nicht gelesen werden konnte.
    zugferdErrors[].typestringArt des Befunds: `fatal` bei Regelverstößen, `XSD` bei XML-Schema-Verstößen.
    zugferdErrors[].linenull | stringZeilennummer als String (z. B. `"1"`) bei Befunden der XML-Schema-Prüfung (XSD). Bei Regelbefunden leer (`null`, bzw. `""` bei `additional-validation`-Befunden) — nutzen Sie dort `location`.

    Beispielantwort

    json
    {
      "message": "File was validated",
      "valid": true,
      "isIbanValidInZugferd": true,
      "numberOfZugferdErrors": 0,
      "zugferdErrors": []
    }

    Beispielantwort

    json
    {
      "message": "cannot extract data to validate",
      "valid": false,
      "numberOfZugferdErrors": 0,
      "zugferdErrors": []
    }

    Playground

    Diesen Endpunkt live im Browser testen.

    Rechnungsobjekt – Referenz

    Das Rechnungsobjekt folgt dem europäischen Semantik-Standard EN 16931. Jedes Feld ist einem Business Term (BT-*) oder einer Business Group (BG-*) zugeordnet. Die folgenden Tabellen zeigen, welche Felder Pflicht und welche optional sind – gruppiert nach ihrer Rolle in der Rechnung.

    Wie diese Tabellen zu lesen sind

    • Pflichtfelder müssen vorhanden sein, damit die Rechnung gegen EN 16931 valide ist.
    • Mit „Min. 1 Pflicht“ markierte Arrays müssen mindestens einen Eintrag enthalten (z. B. Rechnungspositionen, USt-Aufschlüsselung).
    • Verschachtelte Felder werden mit Punktnotation dargestellt (z. B. sellerPostalAddress.sellerCity).
    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-1invoiceNumber
    • BT-2invoiceIssueDate
    • BT-3invoiceTypeCode
    • BT-5invoiceCurrencyCode
    • BT-10buyerReference
    Verkäufer (BG-4, BT-27 bis BT-43)
    • BT-27sellerName
    • BT-31sellerVatIdentifier
    • BT-34sellerElectronicAddress
    • BT-37sellerPostalAddress.sellerCity
    • BT-38sellerPostalAddress.sellerPostCode
    • BT-40sellerPostalAddress.sellerCountryCode
    Käufer (BG-7, BT-44 bis BT-58)
    • BT-44buyerName
    • BT-49buyerElectronicAddress
    • BT-52buyerPostalAddress.buyerCity
    • BT-53buyerPostalAddress.buyerPostCode
    • BT-55buyerPostalAddress.buyerCountryCode
    Zahlungsanweisungen (BG-16, BT-81 bis BT-91)
    • BT-81paymentMeansTypeCode
    Rechnungsbeträge (BG-22, BT-106 bis BT-115)
    • BT-106sumOfInvoiceLineNetAmount
    • BT-109invoiceTotalAmountWithoutVat
    • BT-110invoiceTotalVatAmount
    • BT-112invoiceTotalAmountWithVat
    • BT-115amountDueForPayment
    USt-Aufschlüsselung (BG-23, BT-116 bis BT-121)· ≥ 1
    • BT-116vatCategoryTaxableAmount
    • BT-117vatCategoryTaxAmount
    • BT-118vatCategoryCode
    • BT-119vatCategoryRate
    Rechnungspositionen (BG-25, BT-126 bis BT-161)· ≥ 1
    • BT-126invoiceLineIdentifier
    • BT-129invoicedQuantity
    • BT-130invoicedQuantityUnitOfMeasureCode
    • BT-131invoiceLineNetAmount
    • BT-146priceDetails.itemNetPrice
    • BT-151lineVatInformation[].invoicedItemVatCategoryCode
    • BT-152lineVatInformation[].invoicedItemVatRate
    • BT-153itemInformation.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.

    BTFieldTypePflichtBeschreibung
    BT-1invoiceNumberstringrequiredEindeutige Rechnungsnummer des Verkäufers.
    BT-2invoiceIssueDatedaterequiredAusstellungsdatum der Rechnung. Format JJJJMMTT oder JJJJ-MM-TT.
    BT-3invoiceTypeCodestringrequiredRechnungsart: 380 = Rechnung, 381 = Gutschrift, 384 = Korrekturrechnung.
    BT-5invoiceCurrencyCodestringrequiredISO-4217-Währungscode der Rechnung (z. B. EUR).
    BT-6vatAccountingCurrencyCodestringoptionalWährung für die USt-Buchhaltung, falls abweichend von der Rechnungswährung.
    BT-7valueAddedTaxPointDatedateoptionalUSt-Stichtag – Datum, an dem die USt fällig wird.
    BT-8valueAddedTaxPointDateCodestringoptionalCode, der angibt, welches Datum den USt-Stichtag bestimmt.
    BT-9paymentDueDatedateoptionalFälligkeitsdatum der Zahlung. Pflicht, sofern ein offener Betrag und kein Zahlungsbedingungstext vorhanden ist.
    BT-10buyerReferencestringrequiredKäuferreferenz (Leitweg-ID bei der öffentlichen Verwaltung, sonst eine mit dem Käufer vereinbarte Referenz).
    BT-11projectReferenceobjectoptionalOptionale Projektreferenz (Kennung + Name).
    BT-12contractReferencestringoptionalKennung des zugrunde liegenden Vertrags.
    BT-13purchaseOrderReferencestringoptionalBestellreferenz des Käufers.
    BT-14salesOrderReferencestringoptionalAuftragsreferenz des Verkäufers.
    BT-17tenderOrLotReferencestringoptionalAusschreibungs- oder Losreferenz.
    BT-19buyerAccountingReferencestringoptionalBuchhaltungsreferenz des Käufers.
    BT-20paymentTermsstringoptionalZahlungsbedingungen als Freitext. Pflicht, wenn BT-9 fehlt.
    BT-21/22invoiceNotearrayoptionalFreitext-Hinweise zur Rechnung, jeweils mit optionalem Themencode.
    BT-23/24processControlobjectoptionalGeschäftsprozess- und Spezifikations-Identifikatoren.
    BT-25/26precedingInvoiceReferencearrayoptionalReferenz auf eine vorhergehende Rechnung (für Korrekturen / Gutschriften).

    Verkäufer (BG-4, BT-27 bis BT-43)

    Identifikations- und Kontaktdaten des Rechnungsstellers.

    BTFieldTypePflichtBeschreibung
    BT-27sellerNamestringrequiredEingetragener Firmenname des Verkäufers.
    BT-28sellerTradingNamestringoptionalGeschäftsname, falls vom Firmennamen abweichend.
    BT-29sellerIdentifierstring[]optionalZusätzliche Verkäufer-Identifikatoren (z. B. GLN).
    BT-30sellerLegalRegistrationIdentifierstringoptionalHandelsregisternummer.
    BT-31sellerVatIdentifierstringrequiredUmsatzsteuer-Identifikationsnummer des Verkäufers.
    BT-32sellerTaxRegistrationIdentifierstringoptionalSteuernummer.
    BT-33sellerAdditionalLegalInformationstringoptionalWeitere Rechtsangaben (Geschäftsführer, Registergericht usw.).
    BT-34sellerElectronicAddressstringrequiredElektronische Adresse des Verkäufers (i. d. R. Postfach für E-Rechnungen oder E-Mail).
    BT-35sellerPostalAddress.sellerAddressLine1stringoptionalStraße und Hausnummer (Zeile 1).
    BT-37sellerPostalAddress.sellerCitystringrequiredOrt.
    BT-38sellerPostalAddress.sellerPostCodestringrequiredPostleitzahl.
    BT-40sellerPostalAddress.sellerCountryCodestringrequiredISO-3166-1 alpha-2 Ländercode (z. B. DE).
    BT-41/42/43sellerContactobjectoptionalAnsprechpartner: Name, Telefon, E-Mail.

    Käufer (BG-7, BT-44 bis BT-58)

    Identifikations- und Kontaktdaten des Rechnungsempfängers.

    BTFieldTypePflichtBeschreibung
    BT-44buyerNamestringrequiredEingetragener Firmenname des Käufers.
    BT-45buyerTradingNamestringoptionalGeschäftsname, falls vom Firmennamen abweichend.
    BT-46buyerIdentifierstringoptionalZusätzlicher Käufer-Identifikator.
    BT-47buyerLegalRegistrationIdentifierstringoptionalHandelsregisternummer des Käufers.
    BT-48buyerVatIdentifierstringoptionalUmsatzsteuer-Identifikationsnummer des Käufers.
    BT-49buyerElectronicAddressstringrequiredElektronische Adresse des Käufers.
    BT-50buyerPostalAddress.buyerAddressLine1stringoptionalStraße und Hausnummer (Zeile 1).
    BT-52buyerPostalAddress.buyerCitystringrequiredOrt.
    BT-53buyerPostalAddress.buyerPostCodestringrequiredPostleitzahl.
    BT-55buyerPostalAddress.buyerCountryCodestringrequiredISO-3166-1 alpha-2 Ländercode.
    BT-56/57/58buyerContactobjectoptionalAnsprechpartner: 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.

    BTFieldTypePflichtBeschreibung
    BT-81paymentMeansTypeCodestringrequiredUNTDID 4461 Zahlungsmittelcode (z. B. 58 = SEPA-Überweisung, 30 = Überweisung, 48 = Kreditkarte).
    BT-82paymentMeansTextstringoptionalFreitext-Zahlungsanweisungen.
    BT-83remittanceInformationstringoptionalVerwendungszweck (vom Käufer bei Zahlung anzugeben).
    BT-84creditTransfer[].paymentAccountIdentifierstringoptionalIBAN oder Kontonummer für die Zahlung.
    BT-85creditTransfer[].paymentAccountNamestringoptionalKontoinhaber.
    BT-86creditTransfer[].paymentServiceProviderIdentifierstringoptionalBIC der Empfängerbank.
    BT-87/88paymentCardInformationobjectoptionalKartenzahlungsinformationen (PAN, Karteninhaber).
    BT-89/90/91directDebitobjectoptionalLastschriftmandat-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.

    BTFieldTypePflichtBeschreibung
    BT-106sumOfInvoiceLineNetAmountdecimalrequiredSumme der Nettobeträge aller Rechnungspositionen.
    BT-107sumOfAllowancesOnDocumentLeveldecimaloptionalSumme der Nachlässe auf Dokumentenebene.
    BT-108sumOfChargesOnDocumentLeveldecimaloptionalSumme der Zuschläge auf Dokumentenebene.
    BT-109invoiceTotalAmountWithoutVatdecimalrequiredRechnungs-Gesamtbetrag ohne USt (Nettosumme).
    BT-110invoiceTotalVatAmountdecimalrequiredGesamter USt-Betrag.
    BT-111invoiceTotalVatAmountInAccountingCurrencydecimaloptionalGesamt-USt in der Buchhaltungswährung (BT-6), falls von BT-5 abweichend.
    BT-112invoiceTotalAmountWithVatdecimalrequiredRechnungs-Gesamtbetrag inkl. USt (Bruttosumme).
    BT-113paidAmountdecimaloptionalBereits bezahlter Betrag.
    BT-114roundingAmountdecimaloptionalRundungsbetrag.
    BT-115amountDueForPaymentdecimalrequiredZu zahlender Betrag (BT-112 − BT-113 + BT-114).

    USt-Aufschlüsselung (BG-23, BT-116 bis BT-121)

    Array · Min. 1 Pflicht

    Array mit USt-Zwischensummen. Mindestens ein Eintrag ist Pflicht, mit einer Zeile pro Kombination aus USt-Kategorie und -Satz.

    BTFieldTypePflichtBeschreibung
    BT-116vatCategoryTaxableAmountdecimalrequiredSteuerbarer Betrag für diese USt-Kategorie.
    BT-117vatCategoryTaxAmountdecimalrequiredUSt-Betrag für diese Kategorie (BT-116 × BT-119 / 100).
    BT-118vatCategoryCodestringrequiredUSt-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-119vatCategoryRatedecimalrequiredUSt-Satz in Prozent (z. B. 19 für 19 %).
    BT-120vatExemptionReasonTextstringoptionalPflicht bei Steuerbefreiung oder Nullsatz. Freitext-Begründung.
    BT-121vatExemptionReasonCodestringoptionalKodierte Befreiungsgründe (z. B. VATEX-EU-AE, VATEX-EU-IC).

    Rechnungspositionen (BG-25, BT-126 bis BT-161)

    Array · Min. 1 Pflicht

    Array der Rechnungspositionen. Jede Position beschreibt ein Produkt oder eine Leistung und muss Identifikation, Menge, Nettopreis, Positions-Nettobetrag und USt-Zuordnung enthalten.

    BTFieldTypePflichtBeschreibung
    BT-126invoiceLineIdentifierstringrequiredEindeutige Positionsnummer innerhalb der Rechnung.
    BT-127invoiceLineNotestringoptionalFreitext-Hinweis zur Position.
    BT-128invoiceLineObjectIdentifierstringoptionalObjektkennung, auf die die Position verweist.
    BT-129invoicedQuantitydecimalrequiredIn Rechnung gestellte Menge.
    BT-130invoicedQuantityUnitOfMeasureCodestringrequiredUN/ECE Empfehlung 20 Maßeinheit (z. B. H87 = Stück, HUR = Stunde, KGM = Kilogramm).
    BT-131invoiceLineNetAmountdecimalrequiredPositions-Nettobetrag (Menge × Nettopreis − Positionsnachlässe + Positionszuschläge).
    BT-132referencedPurchaseOrderLineReferencestringoptionalReferenz auf eine Bestellposition des Käufers.
    BT-133invoiceLineBuyerAccountingReferencestringoptionalBuchungsreferenz für diese Position.
    BT-134/135invoiceLinePeriodobjectoptionalLeistungszeitraum dieser Position (Start/Ende).
    BT-136 to BT-140invoiceLineAllowancesarrayoptionalNachlässe/Rabatte auf Positionsebene.
    BT-141 to BT-145invoiceLineChargesarrayoptionalZuschläge auf Positionsebene.
    BT-146priceDetails.itemNetPricedecimalrequiredNetto-Stückpreis (nach Artikel-Preisrabatt).
    BT-147priceDetails.itemPriceDiscountdecimaloptionalRabatt auf den Brutto-Stückpreis zur Ermittlung des Nettopreises.
    BT-148priceDetails.itemGrossPricedecimaloptionalBrutto-Stückpreis vor Rabatt.
    BT-149priceDetails.itemPriceBaseQuantitydecimaloptionalBezugsmenge des Stückpreises (die Menge, auf die sich der Preis bezieht, z. B. 100, wenn der Preis je 100 Stück gilt).
    BT-150priceDetails.itemPriceBaseQuantityUnitOfMeasurestringoptionalMaßeinheit der Bezugsmenge (UN/ECE-Empfehlung-20-Code, z. B. H87, HUR).
    BT-151lineVatInformation[].invoicedItemVatCategoryCodestringrequiredUSt-Kategorie der Position (passt zu einem Eintrag in vatBreakdown).
    BT-152lineVatInformation[].invoicedItemVatRatedecimalrequiredUSt-Satz der Position.
    BT-153itemInformation.itemNamestringrequiredArtikelbezeichnung auf der Rechnung.
    BT-154itemInformation.itemDescriptionstringoptionalAusführliche Artikelbeschreibung.
    BT-155itemInformation.itemSellersIdentifierstringoptionalArtikelnummer des Verkäufers.
    BT-156itemInformation.itemBuyersIdentifierstringoptionalArtikelnummer des Käufers.
    BT-157itemInformation.itemStandardIdentifierstringoptionalStandardartikelkennung (z. B. GTIN). Pflicht, wenn BT-157-1 gesetzt ist.
    BT-157-1itemInformation.itemStandardIdentifierSchemeIdentifierstringoptionalISO-6523-Schema für BT-157. Pflicht, wenn BT-157 gesetzt ist.
    BT-158itemInformation.itemClassificationIdentifierarrayoptionalArtikelklassifizierungen (z. B. UNSPSC, eCl@ss) mit Schema und Version.
    BT-159itemInformation.itemCountryOfOriginstringoptionalISO-3166-1 alpha-2 Herkunftsland.
    BT-160/161itemInformation.itemAttributesarrayoptionalArtikelmerkmale 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.

    BTFieldTypePflichtBeschreibung
    BG-10 / BT-59 to BT-61payeeobjectoptionalZahlungsempfänger, falls vom Verkäufer abweichend.
    BG-11 / BT-62 to BT-69sellerTaxRepresentativePartyobjectoptionalSteuervertreter des Verkäufers (üblicherweise für Verkäufer außerhalb der EU).
    BG-13 / BT-70 to BT-80deliveryInformationobjectoptionalLieferpartei, Ort und tatsächliches Lieferdatum.
    BG-14 / BT-73, BT-74invoicingPeriodobjectoptionalLeistungszeitraum auf Rechnungsebene.
    BG-20 / BT-92 to BT-98documentLevelAllowancesarrayoptionalNachlässe/Rabatte auf Dokumentenebene.
    BG-21 / BT-99 to BT-105documentLevelChargesarrayoptionalZuschläge auf Dokumentenebene.
    BG-24 / BT-122 to BT-125additionalSupportingDocumentsarrayoptionalZusätzliche Belege (Stundennachweis, Lieferschein usw.). Entweder externe URL oder Base64-Anhang. Jeder Eintrag: supportingDocumentReference (BT-122), supportingDocumentDescription (BT-123), externalDocumentLocation (BT-124, URL), attachedDocument (BT-125, Base64), attachedDocumentFilename (Dateiname des Anhangs) und supportingDocumentTypeCodex (Ganzzahl, UNTDID-1001-Dokumenttypcode, z. B. 916 = referenziertes Dokument, 130 = Rechnungsdatenblatt).

    E-Mail-Versand (transport)

    Erzeugen und versenden in einem Aufruf: Die Erzeugungs-Endpunkte createXinvoiceFromJson, createZugferdFromJson und createInvoicePdfFromJson akzeptieren ein optionales transport-Objekt. Ist es vorhanden, wird die erzeugte Rechnung im selben Vorgang per E-Mail zugestellt – DKIM-signiert, an Empfänger, CC und BCC gleichzeitig, ohne eigene Mailinfrastruktur. Ist es nicht vorhanden, verhalten sich die Endpunkte exakt wie bisher; die Funktion ist vollständig abwärtskompatibel. Für bereits erzeugte ZUGFeRD-Daten gibt es den dedizierten Endpunkt sendEmailWithZugferdData.

    Voraussetzungen

    Der E-Mail-Versand muss für Ihr Konto freigeschaltet und Ihre Absenderdomain einmalig authentifiziert sein. So richten Sie beides ein: E-Mail-Versand einrichten.

    Das transport-Objekt

    FeldTypPflichtBeschreibung
    typestringPflichtVersandkanal. Derzeit nur "email".
    useTransportbooleanPflichtAuf true setzen, um die erzeugte Rechnung im selben Aufruf zu versenden.
    senderstringPflichtAbsenderadresse auf Ihrer eigenen Domain. Die Domain muss einmalig authentifiziert sein (DKIM/SPF) – siehe die oben verlinkte Einrichtungsanleitung.
    senderNamestringoptionalAnzeigename des Absenders.
    receiverstringPflichtEmpfängeradresse(n), kommasepariert. Wird vor dem Versand bereinigt.
    ccstringoptionalCC-Adresse(n), kommasepariert.
    bccstringoptionalBCC-Adresse(n), kommasepariert – z. B. Ihr eigenes Archiv-Postfach für eine Kopie jeder versendeten Rechnung.
    subjectstringPflichtE-Mail-Betreff. Unterstützt die Platzhalter {invoicenumber} und {invoicedate} – nicht {lastname}, das nur im message-Feld funktioniert.
    messagestringPflichtE-Mail-Text als HTML. Unterstützt {invoicenumber} und {invoicedate} wie der Betreff, zusätzlich {lastname} (invoice.buyer.buyerName) – nur hier, nicht im Betreff.
    attachmentsarrayoptionalZusä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.

    CodeBezeichnungBeschreibung
    200OKAnfrage verarbeitet. Bei Validierungs- und Erzeugungs-Endpunkten zusätzlich das Feld `valid` prüfen – HTTP 200 bedeutet nicht, dass die Rechnung valide ist.
    400Ungültige AnfrageUngültiges JSON oder ungültige Rechnungsdaten. Der Response-Body listet die betroffenen Felder.
    401Nicht autorisiertFehlender oder ungültiger Authorization-Header / Bearer-Token.
    402Zahlung erforderlichKein aktives Abo oder API-Kontingent aufgebraucht. Bitte Support kontaktieren oder Plan upgraden.
    412Vorbedingung fehlgeschlagenErforderliche Eingabe (PDF, XML oder Rechnungsdaten) fehlt im Request-Body, oder der Rechnung fehlen Pflichtangaben. Der Body ist `{ message }`; bei fehlenden Rechnungsdaten enthält er zusätzlich `noOfMissingData` und `errorlist` – siehe Schema unten.
    500ServerfehlerUnerwarteter serverseitiger Fehler. Mit exponentiellem Backoff erneut versuchen; bei dauerhaftem Fehler Support mit Request-ID kontaktieren.

    Schema eines Validierungsfehlers

    Jeder Eintrag in `xInvoiceErrors` / `xInvoiceErrorList` / `zugferdErrors` / `zugferdErrorList` / `zugferdErrorlist` / `xrechnungErrors` / `errorList` folgt diesem Schema — die Schreibweise des Listennamens unterscheidet sich je Endpunkt, die Einträge nicht. Nutzen Sie `id` und `location`, um zur fehlerhaften Stelle zu springen. `line` ist derzeit immer leer.

    json
    {
      "id": "BR-CO-25",
      "line": null,
      "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]",
      "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
      "schemaFile": "EN16931-CII-validation",
      "type": "fatal"
    }

    Befunde aus den zusätzlichen Prüfungen des XML-Validators (`schemaFile: additional-validation`) haben keine Regel-ID: `id` und `line` sind leere Strings und `location` ist ein Feldschlüssel statt eines XPath. Lässt sich die Datei gar nicht lesen, sind `schemaFile`, `location`, `id` und `line` `null`.

    json
    {
      "id": "",
      "line": "",
      "location": "sellerVatId",
      "message": "Verkäufer Vat ID ist ungültig",
      "schemaFile": "additional-validation",
      "type": "fatal"
    }

    Schema bei fehlenden Daten (412)

    Fehlen Pflichtangaben in der Rechnung, antwortet createXinvoiceFromJson mit 412 und benennt jede Lücke als EN-16931-Business-Term. In diesem Fall wird nichts erzeugt.

    json
    {
      "message": "Data are missing in input.",
      "noOfMissingData": 1,
      "errorlist": [
        {
          "businessTerm": "BT-34",
          "businessTermDescription": "BT-34 (sellerElectronicAddress)",
          "errormessage": "field is required to be filled with an valid email address"
        }
      ]
    }

    MCP-Server & SDK

    RechnungsAPI steht KI-Agenten über einen gehosteten MCP-Server zur Verfügung und Entwicklern als offizielles, typisiertes SDK. Verbinden Sie jeden MCP-Client, der Streamable HTTP mit eigenem Authorization-Header unterstützt (zum Beispiel Claude Code oder Open WebUI), starten Sie denselben Server lokal per npx oder installieren Sie das npm-SDK, um die API aus Ihrem eigenen Code heraus aufzurufen.

    KI-Agent verbinden (MCP)

    Ein gehosteter MCP-Server läuft unter mcp.rechnungsapi.de. Er spricht Streamable HTTP und authentifiziert jede Anfrage mit Ihrem eigenen Bearer-Token (kein OAuth, keine separate Registrierung). Sie möchten ihn lieber selbst ausführen? Derselbe Server ist als npm-Paket rechnungsapi-mcp für stdio-basierte Clients wie Claude Desktop und Claude Code verfügbar.

    {
      "mcpServers": {
        "rechnungsapi": {
          "type": "http",
          "url": "https://mcp.rechnungsapi.de/mcp",
          "headers": { "Authorization": "Bearer <your-api-token>" }
        }
      }
    }

    Open WebUI unterstützt entfernte MCP-Server nativ: Legen Sie unter Admin Settings → Integrations eine Verbindung vom Typ MCP (Streamable HTTP) an, wählen Sie als Auth „Bearer“ und fügen Sie Ihren Token ein. Clients, die für entfernte Server ausschließlich OAuth anbieten, können sich noch nicht mit dem gehosteten Endpunkt verbinden – nutzen Sie dann die lokale npx-Variante oder das SDK weiter unten.

    Offizielles SDK (npm)

    Möchten Sie die API direkt aus Ihrem eigenen Backend aufrufen statt über einen KI-Agenten? rechnungsapi-sdk ist ein typisierter TypeScript/JavaScript-Client für ZUGFeRD/X-Invoice-Erstellung, -Validierung und PDF-Analyse.

    npm install rechnungsapi-sdk

    Pakete und vollständige Dokumentation auf npm: rechnungsapi-mcp · rechnungsapi-sdk

    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.
    rechnungsapi.de

    Professionelle E-Rechnungs-APIs für KMUs. Transformieren Sie Ihr ERP-System mit ZUGFeRD-konformen Lösungen und DSGVO-konformer KI-Technologie.

    DSGVO-konform & sicher

    Produkt

    • Preise
    • XRechnung API
    • ZUGFeRD API
    • PDF zu ZUGFeRD
    • PDF zu JSON
    • Ordner-Workflow
    • Peppol
    • XRechnung 4.0
    • Validator
    • XML-Viewer
    • Kontakt

    Lösungen

    • Steuerberater & Kanzleien
    • Unternehmen & Mittelstand
    • IT-Teams & Softwareanbieter
    • E-Invoicing-Berater & Partner
    • Startups & SaaS
    • International & Peppol

    Rechtliches

    • Über uns / Stefan Grimm
    • Impressum
    • AGB / Datenschutzerklärung
    • AVV / TOM
    • Unterauftragsverarbeiter
    • Nutzungsbedingungen
    • DSGVO-Konformität

    Server in Deutschland · DSGVO-konform · Auftragsverarbeiter ISO/IEC 27001-zertifiziert (Open Telekom Cloud)

    rechnungsapi.de ist ein Produkt der Finbc GmbH, Essenheim (gegründet 2018).

    © 2026 rechnungsapi.de

    support@rechnungsapi.de