/ docs
ProduktWissenEntwickler
Plattform Control
Batch Hooks: Dokumente in großen Mengen abrufen

Dokumente periodisch in großen Mengen über Batch Hooks abrufen: Period, maxBatchSize und ZIP-Archiv.

Standardmäßig sendet der PSB für jedes empfangene Dokument sofort eine Webhook-Benachrichtigung. Bei hohen Volumina kann es effizienter sein, Dokumente periodisch in großen Mengen zu verarbeiten. Mit einem Batch Hook sammelt der PSB alle Events während eines konfigurierbaren Zeitraums und erstellt ein ZIP-Archiv.

Wie funktioniert ein Batch Hook?

Ein Batch Hook hört auf ein Topic (zum Beispiel InvoiceReceived) und sammelt alle Events, die innerhalb eines bestimmten Zeitraums eintreffen. Nach Ablauf des Zeitraums erstellt der PSB eine ZIP-Datei mit allen Dokumenten, die zu diesen Events gehören. Der PSB veröffentlicht dann ein neues Topic ({Topic}Batched), damit Sie das Archiv herunterladen können.

Der Ablauf ist wie folgt:

  1. Der PSB empfängt Dokumente und registriert Events
  2. Der Batch Hook sammelt Events, bis der Zeitraum abgelaufen ist oder die maximale Anzahl erreicht ist
  3. Der PSB erstellt ein ZIP-Archiv aller gesammelten Dokumente
  4. Ein {Topic}Batched-Event wird veröffentlicht (zum Beispiel InvoiceReceivedBatched)
  5. Ihr Webhook empfängt das Batched-Event und lädt das ZIP-Archiv herunter
Einen Batch Hook erstellen

Registrieren Sie einen Hook über die API mit einer batch://zip-Action:

{
  "action": "batch://zip?period=00:15:00&maxBatchSize=100",
  "topics": ["InvoiceReceived"]
}
Parameter
ParameterStandardBeschreibungperiod00:15:00 (15 Minuten)Der Sammelzeitraum im Format hh:mm:ss. Nach diesem Zeitraum wird der Batch abgeschlossen und das ZIP-Archiv erstellt.maxBatchSize100Die maximale Anzahl von Events pro Batch. Wenn diese Anzahl vor Ende des Zeitraums erreicht wird, wird der Batch sofort abgeschlossen.

Tipp: Wählen Sie period und maxBatchSize basierend auf Ihrem Dokumentvolumen. Bei niedrigen Volumina können Sie einen längeren Zeitraum einstellen (zum Beispiel eine Stunde). Bei hohen Volumina ist ein kürzerer Zeitraum mit einer höheren maxBatchSize praktischer.

Publish-Topic

Nach dem Abschluss eines Batches veröffentlicht der PSB ein neues Event auf dem Topic {Topic}Batched. Die Benennung folgt einem festen Muster:

Quell-TopicBatched-TopicInvoiceReceivedInvoiceReceivedBatchedOrderReceivedOrderReceivedBatched

Richten Sie einen regulären Webhook auf das Batched-Topic ein, um das ZIP-Archiv abzurufen:

{
  "action": "https://Ihr-endpoint.de/batches",
  "topics": ["InvoiceReceivedBatched"],
  "secret": "Ihr-geheimer-schluessel"
}
ZIP-Archiv

Die ZIP-Datei enthält alle im Batch gesammelten Dokumente, jeweils als separate XML-Datei. Die Dateinamen basieren auf der DocumentId. Das Archiv kann über die URL heruntergeladen werden, die im Batched-Event mitgegeben wird.

Kombination mit regulären Hooks

Sie können Batch Hooks mit regulären Webhooks kombinieren. Verwenden Sie zum Beispiel einen regulären Webhook für die sofortige Verarbeitung dringender Dokumente und einen Batch Hook für den periodischen Massenimport in Ihr ERP-System. Stellen Sie sicher, dass Sie Dokumente nicht doppelt verarbeiten, wenn Sie beide Hooks auf dasselbe Topic eingerichtet haben.

Wichtig: Batch Hooks verwenden dieselbe Retry-Logik wie reguläre Webhooks. Wenn das Batched-Event nicht erfolgreich zugestellt wird, versucht der PSB es bis zu 5 Tage lang erneut.

Häufig gestellte Fragen
Auf welchem Topic soll ich lauschen, um das ZIP-Archiv eines Batch Hooks abzuholen?

Nach Ende der Sammelperiode veröffentlicht der PSB ein Event auf {Topic}Batched, zum Beispiel InvoiceReceivedBatched bei Quell-Topic InvoiceReceived. Registrieren Sie einen regulären Webhook auf diesem Batched-Topic, um die Download-URL zu erhalten und die ZIP-Datei abzurufen.

Wie wirken period und maxBatchSize zusammen?

period (Standard 15 Minuten) legt fest, wie lange Events gesammelt werden, bevor der Batch geschlossen wird; maxBatchSize (Standard 100) schließt den Batch früher, wenn dieses Limit zuerst erreicht wird. Passen Sie beides an Ihr Volumen an: längere Perioden bei wenigen Dokumenten, kürzere Perioden oder höhere Limits bei Spitzenlast.

Kann ich einen Batch Hook und einen direkten Webhook auf demselben Topic kombinieren?

Ja, aber achten Sie auf doppelte Verarbeitung: Wenn beide dasselbe Quell-Topic nutzen, kann dasselbe Dokument zweimal ankommen. Nutzen Sie beides nur, wenn Sie das explizit abfangen, zum Beispiel direkt für dringende Fälle und Batch für Massenimport.

Die vollständige API-Spezifikation finden Sie unter psb.econnect.eu mit allen Konfigurationsmöglichkeiten.

API-Dokumentation ansehen

PreviousE-Mail-Hooks
NextSFTP-Integration