Ktoré udalosti webhook posiela?

invoice.received (prijatý doklad), invoice.sent (doklad odovzdaný sieti), invoice.delivered (prístupový bod príjemcu potvrdil doručenie doručenkou MLS), invoice.rejected (odmietnutý sieťou alebo pri validácii pred odoslaním), invoice.undeliverable (príjemca bez záznamu v sieti Peppol), invoice.reported (hlásenie Finančnej správe odovzdané), invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere a testovací webhook.test. Nový typ vždy vopred ohlásime; formálne schémy sú v sekcii webhooks našej OpenAPI špecifikácie.

Ako overím, že notifikácia prišla od Verteco?

Ak má firma secret, každé doručenie nesie hlavičku X-Verteco-Signature v tvare sha256=HMAC-SHA256(secret, raw telo) a paralelne hlavičky Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix sekundy pokusu) a webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + telo)). HMAC vždy počítajte nad presnými bajtmi tela a odmietnite doručenie s webhook-timestamp starším ako 5 minút. Secret získate cez POST /companies/{id}/webhook/secret; vráti sa jedenkrát a rotácia vygeneruje nový.

Čo sa stane, keď je môj server dočasne nedostupný?

Notifikácia sa nestratí. Ukladá sa do výstupnej fronty a pri neúspechu ju opakujeme až 8× s exponenciálnym odstupom od 30 sekúnd do 1 hodiny; potom skončí ako dead-letter s upozornením e-mailom a je viditeľná v Realtime logu portálu. Hlavička X-Verteco-Delivery-Id a pole eventId sú pri každom opakovaní rovnaké, preto podľa nich deduplikujte.

Musím používať webhooky, alebo stačí polling?

Webhooky sú doplnok, nie podmienka. Rovnaké informácie získate cez GET /sapi/document/sent a GET /sapi/document/receive s parametrami ?since a ?until, odporúčaný interval je 1 až 5 minút. Webhook URL musí byť verejná a v produkcii https://; loopback a lokálne adresy blokuje ochrana pred SSRF.

Kedy začnú webhooky reálne chodiť?

Až keď je firma aktívna v sieti Peppol, teda po výbere Verteco ako poskytovateľa na portáli Finančnej správy, a skutočne prijíma alebo odosiela doklady. Udalosť company.activated vám tento moment oznámi. Testovaciu notifikáciu webhook.test si pošlete kedykoľvek tlačidlom Otestovať webhook v detaile firmy.

Prepojenie je zadarmo. Služba stojí od €2/mes bez DPH za IČO, ktoré odosiela alebo má zapnutý Archív dát; príjem s vypnutým archívom je zadarmo (do 1 000 faktúr mesačne). Počas dobrovoľného obdobia pred mandátom 1. 1. 2027 je všetko bezplatné.

Integrácie / Pre vývojárov / Webhooky

Webhooky

K dispozícii

Portál pošle na vašu URL podpísanú udalosť pri prijatí, odovzdaní, doručení, odmietnutí a nahlásení faktúry Finančnej správe, takže stav e-faktúr nemusíte zisťovať polovaním. Doručenie je durable: udalosť sa uloží do výstupnej fronty a pri výpadku vášho servera ju opakujeme až 8× s odstupom 30 s až 1 h. Webhook sa nastavuje pre každú firmu zvlášť v jej detaile v záložke Notifikácie.

Získať plugin v portáli Vytvoriť účet zadarmo

Ako to funguje

1V portáli otvorte detail firmy a záložku Notifikácie. Do poľa Webhook pre notifikácie vložte verejnú https:// URL vášho systému a kliknite na Uložiť notifikácie.
2Kliknite na Otestovať webhook: portál pošle podpísanú testovaciu udalosť webhook.test na uloženú URL a ukáže, čo odoslal a čo prišlo späť (stav, telo odpovede, trvanie).
3Získajte podpisový secret cez API: POST /companies/{id}/webhook/secret ho vráti jedenkrát. Vo svojom systéme overujte hlavičku X-Verteco-Signature (sha256=HMAC-SHA256 nad presnými bajtmi tela) alebo hlavičky Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature).
4Spracúvajte udalosti idempotentne podľa eventId, odmietnite doručenie s webhook-timestamp starším ako 5 minút, odpovedzte 2xx do 15 sekúnd a ťažšie spracovanie odložte do vlastnej fronty. Na neznámy typ udalosti odpovedzte 2xx a zalogujte ho.

Čo integrácia rieši

✓Udalosti invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable a invoice.reported plus stavy firmy (company.activated a ďalšie)
✓Dva podpisy naraz: X-Verteco-Signature (HMAC-SHA256) a hlavičky podľa štandardu Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature)
✓Durable doručenie: výstupná fronta, 15 s timeout, až 8 opakovaní s odstupom 30 s až 1 h, potom dead-letter s upozornením e-mailom a záznamom v Realtime logu
✓eventId a occurredAt v každej udalosti: jednoznačný kľúč na deduplikáciu a čas vzniku na radenie
✓Časy sentAt, deliveredAt, receivedAt a fsReportedAt v udalostiach invoice.* ako dôkaz odoslania, doručenia a hlásenia Finančnej správe
✓Webhook per firma s vlastnou URL a secretom; jedným API tokenom ho nastavíte všetkým firmám, ktoré vlastníte

Časté otázky: e-faktúry pre Webhooky

Ktoré udalosti webhook posiela?: invoice.received (prijatý doklad), invoice.sent (doklad odovzdaný sieti), invoice.delivered (prístupový bod príjemcu potvrdil doručenie doručenkou MLS), invoice.rejected (odmietnutý sieťou alebo pri validácii pred odoslaním), invoice.undeliverable (príjemca bez záznamu v sieti Peppol), invoice.reported (hlásenie Finančnej správe odovzdané), invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere a testovací webhook.test. Nový typ vždy vopred ohlásime; formálne schémy sú v sekcii webhooks našej OpenAPI špecifikácie.
Ako overím, že notifikácia prišla od Verteco?: Ak má firma secret, každé doručenie nesie hlavičku X-Verteco-Signature v tvare sha256=HMAC-SHA256(secret, raw telo) a paralelne hlavičky Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix sekundy pokusu) a webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + telo)). HMAC vždy počítajte nad presnými bajtmi tela a odmietnite doručenie s webhook-timestamp starším ako 5 minút. Secret získate cez POST /companies/{id}/webhook/secret; vráti sa jedenkrát a rotácia vygeneruje nový.
Čo sa stane, keď je môj server dočasne nedostupný?: Notifikácia sa nestratí. Ukladá sa do výstupnej fronty a pri neúspechu ju opakujeme až 8× s exponenciálnym odstupom od 30 sekúnd do 1 hodiny; potom skončí ako dead-letter s upozornením e-mailom a je viditeľná v Realtime logu portálu. Hlavička X-Verteco-Delivery-Id a pole eventId sú pri každom opakovaní rovnaké, preto podľa nich deduplikujte.
Musím používať webhooky, alebo stačí polling?: Webhooky sú doplnok, nie podmienka. Rovnaké informácie získate cez GET /sapi/document/sent a GET /sapi/document/receive s parametrami ?since a ?until, odporúčaný interval je 1 až 5 minút. Webhook URL musí byť verejná a v produkcii https://; loopback a lokálne adresy blokuje ochrana pred SSRF.
Kedy začnú webhooky reálne chodiť?: Až keď je firma aktívna v sieti Peppol, teda po výbere Verteco ako poskytovateľa na portáli Finančnej správy, a skutočne prijíma alebo odosiela doklady. Udalosť company.activated vám tento moment oznámi. Testovaciu notifikáciu webhook.test si pošlete kedykoľvek tlačidlom Otestovať webhook v detaile firmy.
Koľko to stojí?: Prepojenie je zadarmo. Služba stojí od €2/mes bez DPH za IČO, ktoré odosiela alebo má zapnutý Archív dát; príjem s vypnutým archívom je zadarmo (do 1 000 faktúr mesačne). Počas dobrovoľného obdobia pred mandátom 1. 1. 2027 je všetko bezplatné.

Začnite ešte dnes: stačí výber na portáli Finančnej správy

Príjem zadarmo · bez viazanosti a skrytých poplatkovSplňte si zákonnú povinnosť 2027 za 2 minúty

Vybrať Verteco na portáli Finančnej správy →Na portáli dáte „Pokračovať", prihlásite sa (slovensko.sk / eID alebo prihlasovacie údaje do portálu FS) a potvrdíte výber. Zvyšok spravíme automatickyCertifikovaný poskytovateľ (EFSK000031) · bez viazanosti · poskytovateľa môžete kedykoľvek zmeniť

Ako výber prebieha? (3 kroky, ~2 minúty)

1Kliknete na tlačidlo vyššie. Otvorí sa oficiálna stránka Finančnej správy „Výber certifikovaného poskytovateľa" s predvybraným Verteco. Kliknete „Pokračovať".
2Prihlásite sa na Portál finančnej správy, cez slovensko.sk (eID / občiansky s čipom) alebo svojimi prihlasovacími údajmi do PFS, a potvrdíte výber poskytovateľa.
3Hotovo. Príde vám e-mail s prihlásením. Účet, firmu aj registráciu v sieti Peppol vytvoríme automaticky. Ak váš príjem už drží iný poskytovateľ, záznam nepreberáme: pošleme vám postup s migračným kódom, alebo si v portáli zvolíte, že príjem ostáva u neho a cez nás len odosielate.
Nemáte eID? Na portál Finančnej správy sa prihlásite aj identifikátorom a heslom (prihlasovacie údaje PFS). Prípadne sa zaregistrujte e-mailom a heslom, firmu pridajte ručne a výber dokončte neskôr.
Nevidíte svoju firmu vo výbere daňového subjektu? Ponúkajú sa len subjekty, za ktoré máte na portáli FS autorizáciu. Pridajte si ju v Osobnej internetovej zóne (Autorizácie → Pridať autorizovaného používateľa) a výber dokončíte.
Podrobný návod k výberu na portáli FS →

Súvisiace: Peppol overenie firmy · sprievodca e-faktúrou 2027 · cenník · všetky integrácie