Batch hooky: hromadné získávání dokumentů

Standardně PSB odesílá při každém přijatém dokumentu okamžitou webhook notifikaci. Při velkých objemech může být efektivnější dokumenty zpracovávat periodicky hromadně. Pomocí batch hooku PSB shromažďuje všechny události během nastavitelného období a vytvoří z nich ZIP archiv.

Jak batch hook funguje?

Batch hook reaguje na topik (například InvoiceReceived) a shromažďuje všechny události, které přijdou v daném období. Po uplynutí období PSB vytvoří ZIP soubor se všemi dokumenty patřícími k těmto událostem. PSB následně publikuje nový topik ({Topic}Batched), abyste mohli archiv stáhnout.

Postup je následující:

PSB přijímá dokumenty a registruje události
Batch hook shromažďuje události, dokud neuplyne období nebo se nedosáhne maximálního počtu
PSB vytvoří ZIP archiv ze všech shromážděných dokumentů
Publikuje se událost {Topic}Batched (například InvoiceReceivedBatched)
Váš webhook přijme batched událost a stáhne ZIP archiv

Vytvoření batch hooku

Zaregistrujte hook přes API s akcí batch://zip:

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

Parametry

Parametr

Výchozí

Popis

period

00:15:00 (15 minut)

Období shromažďování ve formátu hh:mm:ss. Po tomto období se dávka uzavře a vytvoří se ZIP archiv.

maxBatchSize

100

Maximální počet událostí na dávku. Pokud se tento počet dosáhne před koncem období, dávka se okamžitě uzavře.

Tip: Parametry period a maxBatchSize zvolte podle Vašeho objemu dokumentů. Při nízkém objemu můžete nastavit delší období (například hodinu). Při vysokém objemu je praktičtější kratší období s vyšším maxBatchSize.

Publikační topik

Po uzavření dávky PSB publikuje novou událost na topiku {Topic}Batched. Pojmenování sleduje pevný vzor:

Zdrojový topik

Batched topik

InvoiceReceived

InvoiceReceivedBatched

OrderReceived

OrderReceivedBatched

Nastavte regulární webhook na batched topik pro stažení ZIP archivu:

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

ZIP archiv

ZIP soubor obsahuje všechny dokumenty shromážděné v dávce, každý jako samostatný XML soubor. Názvy souborů jsou založeny na documentId. Archiv lze stáhnout přes URL, která je uvedena v batched události.

Kombinace s regulárními hooky

Batch hooky můžete kombinovat s regulárními webhooky. Použijte například regulární webhook pro okamžité zpracování urgentních dokumentů a batch hook pro periodický hromadný import do Vašeho ERP systému. Dbejte však na to, abyste nezpracovávali dokumenty duplicitně, pokud máte oba hooky nastaveny na stejném topiku.

Pozor: Batch hooky používají stejnou logiku opětovných pokusů jako regulární webhooky. Pokud se batched událost nepodaří úspěšně doručit, PSB to bude zkoušet maximálně 5 dní.

Často kladené otázky

Na kterém topiku máte naslouchat, abyste stáhli ZIP archiv z batch hooku?

Po skončení sběrného období PSB publikuje událost na {Topic}Batched, například InvoiceReceivedBatched, když je zdrojový topik InvoiceReceived. Nastavte běžný webhook na tento batched topik, abyste obdrželi URL ke stažení a stáhli ZIP soubor.

Jak spolu souvisí period a maxBatchSize?

period (výchozí 15 minut) určuje, jak dlouho se shromažďují události před uzavřením dávky; maxBatchSize (výchozí 100) dávku uzavře dříve, pokud je tento limit dosažen dříve. Přizpůsobte obě hodnoty objemu: delší období při malém počtu dokumentů, kratší období nebo vyšší limity při špičkách.

Lze kombinovat batch hook a přímý webhook na stejném topiku?

Ano, ale dejte pozor na dvojí zpracování: pokud oba používají stejný zdrojový topik, stejný dokument může dorazit dvakrát. Používejte obě možnosti jen tehdy, pokud to výslovně ošetříte, například okamžitě pro urgentní případy a dávku pro hromadný import.

Kompletní API specifikaci naleznete na psb.econnect.eu se všemi možnostmi konfigurace.

Podívejte se na API dokumentaci