Peppol per API: Welches Datenmodell Softwareanbieter wirklich brauchen

Viele APIs scheitern an Peppol nicht beim XML-Rendering, sondern schon im Datenmodell. Solange eine Lösung nur „Rechnungsnummer, Betrag, VAT-Prozent, PDF und optional XML“ kennt, wirkt vieles noch einfach. Spätestens bei echten Peppol-Fällen zeigt sich aber: Für EN 16931 und Peppol BIS Billing 3.0 musst du deutlich mehr sauber modellieren.

Wenn du vorher noch die Grundlagen brauchst, schau dir auch unseren Vergleich XRechnung vs. ZUGFeRD und unseren Artikel zu ViDA 2030 und grenzüberschreitenden B2B-Rechnungen an.

Das Wichtigste in Kürze

• Peppol BIS Billing 3.0 ist in der Syntax als UBL Invoice und UBL Credit Note beschrieben.
• Buyer EndpointID und Seller EndpointID sind Pflichtfelder.
• Buyer Reference oder Order Reference ist Pflicht; in Deutschland wird Buyer Reference zusätzlich besonders wichtig.
• Für VAT reicht Steuersatz allein nicht. Relevant sind Kategorie + Satz.
• Exemption Reasons sind bei mehreren VAT-Kategorien verpflichtend.
• Credit Notes und Korrekturen brauchen belastbare Referenzketten auf frühere Belege.
• Wer später Peppol sauber unterstützen will, braucht die Datenstruktur früh — nicht erst beim Writer.

Warum das Datenmodell wichtiger ist als der Writer

Ein UBL- oder CII-Writer kann nur ausgeben, was dein System zuvor semantisch sauber modelliert hat. Genau deshalb ist die Reihenfolge wichtig:

1. fachliches Rechnungsmodell
2. Mapping auf EN 16931-Business-Terme
3. Writer für die Zielsyntax

Wer nur am Ende „noch einen Peppol-Export“ anhängt, landet schnell bei Hardcodings, Sonderregeln und schwer wartbaren Mappings.

1. Warum Steuersatz allein nicht reicht

Das klassische ERP-Denken lautet oft: „Position hat 19 %, 7 % oder 0 %.“ Für Peppol ist das zu grob.

Peppol BIS Billing verlangt auf Positionsebene eine VAT Category und optional bzw. je nach Fall den VAT Rate. In den VAT-Breakdowns wird nicht einfach nur nach Prozentwerten aggregiert, sondern nach Kategorie und Satz.

Das sieht man direkt in den Regeln für die VAT-Breakdowns: Die steuerpflichtige Basis in einem Breakdown bezieht sich jeweils auf eine bestimmte VAT category code und eine bestimmte VAT category rate.

Praktisch heißt das:

• 19 % Standard ist nicht dasselbe wie ein anderer Fall mit gleichem Prozentwert, aber anderer Kategorie
• 0 % ist fachlich nicht automatisch „steuerfrei“
• Exempt, Reverse charge, Intra-community supply oder Export outside the EU sind unterschiedliche steuerliche Szenarien

Für APIs ist deshalb sinnvoll:

• tax_category_code pro Position
• tax_rate pro Position
• saubere Aggregationslogik für VAT-Breakdowns nach (rate, category)

Wenn dich das praktisch interessiert: Genau diese Art von Modellierung ist die Grundlage dafür, dass spätere grenzüberschreitende Workflows nicht an der Steuerlogik scheitern.

2. Endpoint- und Participant-IDs sind kein Nice-to-have

Peppol transportiert Dokumente nicht einfach an eine E-Mail-Adresse. In Peppol BIS Billing müssen sowohl Seller als auch Buyer eine elektronische Adresse angeben:

• Seller electronic address via cbc:EndpointID
• Buyer electronic address via cbc:EndpointID

Zusätzlich muss jeweils ein Scheme identifier vorhanden sein. Genau dort steckt die eigentliche Peppol-Adressierung: nicht nur die ID selbst, sondern auch das Schema, zu dem diese ID gehört.

Für ein brauchbares API-Modell solltest du also mindestens vorsehen:

• seller.endpoint_id
• seller.endpoint_scheme
• buyer.endpoint_id
• buyer.endpoint_scheme

Ohne diese Trennung wird aus einer späteren Peppol-Anbindung schnell ein Feld-Puzzle aus Freitexten, GLNs, Leitweg-IDs oder nationalen Kennungen.

3. Buyer Reference gehört ins Kernmodell

Die Buyer Reference ist in vielen hausinternen Rechnungsmodellen unterbewertet. In Peppol BIS Billing ist sie aber operativ wichtig:

• Entweder Buyer reference oder Purchase order reference muss vorhanden sein.
• In den deutschen Peppol-Regeln wird die Buyer Reference zusätzlich ausdrücklich hervorgehoben.

Warum ist das relevant? Weil Rechnungen beim Empfänger oft nicht nur in die Buchhaltung, sondern in Routing-, Freigabe- oder Beschaffungsprozesse laufen. Fehlt die Buyer Reference, scheitert nicht selten schon die automatische Zuordnung.

Ein robustes Modell braucht deshalb nicht nur:

• buyer_reference

sondern idealerweise auch:

• purchase_order_reference
• klare Regeln, wann welches Feld gesetzt wird

4. Tax Categories und Exemption Reasons gehören zusammen

Sobald du nicht mehr im simplen Standard-VAT-Fall bist, reichen Kategorie und Satz allein ebenfalls nicht mehr.

Peppol BIS Billing definiert klar:

• Für Exempt from VAT, Reverse charge, Intra-community supply, Export outside the EU und weitere Sonderfälle ist ein VAT exemption reason code oder ein VAT exemption reason text erforderlich.

Das ist der Punkt, an dem viele Systeme zu kurz greifen. Ein API-Feld wie is_tax_exempt: true ist dafür zu unpräzise.

Besser ist ein Modell mit:

• tax_category_code
• tax_rate
• tax_exemption_reason_code
• tax_exemption_reason_text

Damit bleibt die Fachlichkeit nachvollziehbar und später sauber auf UBL sowie auf Validierungsregeln abbildbar.

5. Credit Notes brauchen Referenzketten

Eine saubere Peppol-API darf Gutschriften und Korrekturen nicht wie „negative Rechnungen“ behandeln, denen jede Historie fehlt.

Peppol BIS Billing kennt für diesen Zweck BillingReference / InvoiceDocumentReference. Ein Preceding Invoice Reference muss die frühere Rechnungs-ID enthalten. Für bestimmte deutsche Konstellationen wird eine solche Referenz zusätzlich besonders relevant, etwa bei korrigierten Rechnungen.

Für dein Datenmodell bedeutet das:

• document_type nicht nur „invoice“, sondern auch sauber für Credit Note / Korrekturfall
• preceding_invoice_id
• optional weitere Referenzen wie Ausstellungsdatum oder Objektbezug

Wenn du das erst im Writer zusammenstückelst, verlierst du schnell Nachvollziehbarkeit und Testbarkeit.

6. Warum UBL für Peppol zentral ist

Peppol BIS Billing 3.0 dokumentiert seine Syntax ausdrücklich als:

• UBL Invoice
• UBL Credit Note

Das ist keine Nebensache. Es bedeutet:

• Das semantische Modell allein reicht nicht.
• Du brauchst am Ende korrekte UBL-Ausgabe.
• Rechnungen und Gutschriften haben unterschiedliche Root-Elemente und Dokumentcodes.

Im BIS ist cbc:InvoiceTypeCode mit Beispielwert 380 für Invoice dokumentiert, cbc:CreditNoteTypeCode mit Beispielwert 381 für Credit Note. Auch CustomizationID und ProfileID gehören zur dokumentierten UBL-Struktur.

Deshalb ist die richtige Reihenfolge für Softwareanbieter:

1. Datenmodell fachlich korrekt machen
2. Writer sauber auf UBL ausrichten
3. erst danach Transport, AP-Anbindung und Netzwerkintegration ergänzen

7. Welche Felder eine Peppol-nahe API mindestens modellieren sollte

Eine pragmatische Mindestliste sieht oft so aus:

• Dokumenttyp, Dokumentnummer, Ausstellungsdatum
• currency_code
• customization_id
• profile_id
• Buyer- und Seller-Stammdaten
• Buyer- und Seller-EndpointID jeweils mit Scheme
• buyer_reference
• purchase_order_reference
• payment_means_code
• Positionsdaten mit tax_category_code und tax_rate
• VAT-Breakdowns nach Kategorie + Satz
• tax_exemption_reason_code und/oder tax_exemption_reason_text
• Billing References für Credit Notes und Korrekturen

Nicht jedes Produkt muss heute schon jede Peppol-Funktion live ausliefern. Aber ohne diese Felder gibt es auch keine belastbare Grundlage für spätere Peppol-Workflows.

Fazit

Wenn du Peppol ernsthaft per API unterstützen willst, ist das eigentliche Projekt nicht „ein UBL-Writer“. Das eigentliche Projekt ist ein sauberes EN-16931- und Peppol-nahes Datenmodell.

Steuersatz allein reicht nicht. EndpointIDs sind Pflicht. Buyer Reference ist operativ relevant. Sonderfälle brauchen Tax Categories und Exemption Reasons. Und Gutschriften brauchen Referenzketten. Erst wenn diese Semantik steht, wird ein UBL-Writer stabil — und erst dann wird eine spätere Peppol-Anbindung realistisch.

Wenn du die europäische Richtung dahinter einordnen willst, lies als Nächstes auch unseren Beitrag zu ViDA 2030 und grenzüberschreitenden B2B-Rechnungen.

Quellen:

• OpenPeppol / Peppol BIS Billing 3.0 Home
• Peppol BIS Billing 3.0: UBL Invoice
• Peppol BIS Billing 3.0: UBL Credit Note
• Peppol BIS Billing 3.0: Buyer Reference
• Peppol BIS Billing 3.0: Buyer electronic address MUST be provided
• Peppol BIS Billing 3.0: Seller electronic address MUST be provided
• Peppol BIS Billing 3.0: VAT breakdown taxable amount by category and rate
• Peppol BIS Billing 3.0: TaxExemptionReason
• Peppol BIS Billing 3.0: TaxExemptionReasonCode
• Peppol BIS Billing 3.0: Preceding Invoice reference (BT-25)