Pro vývojáře: API reference

Verteco API je REST nad HTTPS. Request i response jsou JSON (UTF-8). Začněte vytvořením účtu, potom API tokenu, a udělejte první volání do minuty. Všechny cesty jsou relativní vůči základní URL níže.

Celé testovací prostředí najdete na test.peppol.verteco.digital. Chová se stejně jako produkce, navíc má testovací nástroje (FS webhook, verifikační token, odstranění firmy) a simulovaný výběr poskytovatele namísto portálu Finanční správy.

Base URL

https://peppol.verteco.digital/api/v1

Verze

v1 (v cestě). Zpětně nekompatibilní změny přijdou pod novou verzí.

Protokol

HTTPS only · TLS 1.2+ · TLS A+

Formát

application/json (UTF-8)

Auth

cookie session (portál) nebo Bearer token (server-to-server)

Časy

ISO-8601 (UTC), např. 2026-06-03T09:40:27Z

Účet i API token si vytvoříte v portálu (přes prohlížeč). Integrace potom běží výhradně přes API token. Registraci, přihlášení ani hesla vaše aplikace neřeší.

1. 1

   Vytvořte si účet v portálu

   Zaregistrujte se e-mailem a potvrďte ho odkazem z e-mailu.
2. 2

   Vygenerujte API token

   V portálu API tokeny → Vytvořit. Token vpt_… se zobrazí pouze jednou. Uložte si ho bezpečně.
3. 3

   Udělejte první volání

   Token použijte v hlavičce Authorization:

   javascriptKopírovať

   const res = await fetch('https://peppol.verteco.digital/api/v1/companies', {
   headers: { Authorization: 'Bearer vpt_8f2a…' },
   });
   const companies = await res.json();

4. 4

   Výběr poskytovatele na portálu Finanční správy

   V ostrém provozu je výběr Verteco na portálu FS (vpds.financnasprava.sk) potřebný i při čistě odesílacím použití: odemyká odesílání (Verifikační údaj) a firmu aktivuje. Příjem přitom může zůstat u poskytovatele vašeho účetního programu: příjemce má firma v síti právě jednoho, odesílatelů může mít více.

export BASE=https://test.peppol.verteco.digital   # production: https://peppol.verteco.digital
export KEY=vpt_…        # step 1

Kromě SAPI mock sandboxu (níže) provozujeme i plnohodnotné testovací prostředí, kompletní kopii tohoto portálu s oddělenými daty, kde si celý tok (registrace → firma → odeslání → přijetí → notifikace) vyzkoušíte end-to-end bez jakéhokoli dopadu na ostrý provoz.

URL

https://test.peppol.verteco.digital

Registrace

bez potvrzovacího e-mailu; účet je použitelný okamžitě

Schválení firmy

automatické, přímo v rozhraní nebo přes API (bez výběru na portálu Finanční správy, bez přihlášení na portál FS); hned po vytvoření firmy s IČ DPH můžete odesílat i přijímat

Registrace v síti

automatická do testovací sítě Peppol. Pozor na dvě vrstvy identifikátoru: API a portál používají stejný formát jako produkce (peppolParticipantId = 0245:<číslice DIČ>, váš integrační kód se nemění); do testovacího SMP/SML se firma technicky zapisuje jako 9950:SK<DIČ>, protože schéma 0245 vyžaduje ověřovací kód Finanční správy, který v testu neexistuje. V produkci se registruje 0245:<číslice DIČ> do ostré sítě až po výběru poskytovatele na portálu Finanční správy (přihlášení přes eID nebo přihlašovacími údaji)

Validace

reálná: EN 16931 + Peppol BIS 3.0 pravidla, stejná jako v ostrém provozu

Doručení

reálné přes testovací síť Peppol (AS4, testovací certifikát, testovací SML/SMP): příjemci registrovanému v testovací síti se faktura doručí jako přijatá (včetně e-mailu, PDF a webhooku); do ostré sítě nic neodchází

Doručenka

reálná MLS doručenka z testovací sítě

E-maily

reálně odcházejí (na adresy, které zadáte), s prefixem [TEST]

Simulace chyb

hlavička X-Sandbox-Simulate: 503 (nebo 502, 500, 429) na libovolném volání /sapi/document/* s platným tokenem vrátí odpovídající chybu; nic se nezpracuje ani neuloží. Při 500 (SAPI-PROC-500) a 429 (SAPI-SYS-003 s Retry-After) dostanete chybovou obálku SAPI; 503 a 502 projdou přes okraj sítě (DigitalOcean, Cloudflare) jako HTTP 504 s HTML tělem bez obálky, přesně tak vypadá skutečný výpadek zvenku, takže si ověříte i zpracování odpovědi, která není JSON. Chyby validace vyvoláte nevalidním XML, 429 i překročením 300 volání za minutu. V produkci se hlavička ignoruje

Cena

zdarma, bez limitů na zkoušení

Funguje tam všechno co tady: portál, REST API, SAPI-SK 1.0, e-shop pluginy i webhooky. Stačí v integraci vyměnit doménu za test.peppol.verteco.digital a použít tokeny vytvořené v testovacím prostředí. Ideální pro vývoj integrace, CI testy a zaškolení účetních před ostrým nasazením. Zkušební doklady patří jen tam: v ostrém provozu se každý domácí doklad mezi plátci DPH hlásí Finanční správě a hlášení se nedá vzít zpět. V ostrém portálu zkoušejte pouze tlačítkem „Poslat zkušební fakturu“ (0,00 €); od 1. 1. 2027 ostrý provoz čísla TEST-/VITAJTE- odmítne (test_document_in_production).

Pozn.: edge ochrana testovací domény blokuje generické hlavičky User-Agent: Python-urllib a User-Agent: Java/1.8.x (předvolený User-Agent HttpsURLConnection v Javě 8) odpovědí HTTP 403 „error code: 1010“ ještě před naším API; ostrá doména peppol.verteco.digital je propouští. Stačí nastavit vlastní User-Agent: v Javě buď parametrem JVM -Dhttp.agent=moje-app/1.0 (beze změny kódu; Java připojí „Java/1.8“, výsledný „moje-app/1.0 Java/1.8.0_xxx“ ochrana propouští, blokuje jen hlavičku začínající na „Java/1.8“), nebo na spojení conn.setRequestProperty("User-Agent", "moje-app/1.0"). Běžní klienti (requests, httpx, Java 11+, Apache HttpClient, okhttp, axios, Go, PHP, curl) fungují beze změny.

Proč se firmy schvalují automaticky

Finanční správa nemá testovací prostředí portálu VPDS: výběr poskytovatele na vpds.financnasprava.sk běží jen v produkci a ověřuje se přihlášením na portál FS (eID nebo přihlašovací údaje PFS), takže v ostrém provozu si nemůžete „vybrat“ libovolnou cizí firmu. Abyste přesto uměli integraci otestovat, v testovacím prostředí tento krok simulujeme: každá firma, kterou vytvoříte, se schválí automaticky (bez výběru na FS), takže si umíte založit odesílatele i příjemce a projít celý tok.

Pro testování FS webhooků (výběr poskytovatele) máme vlastní obdobu nástroje Finanční správy: test.peppol.verteco.digital/sandbox-nastroje. Vygenerujete si tam platný verifikační token (verifikační údaj) ve stylu FS a odešlete kompletní webhook na svůj endpoint, přesně jako to dělá portál FS při reálném výběru. Firmy vytvořené pro testování umíte zase odregistrovat (z portálu i z testovacího SMP), právě kvůli chybějícímu testovacímu režimu na straně Finanční správy.

Integrace se autentizuje API tokenem v hlavičce Authorization: Bearer vpt_…. Token vytvoříte v portálu (API tokeny); má formát vpt_ + 40 hex znaků, ukládáme jen jeho SHA-256 hash a má stejný přístup jako váš účet. Otestujte ho přes /auth/me:

curl https://peppol.verteco.digital/api/v1/auth/me -H 'Authorization: Bearer vpt_8f2a…'
# 200 → { "id": "…", "email": "vy(at)firma.sk" }   (token funguje)

Při chybějícím nebo neplatném tokenu API vrátí:

// 401 Unauthorized
{ "error": "unauthorized", "message": "Authentication required" }

Stránkování & idempotence

• Kontrakt jen roste: nová pole (vynechaná, když jsou null), nové volitelné parametry, nové endpointy a události. Existující názvy polí, hodnoty enumů a stavové kódy se nemění.
• Nový enum nebo událost webhooku může přibýt kdykoli; klient ignoruje, co nezná, a na neznámou událost odpoví 2xx.
• Časová razítka jsou ISO 8601 v UTC s proměnlivým počtem desetinných míst; parsujte je, neporovnávejte jako text. Částky přicházejí jako řetězce se dvěma desetinnými místy.
• Pokud by změna nemohla být aditivní, oznámíme ji v changelogu (odběr e-mailem) nejméně 90 dnů předem a starý tvar ponecháme během přechodného období.
• Bezpečnostní model API klíče (od 3. 10. 2026): klíč čte a odesílá doklady, spravuje firmy, notifikace a webhooky. Správu účtu a klíčů (vytvoření, rozsah a zrušení klíče, MFA, heslo, relace, pozvánky, převod firmy, podpisy smluv) provede jen přihlášená osoba; klíč tam dostane 403 token_not_allowed. GET /api/v1/tokens zůstává klíči dostupný.
• Odregistrace ze sítě (POST /api/v1/companies/{id}/deregister) zůstává pro klíč zavřená (403 token_not_allowed) s jednou výjimkou od 19. 10. 2026: firmu pod značkou zprostředkovatele (whiteLabel: true), kterou integrace sama založila, odregistruje klíč vlastníka s důkazem webhook secretem firmy. Hlavičky X-Company-Proof-Timestamp (unix sekundy, server přijme rozdíl nejvýše 300 s) a X-Company-Proof = lowercase hex HMAC-SHA256(klíč = aktuální webhook secret firmy, zpráva = "deregister:" + companyId + ":" + timestamp). Příklad: secret vpt_0123456789abcdef0123456789abcdef01234567, companyId 9fa8fd81-2c4e-4b7a-9d3e-5f6a7b8c9d0e, timestamp 1760000000 → X-Company-Proof e7e21ebd72506453b95c4cbb87c5556a21d93a5539cc7de6b32a29b9d7090901. Nesprávný, expirovaný nebo neuplatnitelný důkaz = 403 company_proof_invalid bez bližšího důvodu; každá odregistrace má řádek v evidenci nastavení firmy.
• Verze kontraktu je v openapi.json (info.version) a každá změna má řádek v changelogu s tagem API nebo Webhooky.

/changelog · /changelog/odber · openapi.json

Chyby mají jednotný tvar s machine-readable error kódem. Validační chyby přidávají mapu fields (první chyba na pole).

// business chyba
{ "error": "invalid_credentials", "message": "Invalid email or password" }

// validační chyba (400)
{ "error": "validation_failed", "message": "Some fields are invalid",
"fields": { "ico": "IČO musí byť 8 číslic" } }

HTTP stavy

200 / 201 / 204

úspěch (OK / vytvořeno / bez obsahu)

400

neplatný vstup (viz error / fields)

401

chybějící nebo neplatná autentizace

403

nedostatečné oprávnění (role)

404

zdroj neexistuje nebo k němu nemáte přístup

405

nepodporovaná HTTP metoda pro danou cestu

409

konflikt (IČO / e-mail už existuje)

415

nepodporovaný Content-Type (XML endpointy očekávají application/xml)

429

překročený rate limit (hlavičky RateLimit-* a Retry-After, tělo JSON rate_limited)

Nejčastější chybové kódy

Výpadek přístupového bodu a opakování

• Pokud API odpoví 502, 503 nebo 504, případně neodpoví vůbec, doklad jsme nepřevzali: zopakujte volání později se stejným Idempotency-Key, nic se neodešle dvakrát.
• Doklad, který API přijalo (202 ACCEPTED, i s retrying: true), odejde po obnově sám: přístupový bod doručení opakuje a stav vidíte přes GET /sapi/document/sent nebo webhook; pokud doručení nakonec vzdá, doklad skončí jako selhaný a stejný klíč ho pošle znovu.
• Příjem na úrovni sítě na portálu nezávisí: doručení, které během výpadku portálu neprošlo, odesílající přístupový bod podle pravidel Peppol zopakuje a doklad se v portálu objeví po obnově. Hlášení Finanční správě, která kvůli výpadku neodešla, doplní automatický obnovovací běh (přenosové selhání se opakuje, obsahové odmítnutí ne).
• Stav a historii dostupnosti najdete na /status; výpadek si v testovacím prostředí nasimulujete hlavičkou X-Sandbox-Simulate (sekce Testovací prostředí).

API je chráněno rate limitingem v 60sekundovém okně (per instance). Limit a zůstatek vracíme v každé odpovědi přes hlavičky; při překročení vrátí 429 Too Many Requests s Retry-After.

Běžná volání

dynamický limit s velkou rezervou, na API token (nebo session, jinak IP); aktuální hodnotu vrací hlavička RateLimit-Limit

Auth (/auth/*)

přísnější limit na IP (anti brute-force; mimo /auth/me a /auth/logout)

RateLimit-Limit

limit v okně

RateLimit-Remaining

kolik ještě zbývá

RateLimit-Reset

sekund do resetu okna

Retry-After

sekund do dalšího pokusu (při 429)

HTTP/2 429 Too Many Requests
RateLimit-Limit: <limit v okně>
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37

{ "error": "rate_limited", "message": "Too many requests. Slow down." }

HTTP/2 200
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
RateLimit-Policy: 300;w=60

Opaque tokeny vpt_… pro server-to-server přístup. Plaintext se zobrazí pouze jednou při vytvoření. Uložte si ho. Ukládáme jen SHA-256 hash a 12znakový prefix pro zobrazení.

curl -X POST https://peppol.verteco.digital/api/v1/tokens -b cookies.txt \
-H 'Content-Type: application/json' -d '{"name":"moje-aplikace"}'
# 201 Created
{ "id":"…","name":"moje-aplikace","token":"vpt_8f2a…","prefix":"vpt_8f2a3b…","createdAt":"…" }

Firmy (IČO / IČ DPH), které spravujete. Přístup je vázán na členství: vidíte jen firmy, jejichž jste členem. Tvůrce firmy se stává jejím owner.

curl -X POST https://peppol.verteco.digital/api/v1/companies \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"ico":"53412834","dic":"SK2121358349","legalName":"Verteco digital services, s. r. o."}'

# 201 Created
{ "id":"08dd…","ico":"53412834","dic":"SK2121358349","legalName":"…",
"registeredAddress":null,"peppolParticipantId":null,
"status":"pending_verification","role":"owner","createdAt":"2026-06-03T09:40:27Z" }

Pole status

pending_verification

po vytvoření; odesílání ještě není odemčeno

active

ověřená, odesílání odemčeno

Role člena

owner

tvůrce firmy (plný přístup)

admin

správce (úpravy, webhooky, ověření)

member

člen (čtení)

viewer

pouze čtení

Před odesíláním je třeba firmu ověřit přes Verifikační údaj (VÚ), podepsaný token od Finanční správy. Po úspěšném ověření se status firmy změní na active a odemkne se odesílání. V běžném toku VÚ nikdo nepřepisuje: Finanční správa ho pošle na náš webhook v momentu, kdy si firma na portálu FS zvolí Verteco (nebo vašeho zprostředkovatele), a ověření proběhne automaticky. Tento endpoint je záložní cesta pro případ, že VÚ máte z e-mailu FS a webhook nedorazil; neregistruje firmu do SMP.

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/verification \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"token":"<1024-hex VÚ>"}'

# 200 OK
{ "companyId":"08dd…","status":"active","sendingVerified":true,
"verificationMethod":"self","verifiedAt":"2026-06-15T…Z" }

Log Peppol dokladů (přijatých a odeslaných) za firmu. Naplňuje se, jak přes Access Point tečou faktury. Vázané na členství ve firmě, seřazené createdAt sestupně.

curl 'https://peppol.verteco.digital/api/v1/companies/{id}/documents?direction=received' \
-H 'Authorization: Bearer vpt_8f2a…'
# 200 OK
[ { "id":"…","direction":"received","peppolMessageId":"…","docTypeId":"…",
  "senderId":"0088:7300010000001","receiverId":"0245:2121358349",
  "invoiceNumber":"2026001","issueDate":"2026-06-03",
  "currency":"EUR","totalAmount":120.00,"status":"received","createdAt":"…" } ]

SAPI-SK je standardizované národní REST rozhraní mezi klientským/ERP systémem a Access Pointem (sapi-sk.sk). Implementujeme ho v plném rozsahu. Díky tomu nejste vázáni na náš proprietární tvar API a integraci napíšete jednou pro kterýkoli SAPI-SK Access Point. Přehled bez technických detailů je v článku SAPI-SK pro vývojáře.

Base URL

https://peppol.verteco.digital/sapi

Autentizace

OAuth2 client_credentials → krátkodobý access token (JWT)

client_id

UUID vašeho API tokenu (seznam v sekci API tokeny / dashboard)

client_secret

samotný vpt_… token z portálu

Verze

1.3 (10 operací: 4× auth, 6× dokumenty)

Sandbox (zkušební prostředí)

Chcete si SAPI-SK vyzkoušet bez registrace a bez rizika? Použijte veřejné sandbox přihlašovací údaje. Sandbox validuje požadavky přesně jako ostrý provoz, ale nikdy nic neodešle do sítě Peppol a nepracuje s reálnými daty; vrátí realistické mock odpovědi. Ideální pro vývoj, CI a onboarding integrace.

client_id

sandbox

client_secret

sandbox

send

plná validace kontraktu + mock 202 (nic se nedoručí)

receive

1 vzorový doklad sandbox-doc-0001 na test parsování a acknowledge

# 1) sandbox token (bez registrace)
curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "sandbox", "client_secret": "sandbox",
      "grant_type": "client_credentials" }'

# 2) mock odeslání: zvaliduje se, ale NIC se reálně nedoručí
curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer <sandbox access_token>' \
-H 'X-Peppol-Participant-Id: 0245:0000000000' \
-H 'Content-Type: application/json' \
-d '{ "metadata": { "documentId": "TEST-1",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "senderParticipantId": "0088:sandbox-sender",
        "receiverParticipantId": "0088:sandbox-receiver" },
      "payload": "<Invoice>…</Invoice>", "payloadFormat": "XML" }'
# 202 { "providerDocumentId": "sandbox-…", "status": "ACCEPTED", … }

# 3) vzorová schránka + detail vzorového dokladu
curl https://peppol.verteco.digital/sapi/document/receive \
-H 'Authorization: Bearer <sandbox access_token>'
curl https://peppol.verteco.digital/sapi/document/receive/sandbox-doc-0001 \
-H 'Authorization: Bearer <sandbox access_token>'

Autentizace

curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "<UUID tokenu>", "client_secret": "vpt_8f2a…",
      "grant_type": "client_credentials" }'
# 200 OK
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer",
"expires_in": 900, "refresh_token": "eyJhbGciOi…" }

// body
{ "refresh_token": "eyJhbGciOi…" }

Odeslání dokumentu

curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer eyJ…' \
-H 'X-Peppol-Participant-Id: 0245:2121358349' \
-H 'Idempotency-Key: 7b1f0e2a-…' \
-H 'Content-Type: application/json' \
-d '{ "metadata": {
        "documentId": "INV-2026-001",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "processId": "urn:…:bis:billing:3.0",
        "senderParticipantId": "0245:2121358349",
        "receiverParticipantId": "0088:7300010000001",
        "creationDateTime": "2026-06-17T10:00:00Z" },
      "payload": "<Invoice …>…</Invoice>",
      "payloadFormat": "XML" }'
# 202 Accepted
{ "providerDocumentId": "…", "status": "ACCEPTED",
"receivedAt": "2026-06-17T10:00:01Z", "timestamp": "…" }
# při status "REJECTED" nese odpověď i pole "detail"
# s důvodem odmítnutí (validační pravidla, např. BR-CO-15)

curl -X POST https://peppol.verteco.digital/sapi/document/validate \
-H 'Authorization: Bearer eyJ…' \
-H 'Content-Type: application/xml' \
--data-binary @faktura.xml
# 200 OK
{ "valid": false,
  "errors": [ "BR-CO-15: Invoice total amount with VAT (BT-112) = … " ],
  "warnings": [],
  "checkedAt": "2026-09-10T12:00:00Z" }

Příjem dokumentů

// 200 OK
{ "documents": [ { "documentId":"…","documentTypeId":"…",
  "senderParticipantId":"0088:…","receiverParticipantId":"0245:…",
  "creationDateTime":"2026-06-17T…Z" } ],
"nextPageToken": "50" }

Stav odeslaných dokumentů

// 200 OK
{ "documents": [ {
  "documentId": "…",
  "receiverParticipantId": "0245:1084695645",
  "peppolMessageId": "befc9112-…",
  "status": "delivered",
  "statusDateTime": "2026-07-09T14:52:31Z",
  "creationDateTime": "2026-07-09T14:52:12Z" } ],
"nextPageToken": null }

Doručenka (MLS) a důkazy doručení

Doručenka MLS (Peppol Message Level Status) je odpověď Access Pointu příjemce na naši zásilku: AP = přijato a doručeno, AB = doručeno bez obchodního potvrzení, RE = odmítnuto s důvodem. Portál ji uloží k odeslanému dokladu a podle ní přepne stav: AP i AB znamenají delivered (při AB začíná statusDetail „MLS AB: “ a mls.responseCode je AB; podle SPOG on MLS je to doručení bez obchodního potvrzení, ne výhrada), RE znamená rejected. Podle § 76a odst. 2 písm. d zákona 222/2004 musí poskytovatel umět prokázat datum a čas odeslání, doručení a přijetí; ty tři časy nese každý řádek GET /sapi/document/sent i webhook: sentAt (předání doručovací službě, tím je podle § 85o odst. 11 splněna povinnost vystavitele), deliveredAt (potvrzení AP příjemce doručenkou) a fsReportedAt (hlášení údajů FS). Zahraniční Access Point doručenku nemusí poslat nikdy: doklad zůstane delivered s detailem as4_receipt_only a bez MLS.

// 200 OK
{ "document": {
    "documentId": "…", "peppolMessageId": "befc9112-…", "status": "delivered",
    "sentAt": "2026-09-17T08:00:12Z", "deliveredAt": "2026-09-17T08:00:31Z", "fsReportedAt": null,
    "hasMls": true,
    "links": { "detail": "…/sapi/document/sent/…", "mls": "…/sapi/document/sent/…/mls" } },
  "mls": { "responseCode": "AP", "receivedAt": "2026-09-17T08:00:31Z", "url": "…/sapi/document/sent/…/mls" } }

Důkazy hlášení FS, integrita a časová osa (SAPI 1.8.14)

Od verze 1.8.14 nese každý řádek GET /sapi/document/sent i detail a seznam přijatých dokladů objekt fsReport: state = reported (hlášení předáno sběrnému bodu C5, reportedAt = fsReportedAt), pending (hlášení je dlužné, předání selhalo a opakuje se automaticky, reason = c5_unavailable) nebo not_required (hlášení nevzniká; reason vysvětluje proč: cross_border, self_send_test, issuer_without_vat_id, recipient_without_vat_id, not_billing_document, tdd_disabled, before_2026_09_01, not_recorded). Po předání přibude tddMessageId (SBDH InstanceIdentifier hlášení) a po odpovědi C5 c5ResponseCode (AP/AB/RE), c5ResponseAt, c5Detail a shrnutí outcome: accepted (AP), accepted_with_reservations (AB), rejected (RE) nebo null, dokud C5 neodpovědělo. outcome = rejected znamená, že hlášení jsme předali, ale Finanční správa ho odmítla (c5Detail nese porušené pravidlo, například BR-AE-08); state zůstává reported, protože předání proběhlo, a portál opravené hlášení odešle znovu automaticky (po přijetí se outcome změní na accepted). Odeslané řádky mají navíc statusReason (strojový kód za statusDetail: network_retrying, network_retrying_sent, as4_receipt_only, recipient_not_registered, transport_failed, mls_rejected, validation_failed), xmlSha256 (SHA-256 předaného XML, zůstává i po výmazu obsahu), retention a receiptRetention = permanent (doručenka MLS se nikdy nemaže). Doručenka v detailu má mls.sha256 a mls.messageId. Přijaté doklady dostaly peppolMessageId, status (received/acknowledged), receivedAt, acknowledgedAt a xmlSha256 (SHA-256 bajtů obchodního dokladu přesně tak, jak je vydává links.xml, bez přenosové obálky SBDH; počítá se při přijetí a zůstává i po výmazu obsahu). Oba seznamy filtrujete přes ?fsReport=reported|pending|not_required|rejected (rejected = outcome rejected), odeslané i přes ?status=undeliverable. Odpověď POST /sapi/document/send nese peppolMessageId už při převzetí. Všechno je doplněno jako nová pole, existující zůstávají nezměněna.

// POST { "documentIds": ["7c1e…", "9af0…", "neznámé"] }  (max 200)
{ "documents": [ {
    "documentId": "7c1e…", "status": "delivered", "statusReason": null, "peppolMessageId": "befc9112-…",
    "sentAt": "2026-09-21T08:00:12Z", "deliveredAt": "2026-09-21T08:00:31Z", "fsReportedAt": "2026-09-21T08:05:40Z",
    "fsReport": { "state": "reported", "reportedAt": "2026-09-21T08:05:40Z", "reason": null, "outcome": "accepted",
                  "tddMessageId": "3f2a…", "c5ResponseCode": "AP", "c5ResponseAt": "2026-09-21T08:06:02Z", "c5Detail": null },
    "xmlSha256": "9b74…", "retention": { "mode": "storage", "contentAvailableUntil": null }, "receiptRetention": "permanent",
    "hasMls": true, "links": { "detail": "…", "mls": "…" },
    "mls": { "responseCode": "AP", "receivedAt": "2026-09-21T08:00:31Z", "url": "…", "sha256": "e1c0…", "messageId": "mls-…" } } ],
  "missing": ["9af0…", "neznámé"] }

Hromadné odeslání

// request
{ "documents": [ {
  "itemId": "fa-2026-001",
  "idempotencyKey": "fa-2026-001",
  "metadata": { "documentId": "2026001", "documentTypeId": "…", "processId": "…",
                "senderParticipantId": "0245:2121358349", "receiverParticipantId": "0245:1084695645" },
  "payload": "<Invoice …>", "payloadFormat": "XML" } ] }

// 202 Accepted
{ "total": 2, "accepted": 1, "rejected": 1, "failed": 0,
"results": [
  { "itemId": "fa-2026-001", "ok": true,  "providerDocumentId": "…", "status": "ACCEPTED" },
  { "itemId": "fa-2026-002", "ok": false, "errorCode": "SAPI-AUTH-003", "errorMessage": "…" } ] }

Model chyb

Všechny SAPI chyby mají jednotnou obálku s kategorií, stabilním kódem, příznakem retryable a correlation_id pro podporu. Při chybě přihlášení (SAPI-AUTH-001) nese obálka navíc hint (lidsky čitelné vysvětlení, co patří do Client Id a Client Secret) a docs (odkaz na návod; pro programy MK-soft přímo na /navody/mksoft#prepojenie). Obě pole jsou volitelná a jinde chybí (1.8.20).

{ "error": {
  "category": "AUTH",
  "code": "SAPI-AUTH-001",
  "message": "Invalid client credentials.",
  "retryable": false,
  "correlation_id": "b4191dfc-…" } }

Při přijaté faktuře umíme firmu upozornit e-mailem nebo webhookem (POST na vaši URL). Doručení je durable: ukládá se do výstupní fronty a doručuje asynchronně (15 s timeout); při selhání opakujeme až 12× s exponenciálním backoffem (30 s → max 8 h, celkem přibližně 16 hodin), potom dead-letter. Výpadek vašeho serveru tedy notifikaci neztratí, doručíme ji při dalším pokusu. HTTP 401/403 znamená, že váš endpoint vyžaduje autentizaci, kterou neposíláme; ověřujte podpis webhook-signature a odpovídejte 2xx. SSRF ochrana blokuje loopback/lokální adresy; webhook URL musí být veřejná.

curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/webhook \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"url":"https://vas-system.sk/peppol/webhook"}'
# 200 OK { "url":"https://vas-system.sk/peppol/webhook", "hasSecret": true }

// 200 OK
{ "secret": "vpt_8f2a…" }

// 200 OK
{
"sent":     { "url": "https://vas-system.sk/peppol/webhook", "event": "webhook.test",
              "signed": true, "payload": "{…}" },
"received": { "status": 200, "body": "OK", "durationMs": 142, "error": null }
}
// 400 webhook_not_configured, pokud není uložená webhook URL

Payload webhooku

Při přijaté (invoice.received) i odeslané (invoice.sent) faktuře pošleme POST s tímto tělem; pole event rozlišuje typ.

Další dvě události oznamují verdikt sítě o faktuře, kterou jste odeslali: invoice.delivered (příjemcův Access Point potvrdil doručení doručenkou MLS) a invoice.rejected (odmítnutá, ať už sítí, nebo při validaci ještě před odesláním); invoice.undeliverable hlásí příjemce bez záznamu v síti Peppol (převzato, nahlášeno FS, nedoručeno). Nesou identifikaci dokladu a firmy (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId) plus status, statusDetail s důvodem odmítnutí a statusDateTime. Pokud první pokus o doručení selhal a přístupový bod ho sám opakuje (zpravidla do hodiny), doklad zůstává submitted a statusDetail začíná předponou network_retrying: ; po doručení přijde delivered, po vzdání rejected s předponou network_gave_up: . Díky nim nemusíte stav odeslaných faktur zjišťovat pollováním.

Událost company.activated přijde, když zákazník dokončí výběr poskytovatele na portálu Finanční správy (tělo: event, companyId, companyDic, peppolParticipantId, status, verifiedAt); company.deactivated zase při odregistrování firmy ze sítě (stejné tělo bez verifiedAt). company.smp_registered_elsewhere přijde, když firma dokončila výběr na portálu FS, ale její záznam v národním SMP drží jiný poskytovatel (tělo jako při company.activated plus action: "migration_code_required" a migrateUrl). Postup pro partnery je v dokumentaci pro zprostředkovatele. Dokud zákazník nevloží migrační kód, síť doručuje starému poskytovateli. Detaily v návodu /saas:

{
"event": "invoice.received",
"eventId": "7f1c2d9e-4b1a-4e3d-9c1f-0a2b3c4d5e6f",
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"documentId": "…",
"invoiceNumber": "2026001",
"senderId": "0088:7300010000001",
"supplierName": "Dodávateľ s.r.o.",
"receiverId": "0245:2121358349",
"issueDate": "2026-06-03",
"dueDate": "2026-06-17",
"deliveryDate": "2026-06-03",
"currency": "EUR",
"totalAmount": "120.00",
"peppolMessageId": "…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349"
}

Pole companyDic a peppolParticipantId identifikují firmu, které se událost týká (důležité pro partnery, kteří mají jednu webhook URL pro všechny své klienty).

Verdikt sítě o odeslané faktuře:

{
"event": "invoice.delivered",          // nebo "invoice.rejected"
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"documentId": "…",
"invoiceNumber": "2026001",
"receiverId": "0245:2120049096",
"peppolMessageId": "…",
"status": "delivered",                 // nebo "rejected"
"statusDetail": null,                  // při rejected: důvod odmítnutí
"statusDateTime": "2026-06-03T10:15:42Z"
}

Aktivace firmy po výběru na portálu Finanční správy:

{
"event": "company.activated",          // company.deactivated má stejné tělo bez verifiedAt
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"status": "active",
"verifiedAt": "2026-06-03T10:02:11Z"
}

Název události nese i hlavička X-Verteco-Event. Úplný seznam událostí: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere a testovací webhook.test. Neznámý typ události doporučujeme odložit stranou a zalogovat; nový typ vždy předem ohlásíme. Každá událost nese i occurredAt (čas vzniku události, ISO-8601 UTC), podle kterého události řadíte, a eventId (stejná hodnota i v hlavičce X-Verteco-Delivery-Id): jedinečný pro každou událost a neměnný při jejím opakování, proto je to správný klíč pro deduplikaci (peppolMessageId se opakuje napříč invoice.sent, invoice.delivered a invoice.reported). Události invoice.* nesou i časy sentAt, deliveredAt, receivedAt a fsReportedAt (ISO-8601 UTC, null dokud skutečnost nenastala). invoice.reported přijde, když bylo hlášení Finanční správě (TDD) k dokladu předáno doručovací službě (§ 85o odst. 11), a to i s odstupem dnů při výpadku sběrného bodu C5. Formální schémata všech událostí jsou v sekci webhooks specifikace OpenAPI.

Ověření podpisu

Pokud má firma secret, posíláme hlavičku X-Verteco-Signature ve tvaru sha256=HMAC-SHA256(secret, raw tělo) (lowercase hex). Vždy počítejte HMAC nad přesnými bajty těla:

import crypto from 'node:crypto';

// rawBody = přesné bajty těla requestu (ne znovu serializovaný JSON)
function verify(rawBody, header, secret) {
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Hlavičky každého doručení: X-Verteco-Event (název události), X-Verteco-Delivery-Id (= eventId v těle, stejné při každém opakování), X-Verteco-Signature (HMAC výše) a paralelně hlavičky podle standardu Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix sekundy okamžiku pokusu) a webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + tělo)). Klíčem jsou bajty vašeho secretu v UTF-8; knihovna standardwebhooks ho očekává jako whsec_ + base64(secret). Doporučený postup: ověřte podpis, odmítněte doručení s webhook-timestamp starším než 5 minut (ochrana před přehráním), zpracovávejte idempotentně podle eventId, odpovězte 2xx do 15 sekund a těžší zpracování odložte do vlastní fronty. Neúspěšné doručení opakujeme 12× s odstupem 30 s až 8 h (celkem přibližně 16 hodin); potom skončí jako dead-letter s upozorněním e-mailem a je viditelné v Realtime logu. Produkční webhook URL musí být https://, v testovacím prostředí je dovoleno i http://.

Hromadné nastavení: jeden token, více firem

Jeden API token (vázaný na váš účet/e-mail) spravuje všechny firmy, které vlastní: kdo firmu založí přes POST /companies, stává se jejím ownerem a umí jí nastavit webhook. Webhook je per firma (vlastní URL i secret), takže stejným tokenem napojíte libovolný počet firem:

# 1) seznam vašich firem (stránkovaně, viz Firmy)
curl 'https://peppol.verteco.digital/api/v1/companies?page=0&limit=100' -H 'Authorization: Bearer vpt_8f2a…'

# 2) pro KAŽDOU firmu {id}: nastavte webhook (a/nebo e-mail)
curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/notifications \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"webhookUrl":"https://vas-system.sk/peppol/webhook","notificationEmail":"faktury@firma.sk"}'

# 3) vyzvedněte podpisový secret (vrátí se JEN JEDNOU) a uložte si ho pro ověřování podpisu
curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → { "secret": "…" }

• Token musí být owner/admin dané firmy; u firmy, kde je jen member/viewer, vrátí 403 forbidden (žádný cross-tenant zásah).
• Každé firmě můžete dát jinou URL nebo všem stejnou; v payloadu je rozlišíte podle companyId (a receiverId).
• Při stovkách firem respektujte rate-limit na token (aktuální hodnotu vrací hlavička RateLimit-Limit); dávkujte s backoffem na 429 (hlavička Retry-After).
• Webhook reálně chodí, až když je firma aktivní v Peppolu (po výběru Verteco jako poskytovatele u Finanční správy) a tedy skutečně přijímá doklady.

Pole objektů vracených API.

Company

Document

User · Token · Webhook

DIČ

Daňové identifikační číslo (10 číslic). Slovenský Peppol identifikátor je 0245: + číslice DIČ, bez SK.

IČ DPH

Identifikační číslo pro DPH (SK + DIČ). Mají ho jen plátci DPH; neplátce vystavuje s kategorií O.

IČO

Identifikační číslo organizace (8 číslic). V API pole ico, v UBL BT-30.

Verifikační údaj (VÚ)

Podpis Finanční správy, který vznikne výběrem poskytovatele na portálu FS; odemyká odesílání za firmu.

VPDS

Výběr poskytovatele doručovací služby, aplikace Finanční správy, kde si subjekt volí pošťáka (nás).

TDD

Tax Data Document, hlášení údajů o faktuře Finanční správě; sestavujeme a posíláme ho za vás.

C5 / C6

Pátý a šestý roh Peppol modelu: přístupový bod Finanční správy, který TDD přijímá (0242:001180).

MLS

Message Level Status, doručenka od přístupového bodu příjemce (AP = přijato, RE = odmítnuto, AB = potvrzeno).

SBDH

Standard Business Document Header, obálka, v níž doklad cestuje sítí; její InstanceIdentifier je peppolMessageId.

SML / SMP

Adresář sítě: SML najde SMP příjemce, SMP řekne, jaký přístupový bod a jaké typy dokladů příjemce přijímá.

Nad rámec Peppol BIS Billing 3.0 se slovenští výrobci ERP a fakturačních systémů průběžně shodují na společné interpretaci volitelných polí (diskuse probíhá ve Slack kanálu Finanční správy). Níže jsou konvence, které náš portál už dnes respektuje: všechno jsou platné BIS konstrukce, přes naše API procházejí beze změny a přijaté doklady je zobrazují i v lidsky čitelném náhledu a PDF.

• Odpočet zdaněné zálohy na řádku: záporný řádek s cac:DocumentReference, kde cbc:ID nese číslo daňového dokladu k přijaté platbě a cbc:DocumentTypeCode je 130 (BIS: invoice line object identifier, max. 1 na řádek). Přijatá faktura s takovým řádkem se v našem náhledu zobrazí s poznámkou „odpočet zálohy, daňový doklad č. …“.
• Daňový doklad k přijaté platbě: podle FAQ Finanční správy se používá InvoiceTypeCode 388 (Tax invoice). Naším API i validací prochází; odpočet neuhrazené (nezdaněné) zálohy se vyjadřuje přes cbc:PrepaidAmount.
• Storno faktury: dobropis 381 (CreditNote) s cac:BillingReference na původní fakturu, ne záporná faktura 380. Pozor: kód 384 síť pro slovenské strany odmítá (pravidlo PEPPOL-EN16931-P0112 ho povoluje jen mezi německými subjekty); na opravu nahoru slouží vrubopis 383.
• BT-83 PaymentID: ve slovenské praxi se prosazuje tvar reference plátce /VS…/SS…/KS…; samotný variabilní symbol je také běžný. Naše zpracování hodnotu přenáší beze změny a zobrazuje ji u platebních údajů.
• Doplňkové údaje položek (šarže, sériová čísla, expirace) přes cac:AdditionalItemProperty s ustálenými názvy jako BatchNumber, SerialNumber, ExpirationDate.

K e-faktuře je možné připojit přílohy (PDF, obrázky) jako base64 v elementu cac:AdditionalDocumentReference (BT-125). U přijatých dokladů zpracujeme přílohy do 25 MB na přílohu; při odesílání musí celé XML včetně base64 příloh zůstat do 10 MB přes SAPI-SK a do 2 MB přes záložku Odeslat souborem v portálu. Peppol jednotný celosíťový limit neurčuje, jednotliví poskytovatelé si ho stanovují sami (FS FAQ 9/DPH/2025/IM, příklad č. 67), takže u velmi velkých příloh si ověřte i limit poskytovatele druhé strany.

Dva pomocné endpointy bez autentizace: stejné validační jádro a stejný SML lookup, jaké používá náš Access Point. Hodí se do CI i do kontrol před odesláním; platí na ně přísnější veřejný rate limit.

curl -X POST https://peppol.verteco.digital/api/v1/public/peppol-validate \
-H "Content-Type: application/xml" \
--data-binary @faktura.xml

// 200 OK
{
"valid": false,
"errors": [
  "BR-CO-09: [BR-CO-09]-The Seller VAT identifier (BT-31) … shall have a prefix in accordance with ISO code…"
],
"warnings": []
}
// 400 = prázdné tělo (empty_document) nebo dokument nad 3 MB (document_too_large)

// 200 OK
{
"registered": true,
"participantId": "0245:2121358349",
"smp": "sml.peppol-smp.sk",
"capabilities": ["Faktúra (BIS Billing)", "Dobropis", "Self-billing", "MLS doručenky"],
"lastCheckedAt": "2026-08-31T…Z"
}

Portál má vlastní server pro Model Context Protocol, otevřený standard, přes který se AI asistenti (Claude Code, Claude Desktop, Cursor, VS Code Copilot a další) připojují k externím systémům. Asistent se přihlásí běžným API klíčem účtu a dostane šest nástrojů; nikdy nevidí víc než ten účet a každé volání je v API logu klíče.

Adresa: https://peppol.verteco.digital/api/mcp. Transport: Streamable HTTP, JSON-RPC 2.0, bezstavově (POST /api/mcp, žádný SSE stream, GET vrátí 405). Přihlášení hlavičkou Authorization: Bearer <API klíč>. Podporované metody: initialize, ping, tools/list, tools/call, resources/list, prompts/list.

Nástroje

• list_companies: firmy účtu s Peppol ID, stavem a rolí (začátek každé konverzace)
• list_documents: odeslané/přijaté faktury firmy se stavem doručení a hlášení FS, stránkované
• get_document: detail faktury včetně doručenky MLS a hlášení FS, volitelně UBL XML (do 1 MB)
• check_participant: živé ověření příjemce v síti Peppol (SML)
• validate_document: validace UBL proti EN 16931 + Peppol BIS 3.0
• send_document: odeslání faktury za firmu, vyžaduje confirm = true a platí brána Verifikačního údaje

Připojení v Claude Code

claude mcp add --transport http verteco-peppol https://peppol.verteco.digital/api/mcp \
  --header "Authorization: Bearer vpt_..."

Claude Desktop (přes most mcp-remote, potřebuje Node.js)

{
  "mcpServers": {
    "verteco-peppol": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://peppol.verteco.digital/api/mcp", "--header", "Authorization: Bearer vpt_..."]
    }
  }
}

Odeslání faktury je právně závazné: nástroj bez confirm = true odmítne volání a asistent má v instrukcích serveru pokyn vyžádat si výslovný souhlas uživatele s konkrétní fakturou a příjemcem. Hotové konfigurace pro Cursor a VS Code a tlačítko na vytvoření klíče najdete v portálu: API klíče → záložka MCP server. API klíče → MCP server

Firma si v portálu zapne vlastní adresu <24 náhodných znaků>@peppol.send.verteco.app. E-mail s přílohou UBL XML poslaný na tuto adresu z povolené schránky odešleme přes síť Peppol stejně, jako kdybyste soubor nahráli na záložce Odeslat souborem; odesílatel dostane jednu odpověď s výsledkem za každou přílohu a doklad je v portálu i v API se stavem doručení, doručenkou MLS a hlášením FS. Nastavení: Propojení a integrace → Odesílání e-mailem (vlastník nebo správce firmy, jen po přihlášení). /dashboard/integrations/email

Pravidla zpracování

• Přijmeme jen zprávu od adresy na seznamu povolených odesílatelů firmy (nejvýše 20); ostatní zahodíme bez odpovědi.
• Předvoleně musí doména odesílatele projít ověřením SPF nebo DKIM u doručujícího serveru (sladění jako u DMARC, relaxed). Doručující server navíc odmítá zprávy, které neprošly ani SPF, ani DKIM, a zprávy proti DMARC politice odesílatele. Kontrolu lze vypnout v nastavení, nedoporučujeme.
• Příloha: UBL 2.1 Invoice nebo CreditNote (Peppol BIS Billing 3.0), přípona .xml, případně v obálce SBDH; nejvýše 10 příloh ve zprávě, 15 MB na přílohu, 200 zpráv na adresu za den. PDF a text zprávy se nezpracovávají.
• IFS Finvoice 2.0: přílohu .xml se SOAP obálkou IFS (IFSFinvoice) nebo samotný Finvoice převedeme na UBL a dál zpracujeme stejně. Pravidla převodu: INV02 nebo záporná částka = dobropis (381) s kladnými částkami a odkazem na původní fakturu (OriginalInvoiceNumber, u IFS OrderIdentifier); prodejce a odběratel podle slovenského IČ DPH (SellerOrganisationTaxCode, BuyerOrganisationTaxCode → 0245:DIČ), odběratel mimo SR se nepřevádí; rozpis DPH z VatSpecificationDetails, řádky s 0 % jako kategorie E s důvodem z VatFreeText, jinak „Osvobozeno od DPH“; zaokrouhlovací řádky IFS (základ 0,00, DPH 0,01) se vynechají, cena řádku, která nesedí s částkou řádku, se přepočítá; jednotky podle UN/ECE (kg → KGM, pcs → H87, h → HUR, neznámé → C62 s původním textem v poznámce řádku); vložený obraz faktury (InvoiceAttachments, PDF) jde jako příloha dokladu do 5 MB; jen EUR. Výsledek převodu je v odpovědi i v deníku firmy.
• Adresa pro výsledky: pokud faktury posílá systémová schránka, v nastavení zvolíte jinou adresu, na kterou chodí odpověď s výsledkem (pole replyTo v PUT /companies/{id}/email-send, prázdné = odpovědět odesílateli).
• Prodejce v XML (EndpointID dodavatele, BT-34) musí být tato firma, jinak zprávu odmítneme (přeposlaná faktura od vašeho dodavatele se nikdy neodešle jako vaše). Odběratel musí mít EndpointID se schématem (BT-49).
• Stejná zpráva (Message-ID) se zpracuje jednou. Doklad má v API a webhoocích origin = email, aktér = adresa odesílatele.

Veřejný health-check endpoint, vhodný pro monitoring.

// 200 OK
{ "service": "peppol-portal-backend", "status": "ok", "timestamp": "2026-06-17T…Z" }

Živý přehled všech komponent najdete na stránce stavu systémů.

Už v produkci (často mylně považované za chybějící)

• POST /companies/{id}/documents/send je stabilní rozhraní portálu; pro ERP integrace zůstává doporučené SAPI-SK s Idempotency-Key.
• Registrace do SMP probíhá automaticky po výběru na portálu FS; přechod od jiného pošťáka přes POST /companies/{id}/smp-migrate s migračním kódem.
• Doručenky MLS, důkazy doručení a hlášení FS (fsReport) v každém řádku /sapi/document/sent; replay webhooků za časové okno.
• Klíč omezený na vybrané firmy; MCP server pro AI asistenty; vzory UBL na /vzory; veřejný validátor.

Připravujeme (pořadí podle poptávky integrátorů)

• Asynchronní batch: POST /sapi/document/batch odpoví 202 s odkazem na job a stav po položkách.
• Změnový kanál GET /sapi/document/changes?since&cursor s kurzorem namísto stránkování offsetem.
• Expirace a rotace API klíčů v portálu, klíč jen pro čtení.
• Více webhook endpointů na firmu s filtrem událostí.