Batch hooky: hromadné získavanie dokumentov

Štandardne PSB odosiela pri každom prijatom dokumente okamžitú webhook notifikáciu. Pri veľkých objemoch môže byť efektívnejšie dokumenty spracovávať periodicky hromadne. Pomocou batch hooku PSB zhromažďuje všetky udalosti počas nastaviteľného obdobia a vytvorí z nich ZIP archív.

Ako batch hook funguje?

Batch hook reaguje na topik (napríklad InvoiceReceived) a zhromažďuje všetky udalosti, ktoré prídu v danom období. Po uplynutí obdobia PSB vytvorí ZIP súbor so všetkými dokumentmi patriacimi k týmto udalostiam. PSB následne publikuje nový topik ({Topic}Batched), aby ste mohli archív stiahnuť.

Postup je nasledovný:

PSB prijíma dokumenty a registruje udalosti
Batch hook zhromažďuje udalosti, kým neuplynie obdobie alebo sa nedosiahne maximálny počet
PSB vytvorí ZIP archív zo všetkých zhromaždených dokumentov
Publikuje sa udalosť {Topic}Batched (napríklad InvoiceReceivedBatched)
Váš webhook prijme batched udalosť a stiahne ZIP archív

Vytvorenie batch hooku

Zaregistrujte hook cez API s akciou batch://zip:

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

Parametre

Parameter

Predvolené

Popis

period

00:15:00 (15 minút)

Obdobie zhromažďovania vo formáte hh:mm:ss. Po tomto období sa dávka uzavrie a vytvorí sa ZIP archív.

maxBatchSize

100

Maximálny počet udalostí na dávku. Ak sa tento počet dosiahne pred koncom obdobia, dávka sa okamžite uzavrie.

Tip: Parametre period a maxBatchSize zvoľte podľa Vášho objemu dokumentov. Pri nízkom objeme môžete nastaviť dlhšie obdobie (napríklad hodinu). Pri vysokom objeme je praktickejšie kratšie obdobie s vyšším maxBatchSize.

Publikačný topik

Po uzavretí dávky PSB publikuje novú udalosť na topiku {Topic}Batched. Pomenovanie sleduje pevný vzor:

Zdrojový topik

Batched topik

InvoiceReceived

InvoiceReceivedBatched

OrderReceived

OrderReceivedBatched

Nastavte regulárny webhook na batched topik na stiahnutie ZIP archívu:

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

ZIP archív

ZIP súbor obsahuje všetky dokumenty zhromaždené v dávke, každý ako samostatný XML súbor. Názvy súborov sú založené na documentId. Archív je možné stiahnuť cez URL, ktorá je uvedená v batched udalosti.

Kombinácia s regulárnymi hookmi

Batch hooky môžete kombinovať s regulárnymi webhookmi. Použite napríklad regulárny webhook na okamžité spracovanie urgentných dokumentov a batch hook na periodický hromadný import do Vášho ERP systému. Dbajte však na to, aby ste nespracovávali dokumenty duplicitne, ak máte oba hooky nastavené na rovnakom topiku.

Pozor: Batch hooky používajú rovnakú logiku opätovných pokusov ako regulárne webhooky. Ak sa batched udalosť nepodarí úspešne doručiť, PSB to bude skúšať maximálne 5 dní.

Často kladené otázky

Na ktorom topiku máte počúvať, aby ste stiahli ZIP archív z batch hooku?

Po skončení zberného obdobia PSB publikuje udalosť na {Topic}Batched, napríklad InvoiceReceivedBatched, keď je zdrojový topik InvoiceReceived. Nastavte bežný webhook na tento batched topik, aby ste dostali URL na stiahnutie a stiahli ZIP súbor.

Ako spolu súvisia period a maxBatchSize?

period (predvolených 15 minút) určuje, ako dlho sa zbierajú udalosti pred uzavretím dávky; maxBatchSize (predvolených 100) dávku uzavrie skôr, ak sa tento limit dosiahne skôr. Prispôsobte obe hodnoty objemu: dlhšie obdobia pri malom počte dokumentov, kratšie obdobia alebo vyššie limity pri špičkách.

Dá sa kombinovať batch hook a priamy webhook na rovnakom topiku?

Áno, ale dávajte pozor na dvojité spracovanie: ak oba používajú rovnaký zdrojový topik, rovnaký dokument môže prísť dvakrát. Použite obe možnosti len vtedy, ak to výslovne ošetríte, napríklad okamžite pre urgentné prípady a dávku pre hromadný import.

Kompletnú API špecifikáciu nájdete na psb.econnect.eu so všetkými možnosťami konfigurácie.

Pozrite si API dokumentáciu