Které události webhook posílá?

invoice.received (přijatý doklad), invoice.sent (doklad předaný síti), invoice.delivered (přístupový bod příjemce potvrdil doručení doručenkou MLS), invoice.rejected (odmítnutý sítí nebo při validaci před odesláním), invoice.undeliverable (příjemce bez záznamu v síti Peppol), invoice.reported (hlášení Finanční správě předáno), invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere a testovací webhook.test. Nový typ vždy předem ohlásíme; formální schémata jsou v sekci webhooks naší OpenAPI specifikace.

Jak ověřím, že notifikace přišla od Verteco?

Pokud má firma secret, každé doručení nese hlavičku X-Verteco-Signature ve tvaru sha256=HMAC-SHA256(secret, raw tělo) a paralelně hlavičky Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix sekundy pokusu) a webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + tělo)). HMAC vždy počítejte nad přesnými bajty těla a odmítněte doručení s webhook-timestamp starším než 5 minut. Secret získáte přes POST /companies/{id}/webhook/secret; vrátí se jednou a rotace vygeneruje nový.

Co se stane, když je můj server dočasně nedostupný?

Notifikace se neztratí. Ukládá se do výstupní fronty a při neúspěchu uděláme 12 pokusů s exponenciálním odstupem od 30 sekund do 8 hodin (celkem přibližně 16 hodin); potom skončí jako dead-letter s možností opakovaného doručení a upozorněním e-mailem a je viditelná v Realtime logu portálu. Hlavička X-Verteco-Delivery-Id a pole eventId jsou při každém opakování stejné, proto podle nich deduplikujte.

Musím používat webhooky, nebo stačí polling?

Webhooky jsou doplněk, ne podmínka. Stejné informace získáte přes GET /sapi/document/sent a GET /sapi/document/receive s parametry ?since a ?until, doporučený interval je 1 až 5 minut. Webhook URL musí být veřejná a v produkci https://; loopback a lokální adresy blokuje ochrana před SSRF.

Kdy začnou webhooky reálně chodit?

Až když je firma aktivní v síti Peppol, tedy po výběru Verteco jako poskytovatele na portálu Finanční správy, a skutečně přijímá nebo odesílá doklady. Událost company.activated vám tento moment oznámí. Testovací notifikaci webhook.test si pošlete kdykoli tlačítkem Otestovat webhook v detailu firmy.

Propojení je zdarma. Služba stojí od €2/měs bez DPH za IČO, které odesílá nebo má zapnutý Archiv dat; příjem s vypnutým archivem je zdarma (do 1 000 faktur měsíčně). Během dobrovolného období před mandátem 1. 1. 2027 je všechno bezplatné.

Integrace / Pro vývojáře / Webhooky

Webhooky pro e-faktury

K dispozici

Portál pošle na vaši URL podepsanou událost při přijetí, předání, doručení, odmítnutí a nahlášení faktury Finanční správě, takže stav e-faktur nemusíte zjišťovat pollováním. Doručení je durable: událost se uloží do výstupní fronty a při výpadku vašeho serveru uděláme 12 pokusů s odstupem od 30 sekund do 8 hodin (celkem přibližně 16 hodin), potom skončí v dead-letter s možností opakovaného doručení. Webhook se nastavuje pro každou firmu zvlášť v jejím detailu v záložce Notifikace.

Získat plugin v portálu Vytvořit účet zdarma

Jak to funguje

1V portálu otevřete detail firmy a záložku Notifikace. Do pole Webhook pro notifikace vložte veřejnou https:// URL vašeho systému a klikněte na Uložit notifikace.
2Klikněte na Otestovat webhook: portál pošle podepsanou testovací událost webhook.test na uloženou URL a ukáže, co odeslal a co přišlo zpět (stav, tělo odpovědi, trvání).
3Získejte podpisový secret přes API: POST /companies/{id}/webhook/secret ho vrátí jednou. Ve svém systému ověřujte hlavičku X-Verteco-Signature (sha256=HMAC-SHA256 nad přesnými bajty těla) nebo hlavičky Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature).
4Zpracovávejte události idempotentně podle eventId, odmítněte doručení s webhook-timestamp starším než 5 minut, odpovězte 2xx do 15 sekund a těžší zpracování odložte do vlastní fronty. Na neznámý typ události odpovězte 2xx a zalogujte ho.

Co integrace řeší

✓Události invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable a invoice.reported plus stavy firmy (company.activated a další)
✓Dva podpisy najednou: X-Verteco-Signature (HMAC-SHA256) a hlavičky podle standardu Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature)
✓Durable doručení: výstupní fronta, 15 s timeout, 12 pokusů s odstupem od 30 sekund do 8 hodin (celkem přibližně 16 hodin), potom dead-letter s možností opakovaného doručení, upozorněním e-mailem a záznamem v Realtime logu
✓eventId a occurredAt v každé události: jednoznačný klíč pro deduplikaci a čas vzniku pro řazení
✓Časy sentAt, deliveredAt, receivedAt a fsReportedAt v událostech invoice.* jako důkaz odeslání, doručení a hlášení Finanční správě
✓Webhook per firma s vlastní URL a secretem; jedním API tokenem ho nastavíte všem firmám, které vlastníte

Časté otázky: e-faktury pro Webhooky

Které události webhook posílá?: invoice.received (přijatý doklad), invoice.sent (doklad předaný síti), invoice.delivered (přístupový bod příjemce potvrdil doručení doručenkou MLS), invoice.rejected (odmítnutý sítí nebo při validaci před odesláním), invoice.undeliverable (příjemce bez záznamu v síti Peppol), invoice.reported (hlášení Finanční správě předáno), invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere a testovací webhook.test. Nový typ vždy předem ohlásíme; formální schémata jsou v sekci webhooks naší OpenAPI specifikace.
Jak ověřím, že notifikace přišla od Verteco?: Pokud má firma secret, každé doručení nese hlavičku X-Verteco-Signature ve tvaru sha256=HMAC-SHA256(secret, raw tělo) a paralelně hlavičky Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix sekundy pokusu) a webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + tělo)). HMAC vždy počítejte nad přesnými bajty těla a odmítněte doručení s webhook-timestamp starším než 5 minut. Secret získáte přes POST /companies/{id}/webhook/secret; vrátí se jednou a rotace vygeneruje nový.
Co se stane, když je můj server dočasně nedostupný?: Notifikace se neztratí. Ukládá se do výstupní fronty a při neúspěchu uděláme 12 pokusů s exponenciálním odstupem od 30 sekund do 8 hodin (celkem přibližně 16 hodin); potom skončí jako dead-letter s možností opakovaného doručení a upozorněním e-mailem a je viditelná v Realtime logu portálu. Hlavička X-Verteco-Delivery-Id a pole eventId jsou při každém opakování stejné, proto podle nich deduplikujte.
Musím používat webhooky, nebo stačí polling?: Webhooky jsou doplněk, ne podmínka. Stejné informace získáte přes GET /sapi/document/sent a GET /sapi/document/receive s parametry ?since a ?until, doporučený interval je 1 až 5 minut. Webhook URL musí být veřejná a v produkci https://; loopback a lokální adresy blokuje ochrana před SSRF.
Kdy začnou webhooky reálně chodit?: Až když je firma aktivní v síti Peppol, tedy po výběru Verteco jako poskytovatele na portálu Finanční správy, a skutečně přijímá nebo odesílá doklady. Událost company.activated vám tento moment oznámí. Testovací notifikaci webhook.test si pošlete kdykoli tlačítkem Otestovat webhook v detailu firmy.
Kolik to stojí?: Propojení je zdarma. Služba stojí od €2/měs bez DPH za IČO, které odesílá nebo má zapnutý Archiv dat; příjem s vypnutým archivem je zdarma (do 1 000 faktur měsíčně). Během dobrovolného období před mandátem 1. 1. 2027 je všechno bezplatné.

Začněte ještě dnes: stačí výběr na portálu Finanční správy

Příjem zdarma · bez závazků a skrytých poplatkůSplňte si zákonnou povinnost 2027 za 2 minuty

Vybrat Verteco na portálu Finanční správy →Na portálu kliknete na „Pokračovať" (Pokračovat), přihlásíte se (slovensko.sk / eID nebo přihlašovací údaje do portálu FS) a potvrdíte výběr, zbytek zařídíme automatickyCertifikovaný poskytovatel Finanční správy (EFSK000031) · bez závazku · poskytovatele můžete kdykoli změnit

Jak výběr probíhá? (3 kroky, ~2 minuty)

1Kliknete na tlačítko výše, otevře se oficiální stránka Finanční správy „Výber certifikovaného poskytovateľa" (Výběr certifikovaného poskytovatele) s předvybraným Verteco. Kliknete na „Pokračovať" (Pokračovat).
2Přihlásíte se do Portálu finanční správy, přes slovensko.sk (eID / občanský průkaz s čipem) nebo svými přihlašovacími údaji do PFS, a potvrdíte výběr poskytovatele.
3Hotovo, přijde vám e-mail s přihlášením. Účet, firmu i registraci v síti Peppol vytvoříme automaticky. Pokud váš příjem už drží jiný poskytovatel, záznam nepřebíráme: pošleme vám postup s migračním kódem, nebo si v portálu zvolíte, že příjem zůstává u něj a přes nás jen odesíláte.
Nemáte eID? Na portál Finanční správy se přihlásíte i identifikátorem a heslem (přihlašovací údaje PFS). Případně se zaregistrujte e-mailem a heslem, firmu přidejte ručně a výběr dokončete později.
Nevidíte svou firmu ve výběru daňového subjektu? Nabízejí se jen subjekty, ke kterým máte na portálu FS autorizaci. Přidejte si ji v Osobní internetové zóně (Autorizácie → Pridať autorizovaného používateľa) a výběr dokončíte.
Podrobný návod k výběru na portálu FS (slovensky) →

Související: Peppol ověření firmy · průvodce e-fakturou 2027 · ceník · všechny integrace