Peppol für Ihre Verkäufer

Über Peppol gehen Rechnungen direkt in die Buchhaltung des Empfängers, ohne E-Mail und ohne Portal. Unser Peppol-Zugangspunkt sendet die XRechnung, die wir für die Rechnung erzeugt und archiviert haben, unverändert. Jeder Verkäufer, der über Peppol sendet, wird dort einmal registriert.

Aktivieren

Voraussetzungen: ein Tarif mit echtem Peppol (Growth oder höher), ein verifizierter Verkäufer in Deutschland und als Peppol-Adresse seine USt-IdNr. mit Schema 9930 (z. B. 9930:DE136695976).

# Admin-Schlüssel (live); 201 beim ersten Aufruf, danach 200 mit derselben Registrierung
curl -s -X POST $BASE/sellers/<sellerId>/peppol -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"receive": false}'
curl -s $BASE/sellers/<sellerId>/peppol -H "Authorization: Bearer $KEY"     # Stand

Die Antwort hat status (pending, verified, rejected, error), bei Fehlern statusReason und statusMessage sowie explanation auf Deutsch und Englisch. Jede Änderung sendet das Webhook-Ereignis seller.status_changed.

Der Link zur Identitätsprüfung

Bevor ein Verkäufer senden kann, bestätigt eine vertretungsberechtigte Person des Unternehmens (z. B. die Geschäftsführung) ihre Identität. Den Link dazu enthält verificationUrl; nur Admin-Schlüssel sehen ihn. Geben Sie ihn nur an diese Person weiter: Er gilt für dieses Unternehmen.

curl -s -X POST $BASE/sellers/<sellerId>/peppol/verification -H "Authorization: Bearer $KEY"   # neuer Link

Ein neuer Link geht höchstens alle 10 Minuten und fünfmal am Tag (429 peppol.link-limit mit Retry-After). Ändern sich USt-IdNr. oder Handelsregisternummer des Verkäufers, beginnt eine neue Prüfung; bis sie bestanden ist, antworten echte Peppol-Zustellungen mit 409 peppol.identity-check-pending.

Nur senden oder auch empfangen

Verkäufer werden nur zum Senden registriert. Empfangen ist eine eigene Entscheidung: Eine Peppol-Adresse kann nur bei einem Anbieter Rechnungen empfangen. Empfängt der Verkäufer schon über eine andere Software, würde ein Wechsel dort den Empfang beenden.

curl -s -X POST $BASE/sellers/<sellerId>/peppol/receiving -H "Authorization: Bearer $KEY"     # auch empfangen

Empfangen beginnt erst nach bestandener Identitätsprüfung und nur, wenn kein anderer Anbieter die Adresse bedient; sonst nennt receivingBlocked diesen Anbieter. Wir übernehmen den Empfang nie ungefragt.

Zustellen und die Status

curl -s -X POST $BASE/invoices/<id>/deliveries -H "Authorization: Bearer $KEY" \
  -H 'Idempotency-Key: re-2026-0042-peppol' -H 'Content-Type: application/json' \
  -d '{"channel":"peppol","recipient":"0204:04011000-12345-34"}'

PENDING: wartet auf den Versand.
SENT: beim Zugangspunkt angenommen, unterwegs.
DELIVERED: beim Zugangspunkt des Empfängers angekommen.
FAILED / REJECTED: nicht angekommen; failure nennt den Grund.
OUTCOME_UNKNOWN: der Versand hat nicht eindeutig geantwortet. Wir suchen die Rechnung beim Zugangspunkt und übernehmen sie, wenn sie dort ist. Nur wenn sie nach 30 Minuten noch fehlt, senden wir sie ein einziges Mal erneut, nie blind doppelt, damit der Empfänger sie nicht zweimal bucht.
UNCONFIRMED: keine Bestätigung binnen 72 Stunden; ein erneuter Versand braucht "resend": true.

Änderungen kommen als delivery.updated-Webhook.

Fehlermeldungen

Eine Zustellung, die nicht angekommen ist, hat ein failure mit festem code und Texten auf Deutsch (de) und Englisch (en), die Sie Ihren Nutzern zeigen können:

`code`	Bedeutung	Was tun
`not-on-peppol`	Der Empfänger ist im Peppol-Netz nicht erreichbar.	Adresse prüfen oder `fallbackEmail` nutzen.
`format-not-supported`	Der Empfänger nimmt dieses Format nicht an.	Beim Empfänger nachfragen; per E-Mail senden.
`validation`	Der Zugangspunkt hat das Dokument abgelehnt.	Rechnung mit `/validate` prüfen, korrigieren, neu ausstellen.
`transport`	Die Übertragung ist fehlgeschlagen.	Später erneut senden.
`recipient-rejected`	Der Empfänger hat die Rechnung abgelehnt.	Mit dem Empfänger klären.
`duplicate`	Diese Rechnung wurde schon gesendet.	Nichts; sie wird nicht erneut gesendet.
`sender-not-registered`	Der Verkäufer ist (noch) nicht registriert.	Peppol aktivieren, Identitätsprüfung abschließen.
`other`	Sonstiger Grund (siehe Text).	Text lesen; bei Bedarf Support fragen.

Fehler beim Anlegen der Zustellung: 409 peppol.not-activated (Peppol für den Verkäufer zuerst aktivieren), 409 peppol.identity-check-pending, 503 delivery.peppol-unavailable (auf dieser Installation ist kein Zugangspunkt eingerichtet). Ist der Zugangspunkt nur vorübergehend nicht nutzbar, bleibt die Zustellung PENDING und geht raus, sobald er wieder funktioniert.

Empfangen und `invoice.received`

Empfangene Dokumente prüfen wir beim Eingang mit derselben Prüfung wie /validate und speichern sie unverändert mit dem Ergebnis (validation: valid oder invalid) und dem Prüfbericht, auch wenn sie Fehler haben.

curl -s "$BASE/received-documents?sellerId=<sellerId>&validation=invalid" -H "Authorization: Bearer $KEY"
curl -s $BASE/received-documents/<id>/content -H "Authorization: Bearer $KEY" -o empfangen.xml
curl -s $BASE/received-documents/<id>/report -H "Authorization: Bearer $KEY"
curl -s $BASE/received-documents/<id>/pdf -H "Authorization: Bearer $KEY" -o empfangen.pdf

Jedes empfangene Dokument sendet document.received (documentId, sellerId, sender); Rechnungen und Gutschriften zusätzlich invoice.received mit documentId, sellerId, kind (invoice oder credit-note), validation und sender. Andere Dokumentarten (Bestellungen, Antworten) werden mit kind other gespeichert.