Batch hook: hurtowe pobieranie dokumentów

Domyślnie PSB wysyła powiadomienie webhook dla każdego otrzymanego dokumentu. Przy dużych wolumenach efektywniejsze może być okresowe przetwarzanie dokumentów hurtowo. Za pomocą batch hooka PSB zbiera wszystkie zdarzenia w konfigurowalnym okresie i tworzy z nich archiwum ZIP.

Jak działa batch hook?

Batch hook nasłuchuje na topiku (na przykład InvoiceReceived) i zbiera wszystkie zdarzenia przychodzące w określonym okresie. Po upływie okresu PSB tworzy plik ZIP ze wszystkimi dokumentami należącymi do tych zdarzeń. PSB publikuje następnie nowy topik ({Topic}Batched), aby można było pobrać archiwum.

Przebieg jest następujący:

PSB otrzymuje dokumenty i rejestruje zdarzenia
Batch hook zbiera zdarzenia do upływu okresu lub osiągnięcia maksymalnej liczby
PSB tworzy archiwum ZIP ze wszystkich zebranych dokumentów
Publikowane jest zdarzenie {Topic}Batched (na przykład InvoiceReceivedBatched)
Webhook otrzymuje zdarzenie batched i pobiera archiwum ZIP

Tworzenie batch hooka

Rejestracja hooka przez API z akcją batch://zip:

{
  "action": "batch://zip?period=00:15:00&maxBatchSize=100",
  "topics": ["InvoiceReceived"]
}

Parametry

Parametr

Domyślnie

Opis

period

00:15:00 (15 minut)

Okres zbierania w formacie gg:mm:ss. Po upływie tego okresu wsad zostaje zamknięty i tworzone jest archiwum ZIP.

maxBatchSize

100

Maksymalna liczba zdarzeń na wsad. Jeśli ta liczba zostanie osiągnięta przed końcem okresu, wsad zostaje natychmiast zamknięty.

Wskazówka: Należy dobrać period i maxBatchSize na podstawie wolumenu dokumentów. Przy niskich wolumenach można ustawić dłuższy okres (na przykład godzinę). Przy wysokich wolumenach praktyczniejszy jest krótszy okres z wyższym maxBatchSize.

Topik publikacji

Po zamknięciu wsadu PSB publikuje nowe zdarzenie na topiku {Topic}Batched. Nazewnictwo podlega stałemu wzorcowi:

Topik źródłowy

Topik batched

InvoiceReceived

InvoiceReceivedBatched

OrderReceived

OrderReceivedBatched

Należy skonfigurować zwykły webhook na topiku batched, aby pobrać archiwum ZIP:

{
  "action": "https://jouw-endpoint.nl/batches",
  "topics": ["InvoiceReceivedBatched"],
  "secret": "jouw-geheime-sleutel"
}

Archiwum ZIP

Plik ZIP zawiera wszystkie dokumenty zebrane we wsadzie, każdy jako osobny plik XML. Nazwy plików bazują na documentId. Archiwum można pobrać przez URL podany w zdarzeniu batched.

Łączenie z regularnymi hookami

Batch hooki można łączyć z regularnymi webhookami. Na przykład webhook regularny do natychmiastowego przetwarzania pilnych dokumentów i batch hook do okresowego importu hurtowego do systemu ERP. Należy jednak zadbać o to, by nie przetwarzać dokumentów podwójnie, jeśli oba hooki są na tym samym topiku.

Uwaga: Batch hooki stosują tę samą logikę ponowień co regularne webhooki. Jeśli zdarzenie batched nie zostanie pomyślnie dostarczone, PSB ponawia próby przez maksymalnie 5 dni.

Najczęściej zadawane pytania

Na którym topiku należy nasłuchiwać, aby pobrać archiwum ZIP z batch hooka?

Po zakończeniu okresu zbierania PSB publikuje zdarzenie na {Topic}Batched, na przykład InvoiceReceivedBatched, gdy topik źródłowy to InvoiceReceived. Skonfiguruj zwykły webhook na tym topiku batched, aby otrzymać adres URL pobrania i pobrać plik ZIP.

Jak współdziałają ze sobą period i maxBatchSize?

period (domyślnie 15 minut) określa, jak długo zbierane są zdarzenia przed zamknięciem wsadu; maxBatchSize (domyślnie 100) zamyka wsad wcześniej, jeśli limit zostanie osiągnięty jako pierwszy. Dostosuj oba parametry do wolumenu: dłuższe okresy przy małej liczbie dokumentów, krótsze okresy lub wyższe limity przy szczytach.

Czy można łączyć batch hook i bezpośredni webhook na tym samym topiku?

Tak, ale należy uważać na podwójne przetwarzanie: jeśli oba używają tego samego topiku źródłowego, ten sam dokument może dotrzeć dwukrotnie. Oba mechanizmy należy stosować tylko wtedy, gdy jawnie się to obsłuży, na przykład natychmiastowo w pilnych przypadkach i wsadowo przy imporcie masowym.

Pełna specyfikacja API dostępna jest na psb.econnect.eu ze wszystkimi opcjami konfiguracji.

Zobacz dokumentację API