Wenn eine Rechnung für Ihre Organisation über Peppol oder ein anderes Netzwerk eingeht, speichert der PSB das Dokument und sendet eine Benachrichtigung an Ihren Webhook. In diesem Artikel erfahren Sie, wie Sie diese Benachrichtigung empfangen, das Dokument herunterladen und die Statusverwaltung einrichten.

Das Empfangen einer Rechnung umfasst vier Schritte:

1. Benachrichtigung: Der PSB sendet ein InvoiceReceived Webhook-Event an Ihren Endpoint
2. Download: Sie rufen das Dokument über den PurchaseInvoice-Endpoint ab
3. Verarbeitung: Sie verarbeiten die Rechnung in Ihrem eigenen System
4. Bereinigung (optional): Sie löschen das Dokument aus dem PSB

Um Rechnungen zu empfangen, benötigen Sie einen Webhook, der auf das Topic InvoiceReceived hört. Registrieren Sie ihn über die Hook API:

POST /api/v1/hook

{
  "action": "https://mein-system.de/webhook/invoices#meinSecretKey",
  "topics": ["InvoiceReceived"]
}

Sobald eine Rechnung eingeht, erhält Ihr Endpoint eine POST-Anfrage mit einem JSON-Payload. Dieser Payload enthält unter anderem die documentId und die partyId, mit denen Sie das Dokument abrufen können.

Tipp: Richten Sie auch einen Webhook auf das Topic InvoiceReceivedError ein, um Benachrichtigungen zu erhalten, wenn beim Empfang etwas schiefgeht.

Verwenden Sie die DocumentId aus dem Webhook-Payload, um die Rechnung abzurufen:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Die Antwort enthält das XML-Dokument (standardmäßig im Originalformat). Möchten Sie das Dokument in einem anderen Format erhalten? Verwenden Sie den Parameter targetDocumentTypeId:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download?targetDocumentTypeId={URN}

Der PSB transformiert das Dokument automatisch in das angegebene Format, bevor es zurückgegeben wird.

Der PSB bewahrt empfangene Dokumente nach folgendem Schema auf:

Es wird empfohlen, Dokumente direkt nach dem Empfang abzurufen und in Ihrem eigenen System zu speichern. Verlassen Sie sich nicht auf den PSB als Langzeitspeicher.

Nach der Verarbeitung können Sie das Dokument manuell löschen:

DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Dies löscht das Dokument endgültig aus dem PSB. Der Audit Trail bleibt verfügbar.

Nach dem Empfang können Sie den Verarbeitungsstatus einer Eingangsrechnung aktualisieren. Dies ist besonders relevant, wenn Sie Invoice Responses (Statusnachrichten) an den Absender senden möchten. Lesen Sie dazu den Artikel Invoice Response versenden.

Der PSB sendet nach dem Empfang eines Dokuments automatisch eine MLS-Nachricht (Message Level Status) an den Absender zurück. Dies bestätigt, dass das Dokument empfangen und zugestellt wurde. Als Integrator müssen Sie hierfür nichts konfigurieren: der PSB übernimmt dies vollständig. Wenn Sie selbst Dokumente versenden, erhalten Sie MLS-Feedback über das Webhook-Topic MessageLevelStatusReceived. Siehe Webhooks einrichten für die Konfiguration.

Wenn Sie keine Webhooks konfigurieren können (zum Beispiel in einer On-Premise-Umgebung ohne eingehenden Internetverkehr), können Sie Rechnungen auch per Polling abrufen:

GET /api/v1/{partyId}/purchaseInvoice HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Dieser Endpoint gibt eine Liste verfügbarer Eingangsrechnungen zurück. Webhooks sind jedoch immer die bevorzugte Methode, da sie Echtzeitverarbeitung und geringere API-Belastung bieten.

Wichtig: Erwägen Sie bei On-Premise-Integrationen auch den Reverse Webhook (HTTPS Inbound Hook), mit dem der PSB Dokumente pusht, ohne dass Ihr System direkt aus dem Internet erreichbar sein muss.

• Idempotent verarbeiten: In Ausnahmefällen kann der PSB ein Event mehrfach zustellen. Prüfen Sie auf Ihrer Seite, ob Sie ein Dokument bereits verarbeitet haben, bevor Sie es erneut importieren.
• Sofort herunterladen: Rufen Sie Dokumente so schnell wie möglich nach der Webhook-Benachrichtigung ab. Die 90-Tage-Aufbewahrung ist ein Sicherheitsnetz, keine Speicherstrategie.
• DocumentId protokollieren: Speichern Sie die PSB-DocumentId in Ihrem eigenen System für Nachverfolgung und eventuelle Fehlerbehebung.
• Format konvertieren: Wenn Sie ein bestimmtes XML-Format benötigen, verwenden Sie targetDocumentTypeId beim Herunterladen, anstatt selbst zu konvertieren.
• Webhook-Retries: Wenn Ihr Endpoint vorübergehend nicht erreichbar ist, versucht die PSB die Benachrichtigung bis zu 5 Tage lang erneut zuzustellen. Bei längerem Ausfall können Sie Batch Hooks als Fallback verwenden, um verpasste Dokumente nachträglich abzurufen.

Die vollständigen PurchaseInvoice-Endpoints und Response-Modelle finden Sie unter psb.econnect.eu.