Eine E-Rechnung über den SalesInvoice-Endpoint senden: Upload in jedem unterstützten Format, automatische Transformation, Routing und Statusverfolgung.
Das Senden einer E-Rechnung über die PSB API ist der am häufigsten genutzte Endpoint. Sie senden ein XML-Dokument im Format Ihrer Software an die API, und der PSB übernimmt Validierung, automatische Transformation in das vom Empfänger erwartete Format, Routing und Zustellung über das entsprechende Netzwerk.
POST /api/v1/{partyId}/salesInvoice/send
Die {partyId} in der URL ist der Peppol-Identifikator der sendenden Organisation (des Lieferanten). Die Anfrage enthält das XML-Dokument als Body (Content-Type application/xml). Sie können in jedem unterstützten Format einliefern: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA, ebInterface, Svefaktura, DICO, SETU und weitere. Der PSB erkennt das Dokumentformat automatisch, validiert das Dokument und transformiert es automatisch in das Format, das der Empfänger erwartet.
Hinweis: Die PSB bestimmt den Empfänger anhand der
EndpointIDin Ihrem XML-Dokument. Wenn dieses Element fehlt oder einen falschen Identifikator enthält, scheitert die Zustellung mit dem StatusInvoiceSentError. Stellen Sie sicher, dass Ihr Quellsystem die korrekte EndpointID einträgt. Mehr über Identifikatoren und Routing finden Sie im Artikel über Peppol-Identifikatoren.
Die PSB unterstützt Idempotency über den X-EConnect-DocumentId-Request-Header. Indem Sie bei jedem Upload-Request eine eigene UUID mitsenden, verhindern Sie doppelte Verarbeitung:
X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000
Wenn Sie dieselbe documentId erneut senden, antwortet die API mit 409 Conflict, der Absender weiß dann, dass das Dokument bereits verarbeitet wurde.
Hinweis: Verwenden Sie immer eine UUID/GUID als documentId. Verwenden Sie niemals die Rechnungsnummer, da dies Probleme verursacht, wenn Sie eine korrigierte Version derselben Rechnung erneut senden möchten.
Bevor Sie eine Rechnung versenden, können Sie über queryRecipientParty prüfen, ob und wie der Empfänger erreichbar ist:
POST /api/v1/{partyId}/salesInvoice/queryRecipientParty
Im Request-Body übergeben Sie eine Liste von Identifikatoren, zum Beispiel ["0106:12345678"], oder ein Objekt mit partyIds und metaAttributes. Optionale Queryparameter sind ?preferredDocumentTypeId und ?includeOptions.
Die Antwort enthält Informationen über:
Für erweiterte Lookups einschließlich der Access-Point-URL und des AP-Zertifikats steht eine separate Route zur Verfügung:
GET /api/v1/peppol/deliveryOption?partyIds={id}&documentFamily=Invoice&isCredit=false
Bei einer gescheiterten Zustellung wendet die PSB automatisch einen Retry-Mechanismus an:
InvoiceSentRetry-Event veröffentlichtInvoiceSentError-Event über Ihren WebhookHäufige Fehler beim Versand:
InvoiceSentError als Endstatus.Invalid payload — '{Wert}' ist kein gültiges xs:decimal auf einem Betragsfeldcbc:TaxInclusiveAmount, cbc:PriceAmount, cbc:LineExtensionAmount) in wissenschaftlicher Notation, etwa -1.336061E6 statt -1336061.00. UBL-Betragsfelder sind vom Typ xs:decimal, und der XML-Schema-Typ erlaubt keine Exponent-Notation; nur feste Dezimalnotation mit maximal 2 Nachkommastellen ist gültig. Tritt typischerweise bei großen oder negativen Beträgen auf, die intern als double serialisiert werden.E-Notation, keine Tausendertrennzeichen). Melden Sie das Problem dem Anbieter des versendenden Softwarepakets; eConnect kann dies nicht beheben, da der Wert in der gelieferten XML steht.The string '' is not a valid Decimal value bei einem PriceAmount-Feldcbc:PriceAmount) enthält bei einer oder mehreren Rechnungspositionen einen leeren String ("") statt einer Dezimalzahl. xs:decimal lässt einen leeren String als lexikalischen Wert nicht zu. Andere Ursache als wissenschaftliche Notation, gleiche Fehlermuster-Klasse.queryRecipientPartyHinweis: SI-UBL 1.2 (Simpler Invoicing 1.2) ist seit dem 1. Januar 2024 im Peppol-Netzwerk nicht mehr zulässig. Rechnungen in diesem Format führen zu einem
InvoiceSentError. Verwenden Sie NLCIUS (SI-UBL 2.0) oder Peppol BIS Billing V3. Überprüfen Sie dieCustomizationIDin Ihrem XML-Dokument, wenn dieser Fehler auftritt.
Ein erfolgreicher Upload liefert 200 OK mit der Dokument-ID in der PSB zurück. Verwenden Sie diese ID, um den Dokumentstatus über die API oder über Webhooks zu verfolgen.
Im Gegensatz zu purchaseInvoice kennt der salesInvoice-Endpoint kein DELETE. Dies ist eine bewusste Entscheidung, denn eine versendete oder abgelehnte Ausgangsrechnung ist ein audit-relevantes Lebensereignis: das Dokument bleibt im Audit-Trail nachvollziehbar, auch nachdem der Versand fehlgeschlagen ist.
Kunden fragen manchmal, ob eine abgelehnte Sales Invoice gestoppt oder gelöscht werden kann, zum Beispiel nachdem sie die Rechnung intern bereits gutgeschrieben haben. Die Antwort lautet:
Invalid payload): die PSB versetzt das Dokument in den Endstatus InvoiceSentError. Es wird kein Retry ausgeführt (nur 5xx-Fehler werden wiederholt). Das Dokument wird nicht nachträglich an den Empfänger zugestellt. Auf der PSB ist keine Aktion erforderlich; das Dokument befindet sich im Endstatus und wird 90 Tage zu Auditzwecken aufbewahrt.Dieser Unterschied im Lebenszyklus zwischen salesInvoice (kein DELETE) und purchaseInvoice (mit DELETE) ergibt sich aus der Rolle: eine Ausgangsrechnung ist eine vom Versender festgehaltene Handelsaktion, die rechtlich nachvollziehbar sein muss; eine eingehende Rechnung kann nach erfolgreichem Download aus dem eigenen System entfernt werden.
Beim Versand einer Rechnung übernimmt der PSB auch die steuerliche Berichterstattung. Im Rahmen der ViDA-Richtlinie (VAT in the Digital Age) generiert der PSB automatisch einen DRR (Digital Reporting Requirement) aus den Rechnungsdaten und übermittelt diesen an die zuständige Steuerbehörde. Als Integrator müssen Sie nichts Zusätzliches tun: der DRR wird aus derselben Rechnung abgeleitet, die Sie über den regulären Endpoint versenden. Statusnachrichten und CTC-Berichterstattungsnachrichten sind im Dokumentpreis enthalten.
Standardmäßig wählt die PSB automatisch den besten Kanal. Mit dem Queryparameter ?channel={hookId} können Sie einen bestimmten Zustellungskanal erzwingen (z. B. ein bestimmtes Netzwerk oder E-Mail-Fallback).
Anhänge (PDF, Bilder) können als base64 im UBL-Dokument als AdditionalDocumentReference eingebettet werden. Die PSB verarbeitet eingebettete Anhänge korrekt und stellt sie zusammen mit der Rechnung zu.
Hinweis: Der Send-Endpoint akzeptiert maximal 24 MB pro Anfrage (einschließlich HTTP-Overhead). Bei base64-kodierten Anhängen wächst die Payload um circa 33%, eine 18 MB große PDF ergibt also eine Anfrage von circa 24 MB. Payloads, die das Limit überschreiten, werden vom Webserver mit HTTP 500 (nicht 413) abgelehnt, noch bevor die Anwendungsvalidierung stattfindet. Reduzieren Sie große Anhänge oder versenden Sie sie über einen separaten Kanal.
Tipp: Der aktuelle Peppol BIS Billing 3.0-Standard unterstützt maximal eine
OrderReferencepro Rechnung. Bezieht sich eine Rechnung auf mehrere Bestellungen, müssen mehrere Rechnungen versendet werden.
Tipp: Einige Empfänger melden Fehler bei Rechnungen mit einem XML-Namespace-Präfix (z. B.
<urn:Invoice>statt<Invoice>). Beide Formen sind technisch korrektes XML gemäß W3C-Spezifikation. Wenn ein Empfänger dies als Ablehnungsgrund angibt, ist dies keine gültige Ablehnung innerhalb des Peppol-Netzwerks. Der Empfänger muss einen XML-Parser verwenden, der sowohl präfixierte als auch Standard-Namespaces korrekt verarbeitet.
Sie können in jedem Format einliefern, das der PSB unterstützt: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA, ebInterface, Svefaktura, DICO, SETU und weitere. Posten Sie das XML-Dokument als Body an POST /api/v1/{partyId}/salesInvoice/send mit Content-Type: application/xml. Der PSB erkennt das Format automatisch, validiert es und transformiert es in das Format, das der Empfänger erwartet. Der Empfänger wird über die EndpointID in Ihrem XML bestimmt.
Senden Sie bei jedem Upload den Header X-EConnect-DocumentId mit einer eigenen UUID. Wiederholen Sie dieselbe documentId, antwortet die API mit 409 Conflict und Sie wissen, dass das Dokument bereits verarbeitet wurde. Verwenden Sie niemals die Rechnungsnummer als documentId, da Sie bei einer korrigierten Neuversendung eine neue ID benötigen.
Nach einem erfolgreichen Upload gibt die API eine Dokument-ID in der PSB zurück, mit der Sie den Status über die API oder Webhooks verfolgen können. Bei vorübergehenden 5xx-Fehlern auf der Empfängerseite veröffentlicht die PSB pro Versuch ein InvoiceSentRetry-Event und unternimmt bis zu 8 Versuche über circa 35 Stunden; bei endgültigem Fehlschlag erhalten Sie ein InvoiceSentError-Event.
Möchten Sie zunächst testen, ob Ihr Dokument valide ist? Verwenden Sie die Validate API.
In der API ausprobieren