Zum Inhalt springen

Deutschland — E-INVOICE DE (Unified API)

In Deutschland unterstützt fiskaly das Senden und Empfangen von B2B-E-Rechnungen. Die E-Rechnung wird vom Bundesministerium der Finanzen (BMF) geregelt. Alle elektronischen Rechnungen müssen der EN 16931 entsprechen, die durch Formate wie XRechnung, ZUGFeRD oder Peppol BIS 3.0 Billing erfüllt wird. fiskaly archiviert deutsche E-Rechnungen nicht — siehe Archivierung.

fiskaly generiert EN 16931-konforme E-Rechnungen und stellt sie über einen von zwei Kanälen zu. Den Kanal legen Sie pro Rechnung beim Empfänger fest (recipients[].invoicing): per E-Mail — als ZUGFeRD oder XRechnung — oder über das PEPPOL-Netzwerk als XRechnung.

Die beiden Richtungen werden unterschiedlich konfiguriert:

Diese Seite behandelt die Deutschland-spezifischen Anforderungen, die die Allgemeine Schritt-für-Schritt-Integration ergänzen. Stellen Sie sicher, dass Ihnen die folgenden Daten des Steuerpflichtigen vorliegen, bevor Sie fortfahren:

  • fiscalization.vat_id_number — Umsatzsteuer-Identifikationsnummer (Umsatzsteuer-ID), 9 Ziffern ohne das Präfix DE
  • fiscalization.tax_id_number — steuerliche Identifikationsnummer (Steuer-ID), 11 Ziffern. Erforderlich für Taxpayer vom Typ INDIVIDUAL.
  • name — Eingetragener Firmenname und Handelsname des Unternehmens oder der natürlichen Person
  • address — Eingetragene Geschäftsadresse des Unternehmens oder der natürlichen Person

Um eine E-Rechnung zu versenden, geben Sie den Empfänger und den Zustellweg direkt im Record der Rechnung an. Wenn Sie die Rechnung (TRANSACTION::INVOICE) mit createRecord erstellen, fügen Sie den Empfänger dem recipients-Array hinzu.

Wie in der Allgemeinen Schritt-für-Schritt-Integration beschrieben, muss jeder Empfänger vom Typ BUSINESS sein und einen ausgefüllten invoicing-Block haben. Zusätzlich zu den Standardangaben jeder E-Rechnung (Name, Adresse, Steueridentifikation des Empfängers, Rechnungspositionen usw.) kommt in Deutschland der Zustellkanal beim Empfänger hinzu:

  • recipients[].type = BUSINESS
  • recipients[].identification.type = VAT — die deutsche E-Rechnung identifiziert den Käufer über die Umsatzsteuer-Identifikationsnummer
  • recipients[].address.country = DE — Empfänger müssen in Deutschland ansässig sein
  • recipients[].invoicing.type = EMAIL oder PEPPOL — der Zustellkanal
  • recipients[].invoicing.email — (nur EMAIL) die E-Mail-Adresse des Empfängers
  • recipients[].invoicing.format — (nur EMAIL, optional) das Dokumentformat
  • recipients[].invoicing.identifier — (nur PEPPOL) der PEPPOL Network Identifier des Empfängers, in der Form <Schemacode>:<Wert> — für ein deutsches Unternehmen typischerweise 9930:<USt-IdNr.>
invoicing.typeZusätzlich erforderlichWie fiskaly zustellt
EMAILinvoicing.emailPer E-Mail an diese Adresse, als ZUGFeRD oder XRechnung je nach invoicing.format.
PEPPOLinvoicing.identifierAn den PEPPOL-Endpunkt des Empfängers als XRechnung — siehe XRechnung-Einschränkung.

Sie wählen den Kanal pro Rechnung, nicht dauerhaft pro Empfänger — dasselbe Unternehmen kann eine Rechnung per E-Mail und die nächste über PEPPOL erhalten.

Jeder Eintrag in payments ist entweder eine bereits erhaltene Zahlung (CASH, CARD, ONLINE, VOUCHER, OTHER) oder der noch offene Betrag (OUTSTANDING). Erhaltene Zahlungen erscheinen auf der Rechnung als bereits gezahlter Betrag, und das Datum des OUTSTANDING-Eintrags wird zum Fälligkeitsdatum der Rechnung. Bei einer vollständig bezahlten Rechnung lassen Sie OUTSTANDING weg.

Jede Zahlung benötigt type und details.amount. Einige Typen benötigen mehr:

typeZusätzlich erforderlich
CASH—
CARDnumber (maskierte Kartennummer, zum Beispiel ************1234) und kind
ONLINEname, zum Beispiel der Zahlungsdienstleister
VOUCHERnumber und kind
OTHER— (name ist optional)
OUTSTANDINGconcept (GOOD, SERVICE oder INVOICE) und details.date, das Fälligkeitsdatum

concept wird nur bei OUTSTANDING akzeptiert. Bei jedem anderen Zahlungstyp wird der Request mit 400 abgelehnt.

In Deutschland ist die Registrierung im PEPPOL-Netzwerk optional — Sie entscheiden sich pro System dafür.

Hinterlegen Sie sie am E_INVOICE_SERVICE System mit createSystem:

{
"content": {
"type": "E_INVOICE_SERVICE",
"location": { "id": "..." },
"software": { "...": "..." },
"registrations": [{ "type": "PEPPOL" }]
}
}

Oder ergänzen Sie sie an einem bestehenden System mit updateSystem:

{
"content": {
"registrations": [{ "type": "PEPPOL" }]
}
}

Was sich aus dieser Entscheidung ergibt:

  • registrations weggelassen — das System versendet ausschließlich per E-Mail. Ein Proof of Ownership ist nicht erforderlich, und das System geht bei der Inbetriebnahme direkt in den Modus OPERATIVE.
  • registrations enthält PEPPOL — ein Proof of Ownership ist erforderlich. Bei der Inbetriebnahme wird der state des Systems COMMISSIONED, sein mode jedoch DEGRADED, und das System erhält einen Log-Eintrag, der den fehlenden Proof of Ownership festhält.

Um das System in den Modus OPERATIVE zu bringen, laden Sie den Proof of Ownership wie in Schritt 11 der allgemeinen Integrationsanleitung beschrieben hoch. Die Prüfung dauert bis zu 72 Stunden; sobald sie abgeschlossen ist, wechselt das System automatisch und der Log-Eintrag wird entfernt. Was das Dokument enthalten muss, steht im Abschnitt Proof of Ownership.

Setzen Sie beim Empfänger in Ihrem createRecord-Request:

  • recipients[].invoicing.type = PEPPOL
  • recipients[].invoicing.identifier — der PEPPOL Network Identifier des Empfängers

Dafür müssen zwei Voraussetzungen erfüllt sein: Ihr E_INVOICE_SERVICE System muss im PEPPOL-Netzwerk registriert sein (siehe PEPPOL-Registrierung), und der PEPPOL Network Identifier des Empfängers muss Ihnen vorliegen. Um das Identifier-Schema kümmert sich fiskaly.

Auf diesem Weg versandte Rechnungen werden als XRechnung erzeugt. recipients[].invoicing.format spielt hier keine Rolle — auf diesem Kanal ist das Format nicht wählbar.

Wenn der Kanal EMAIL ist, entscheiden Sie, welches Dokumentformat fiskaly erzeugt. Setzen Sie es beim selben Empfänger in Ihrem createRecord-Request über recipients[].invoicing.format:

WertFormat
ZUGFERD_V2 (Standard)ZUGFeRD — ein hybrides Dokument: ein menschenlesbares PDF/A-3 mit eingebettetem strukturiertem XML.
XRECHNUNG_V3XRechnung — eine reine strukturierte XML-Rechnung, ohne PDF-Ebene.

Das Feld ist optional: Wenn Sie es weglassen, erzeugt fiskaly ZUGFERD_V2. Beide Formate entsprechen der EN 16931.

fiskaly versendet die E-Mail im Namen des Verkäufers von no-reply.e-invoicing@fiskaly.com. Der Betreff lautet „Your Invoice“, der Text ist auf Englisch. Die E-Mail nennt den Verkäufer und verweist den Empfänger bei Fragen zur Rechnung an den Verkäufer.

Die E-Mail wird direkt nach dem Erstellen der Rechnung verschickt (die Verarbeitung ist asynchron, siehe unten). Einen separaten Versand-Trigger gibt es nicht: Um die Zustellung zu verzögern, verzögern Sie den createRecord-Aufruf.

Die Rechnung ist als invoice_<id>.xml (XRechnung) bzw. invoice_<id>.pdf (ZUGFeRD) angehängt. <id> ist die ID des E_INVOICE::TRANSMISSION Records.

Jede über PEPPOL versendete Rechnung wird als XRechnung erzeugt, ebenso jede E-Mail-Rechnung mit XRECHNUNG_V3. XRechnung verlangt zwei Felder, die ZUGFeRD nicht verlangt:

FeldXRechnung-RegelWert
document.references.buyerBR-DE-151–32 Zeichen: Buchstaben, Ziffern, Leerzeichen und . - _ /. Pflicht bei jeder Rechnung, nicht nur bei öffentlichen Auftraggebern.
seller.phoneBR-DE-6Telefonnummer des Verkäufers im Format E.164, zum Beispiel +49301234567.

Jede Rechnung erfordert zwei createRecord-Aufrufe, wie in Schritt 12 der allgemeinen Integrationsanleitung beschrieben: eine INTENTION und danach eine TRANSACTION::INVOICE, die darauf verweist. Senden Sie jeden Aufruf mit einem neuen Idempotency Key. Ersetzen Sie IDs und Werte durch Ihre eigenen.

Intention
{
"content": {
"type": "INTENTION",
"system": {
"id": "<E_INVOICE_SERVICE System ID>"
},
"operation": {
"type": "TRANSACTION"
}
}
}
Rechnung per E-Mail als ZUGFeRD
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "EMAIL",
"email": "invoices@beispiel-gmbh.de",
"format": "ZUGFERD_V2"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}
Rechnung per E-Mail als XRechnung
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00",
"references": {
"buyer": "PO-4711"
}
},
"seller": {
"name": "Max Mustermann",
"phone": "+49301234567",
"email": "billing@example-seller.de"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "EMAIL",
"email": "invoices@beispiel-gmbh.de",
"format": "XRECHNUNG_V3"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}
Rechnung über PEPPOL (XRechnung)
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00",
"references": {
"buyer": "PO-4711"
}
},
"seller": {
"name": "Max Mustermann",
"phone": "+49301234567",
"email": "billing@example-seller.de"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "PEPPOL",
"identifier": "9930:DE369204173"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}

Der Versand erfolgt asynchron. createRecord antwortet, sobald die TRANSACTION::INVOICE angenommen ist. Rechnung und Übermittlung werden danach verarbeitet. Dafür gibt es keine Webhooks, fragen Sie den Status daher mit retrieveRecord ab. Jeder Record zeigt seinen Fortschritt in mode: PROCESSING, solange die Verarbeitung läuft, FINISHED, sobald sie abgeschlossen ist. state enthält dann das Ergebnis.

Sobald die TRANSACTION::INVOICE FINISHED ist, bedeutet COMPLETED allein nicht, dass die Rechnung versendet wurde. Prüfen Sie, dass ihre logs keinen Eintrag mit "severity": "ERROR" enthalten und dass used_in vorhanden ist.

used_in.id ist der E_INVOICE::TRANSMISSION Record. Fragen Sie ihn ab, bis sein mode FINISHED ist. Sein state zeigt das Ergebnis:

  • COMPLETED — die Rechnung wurde zur Zustellung übergeben.
  • FAILED — die Rechnung wurde nicht zugestellt. Der Grund steht in den logs des Records.

Bei E-Mail bedeutet COMPLETED, dass die Rechnung an das E-Mail-Gateway von fiskaly übergeben wurde. Die Zustellung in das Postfach des Empfängers kann nicht bestätigt werden, und spätere Bounces werden nicht am Record gemeldet.

Lehnt das E-Mail-Gateway eine E-Mail dauerhaft ab, endet die Übermittlung sofort mit FAILED. Vorübergehende Fehler werden im Hintergrund erneut versucht, daher kann die Übermittlung eine Weile in PROCESSING bleiben. Sie endet erst mit FAILED, wenn alle Wiederholungsversuche aufgebraucht sind.

Eine fehlgeschlagene Rechnung wurde nicht ausgestellt. Senden Sie sie erneut als neue TRANSACTION::INVOICE (neue INTENTION, neuer Idempotency Key) mit derselben Rechnungsnummer — nicht als CORRECTION. Um eine Rechnung zu korrigieren, die den Käufer erreicht hat, stellen Sie eine Credit Note aus.

Ausführliche Informationen finden Sie im Support-Artikel How to detect and handle failed invoices (auf Englisch).

Was Sie sehenUrsache
ERROR-Log either party.telephones or party.people[0].telephones is required (BR-DE-6), nichts versendetXRechnung ohne seller.phone
ERROR-Log an der TRANSACTION::INVOICE, kein used_in, nichts versendetXRechnung ohne document.references.buyer
400 bei createRecordLeere document.references.buyer oder ein anderer Schemafehler
receiver does not support document typePEPPOL-Empfänger nicht für XRechnung registriert — siehe Versand über PEPPOL
422 Unprocessable Content bei der InbetriebnahmeTaxpayer ohne vat_id_number

Rufen Sie retrieveRecord für die E_INVOICE::TRANSMISSION (used_in.id) mit compliance-artifact auf, um die erzeugte E-Rechnung zu erhalten. Die Antwort ist ein JSON-Envelope. Bei XRechnung ist content.compliance.artifact:

{ "type": "application/xml", "data": "<base64>" }

Für ZUGFeRD ist content.compliance.artifact das PDF/A-3 mit eingebettetem XML:

{ "type": "application/pdf", "data": "<base64>" }

Wann und wie Sie eine Credit Note ausstellen, erklärt der Leitfaden Credit Note. Dieser Abschnitt behandelt nur, was speziell für Deutschland gilt.

Eine Credit Note ist ein vollständiges eigenständiges Dokument und übernimmt keine Daten aus der ursprünglichen Rechnung. Senden Sie denselben Empfänger, Kanal und dasselbe Format wie auf der Rechnung. Senden Sie für XRechnung außerdem seller.phone, seller.email und document.references.buyer erneut mit. Fehlen sie, wird nichts versendet und der Record erhält einen ERROR-Log (BR-DE-6, BR-DE-7, BR-DE-15).

Zahlungen auf Credit Notes und aufhebenden Rechnungen

Abschnitt betitelt „Zahlungen auf Credit Notes und aufhebenden Rechnungen“

Auf einer Credit Note und auf einer Rechnung, die eine Credit Note aufhebt, beschreibt payments, was auf diesem Dokument noch offen ist:

  • Beglichener Teil: type: OTHER mit details.amount und details.currency, ohne Datum.
  • Noch zu zahlender Betrag: type: OUTSTANDING mit concept, details.amount, details.currency und details.date, dem Fälligkeitsdatum (Pflichtfeld).

Die E-Rechnung weist den beglichenen Teil als bereits gezahlt aus und den Rest als zahlbar bis zum Fälligkeitsdatum. Beide Typen lassen sich auf Credit Notes und auf Rechnungen kombinieren.

DokumentSituationpayments
Credit NoteErstattung bereits an den Kunden ausgezahltOTHER = gutgeschriebener Betrag
Credit NoteErstattung noch auszuzahlenOUTSTANDING mit Fälligkeitsdatum
Credit NoteTeilweise erstattetOTHER (erstatteter Teil) + OUTSTANDING (Rest)
Aufhebende RechnungErstattung vollständig ausgezahlt, der Kunde zahlt sie zurückOUTSTANDING = voller Betrag
Aufhebende RechnungErstattung teilweise ausgezahlt (z. B. 50,00 von 119,00)OTHER 69.00 + OUTSTANDING 50.00
Aufhebende RechnungNichts ausgezahlt, die Dokumente heben sich aufOTHER = voller Betrag
Beispiel — aufhebende Rechnung, Erstattung teilweise ausgezahlt
"payments": [
{
"type": "OTHER",
"details": {
"amount": "69.00",
"currency": "EUR"
}
},
{
"type": "OUTSTANDING",
"concept": "SERVICE",
"details": {
"amount": "50.00",
"currency": "EUR",
"date": "2026-11-30"
}
}
]

Der Empfang eingehender E-Rechnungen läuft über PEPPOL und setzt daher dieselbe PEPPOL-Registrierung voraus wie der Versand über PEPPOL — einschließlich eines bestätigten Proof of Ownership. Ein Taxpayer, der ausschließlich per E-Mail versendet, kann nicht empfangen.

Wenn Sie einen deutschen Taxpayer im PEPPOL-Netzwerk registrieren, registriert fiskaly ihn standardmäßig für Versand und Empfang. Eingehende Rechnungen, die an den PEPPOL Identifier des Systems adressiert sind, werden diesem System zugeordnet, und fiskaly erstellt für jede einen Record vom Typ E_INVOICE::RECEPTION.

Rufen Sie retrieveSystem auf, um compliance.state zu lesen:

  • TRANSMISSION_RECEPTION — das System kann senden und empfangen.
  • TRANSMISSION_ONLY — das System kann nur senden.

Jede an Ihren Taxpayer adressierte Rechnung wird automatisch empfangen und als Record gespeichert — es gibt keinen Webhook, Sie fragen neue Rechnungen also selbst ab:

  1. Rufen Sie listRecords auf und filtern Sie nach E_INVOICE::RECEPTION.
  2. Rufen Sie für jeden neuen Record retrieveRecord mit compliance-artifact auf, um das signierte XML zu erhalten.

listRecords gibt die neuesten Records zurück (limit ist standardmäßig 10, neueste zuerst) — verfolgen Sie daher, welche Sie bereits verarbeitet haben.

Sie können die erzeugte E-Rechnung einer versendeten Rechnung und das XML einer empfangenen Rechnung abrufen.