E-faktúra na Slovensku: jednoducho a po slovensky

Nemusíte byť technik. Ak ste živnostník, s. r. o. alebo účtovník, stačí vám náš portál v prehliadači: faktúry prijímate aj vystavujete klikaním, bez programovania. Takto to funguje v troch krokoch:

1. 1

   Zaregistrujte sa (zadarmo)

   Vytvorte si účet e-mailom v registrácii. Príjem faktúr je zadarmo (do 1000 mesačne).

2. 2

   Vyberte si nás na portáli Finančnej správy

   Aby vám mohli chodiť e-faktúry, zvoľte si nás ako svojho certifikovaného poskytovateľa (digitálneho poštára) na portáli FS (potvrdzuje sa cez eID). My vás potom automaticky zaregistrujeme do siete Peppol a pošleme e-mail s prihlásením.

3. 3

   Prijímajte a vystavujte faktúry

   Prijaté faktúry vám prídu do portálu aj e-mailom. Faktúru vystavíte v jednoduchom editore (ako vo Worde), alebo si existujúcu faktúru duplikujete na pár klikov. Daňové hlásenie na Finančnú správu (TDD) odošleme za vás automaticky.

Podrobné návody (po slovensky, pre začiatočníkov):

Všetky návody na jednom mieste: Sprievodca e-fakturáciou.

Verteco API je REST nad HTTPS. Request aj response sú JSON (UTF-8). Začnite vytvorením účtu, potom API tokenu, a urobte prvé volanie do minúty. Všetky cesty sú relatívne voči základnej URL nižšie.

Celé testovacie prostredie nájdete na test.peppol.verteco.digital. Správa sa rovnako ako produkcia, navyše má testovacie nástroje (FS webhook, verifikačný token, odstránenie firmy) a simulovaný výber poskytovateľa namiesto portálu Finančnej správy.

Base URL

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

Verzia

v1 (v ceste). Spätne nekompatibilné zmeny prídu pod novou verziou.

Protokol

HTTPS only · TLS 1.2+ · TLS A+

Formát

application/json (UTF-8)

Auth

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

Časy

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

Účet aj API token si vytvoríte v portáli (cez prehliadač). Integrácia potom beží výhradne cez API token. Registráciu, prihlásenie ani heslá vaša appka nerieši.

1. 1

   Vytvorte si účet v portáli

   Zaregistrujte sa e-mailom a potvrďte ho odkazom z e-mailu.
2. 2

   Vygenerujte API token

   V portáli API tokeny → Vytvoriť. Token vpt_… sa zobrazí iba raz. Uložte si ho bezpečne.
3. 3

   Urobte prvé volanie

   Token použite v hlavičke Authorization:

   javascriptKopírovať

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

Okrem SAPI mock sandboxu (nižšie) prevádzkujeme aj plnohodnotné testovacie prostredie, kompletnú kópiu tohto portálu s oddelenými dátami, kde si celý tok (registrácia → firma → odoslanie → prijatie → notifikácie) vyskúšate end-to-end bez akéhokoľvek dopadu na ostrú prevádzku.

URL

https://test.peppol.verteco.digital

Registrácia

bez potvrdzovacieho e-mailu; účet je použiteľný okamžite

Schválenie firmy

automatické, priamo v rozhraní alebo cez API (bez výberu na portáli Finančnej správy, bez eID); hneď po vytvorení firmy s IČ DPH môžete odosielať aj prijímať

Registrácia v sieti

automatická do testovacej siete Peppol. Pozor na dve vrstvy identifikátora: API a portál používajú rovnaký formát ako produkcia (peppolParticipantId = 0245:<číslice DIČ>, váš integračný kód sa nemení); do testovacieho SMP/SML sa firma technicky zapisuje ako 9950:SK<DIČ>, lebo schéma 0245 vyžaduje overovací kód Finančnej správy, ktorý v teste neexistuje. V produkcii sa registruje 0245:<číslice DIČ> do ostrej siete až po výbere poskytovateľa cez eID

Validácia

reálna: EN 16931 + Peppol BIS 3.0 pravidlá, rovnaké ako v ostrej prevádzke

Doručenie

simulované: dokument nikdy neopustí testovací server; ak príjemca (IČ DPH) existuje v testovacom prostredí, faktúra sa mu doručí ako prijatá (vrátane e-mailu, PDF a webhooku)

Doručenka

simulovaná, výslovne označená ako SANDBOX

E-maily

reálne odchádzajú (na adresy, ktoré zadáte), s prefixom [TEST]

Cena

zadarmo, bez limitov na skúšanie

Funguje tam všetko čo tu: portál, REST API, SAPI-SK 1.0, e-shop pluginy aj webhooky. Stačí v integrácii vymeniť doménu za test.peppol.verteco.digital a použiť tokeny vytvorené v testovacom prostredí. Ideálne na vývoj integrácie, CI testy a zaškolenie účtovníkov pred ostrým nasadením.

Pozn.: edge ochrana testovacej domény blokuje generickú hlavičku User-Agent: Python-urllib (HTTP 403 ešte pred naším API). Ak používate python urllib zo štandardnej knižnice, nastavte vlastný User-Agent; bežné klienty (requests, httpx, Java, okhttp, axios, Go, PHP, curl) fungujú bez zmeny.

Prečo sa firmy schvaľujú automaticky

Finančná správa nemá testovacie prostredie portálu VPDS: výber poskytovateľa na vpds.financnasprava.sk beží len v produkcii a overuje sa cez slovensko.sk (eID), takže v ostrej prevádzke si nemôžete „vybrať" ľubovoľnú cudziu firmu. Aby ste napriek tomu vedeli integráciu otestovať, v testovacom prostredí tento krok simulujeme: každá firma, ktorú vytvoríte, sa schváli automaticky (bez výberu na FS), takže si viete založiť odosielateľa aj príjemcu a prejsť celý tok.

Na testovanie FS webhookov (výber poskytovateľa) máme vlastnú obdobu nástroja Finančnej správy: test.peppol.verteco.digital/sandbox-nastroje. Vygenerujete si tam platný verifikačný token (verifikačný údaj) v štýle FS a odošlete kompletný webhook na svoj endpoint, presne ako to robí portál FS pri reálnom výbere. Firmy vytvorené na testovanie viete zase odregistrovať (z portálu aj z testovacieho SMP), práve pre chýbajúci testovací režim na strane Finančnej správy.

Ak prevádzkujete fakturačnú appku, ERP alebo platformu a chcete cez nás napojiť na Peppol viacero svojich zákazníkov (tenantov), integrujete sa raz a obsluhujete N firiem. Model je proxy: váš backend drží jeden API token (vpt_…) len na serveri (nikdy nie v prehliadači) a každý váš tenant = jedna firma u nás (jeden token → N firiem). Rozšírený verejný návod so vzorovými kódmi, webhook podpismi a go-live checklistom: peppol.verteco.digital/saas.

1. 1

   Jeden token, server-side

   Vytvorte si API token a držte ho v zabezpečenom prostredí backendu. Všetky volania robí váš server (Bearer), nie prehliadač zákazníka.
2. 2

   Onboarding tenanta = založenie firmy

   Pre každého zákazníka POST /companies s jeho IČO/IČ DPH; vráti { id, status: "pending_verification" }; id si uložte k tenantovi (detail viď Firmy).

   bashKopírovať

   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":"Firma s.r.o.",
          "street":"Príkladná 12","postalCode":"010 01","city":"Žilina","iban":"SK…"}'

3. 3

   Aktivácia v Peppole (krok zákazníka u štátu)

   pending_verification ≠ živé v Peppole. Aby firma prijímala, musí si zákazník na portáli Finančnej správy (cez eID) zvoliť Verteco ako poskytovateľa; vtedy ju zaregistrujeme do SMP a stav sa zmení na active. Aby firma mohla odosielať, doložte jej Verifikačný údaj cez Overenie odosielania (POST /companies/{id}/verification).
4. 4

   Príjem faktúr: webhook per tenant

   Nastavte webhook (a/alebo e-mail) pre každú firmu a vyzdvihnite podpisový secret:

   bashKopírovať

   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://vasa-saas.sk/peppol/webhook","notificationEmail":"…"}'
   
   curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
   # → { "secret": "…" }   (uložte na overovanie X-Verteco-Signature)

   Pri prijatej faktúre vám príde podpísaný POST (event invoice.received), durable s retry/dead-letter. Overenie podpisu, payload aj tlačidlo „Otestovať webhook" viď Notifikácie & webhooky.
5. 5

   Odoslanie faktúr

   Faktúru (UBL Peppol BIS 3.0) odošlite cez národné rozhranie SAPI-SK 1.0: POST /sapi/document/send (OAuth2 client_credentials, client_secret = váš vpt_ token). SK daňové hlásenie (TDD/C5) doplníme automaticky.
6. 6

   Podklady na prefakturáciu

   GET /companies/usage?month=YYYY-MM vráti počty odoslaných a prijatých dokladov za každú vašu firmu zvlášť aj súhrnne, presne v jednotkách, v ktorých je postavený cenník, takže si viete svojim klientom prefakturovať priamo z toho. Bez parametra vráti aktuálny mesiac; obdobie je polouzavreté a v odpovedi sú explicitne polia from/to, aby ste nemuseli hádať hranicu mesiaca. Firmy bez prevádzky sú v zozname s nulami.
7. 7

   Škálovanie a robustnosť

   Zoznamy stránkujte: GET /companies?page&limit aj GET /companies/{id}/documents?page&limit (s hlavičkami X-Total-Count a i.). Rešpektujte rate-limit na token: pri hromadnom onboardingu dávkujte s backoffom na 429 (Retry-After) a ošetrite 409 ico_taken (idempotentne).

Ak ste zapísaný ako sprostredkovateľ (žiadosť cez /sprostredkovatel), Finančná správa posiela na vašu webhook URL notifikáciu vždy, keď si vás klient vyberie na portáli VPDS. Tento manuál popisuje presný kontrakt tak, ako ho FS reálne volá v produkcii (overené na živých výberoch). FS k webhookom vlastný verejný manuál nevydáva; toto je to, čo na implementáciu potrebujete.

1 · Ako notifikácia vyzerá + 2 · overenie pravosti

3 · Čo s tým: preposlať nám surové telo

Odporúčaná (a najjednoduchšia) implementácia je raw-byte proxy: prijmite POST, odpovedzte rýchlo a surové bajty tela prepošlite na váš registračný endpoint u nás. Ten vzniká automaticky po vyplnení formulára /sprostredkovatel, je aktívny hneď a jeho presnú URL (s vaším kľúčom) vidíte po prihlásení cez GET /api/v1/resellers/me:

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-kluc}
Content-Type: application/json
(telo = nezmenené surové bajty od FS)

My verification_token kryptograficky overíme, firmu automaticky založíme pod vaším partnerským účtom (white-label), zaregistrujeme ju do centrálneho SK SMP a od tej chvíle jej doručujeme e-faktúry. Vy si z payloadu môžete uložiť kontaktné údaje pre vlastný onboarding; nič viac netreba.

4 · Prevádzkové pravidlá (dôležité)

• Idempotencia: ten istý subjekt môže výber zopakovať; spracovanie rovnakého DIČ musí byť bezpečné (u nás je).
• Zdrojová IP: volania chodia z infraštruktúry FS (pozorované z 194.1.2.13); IP allowlist odporúčame len ako doplnok, nie ako jedinú ochranu (rozsah FS negarantuje).
• Odpoveď: vracajte 200 aj pri internej chybe spracovania (chybu si zalogujte); nič iné FS nevyhodnotí.
• Poradie nasadenia: webhook musí byť živý pred podaním žiadosti FS; prvý výber môže prísť krátko po zverejnení.

Referenčná implementácia proxy má ~30 riadkov (prijmi POST → ulož → prepošli surové bajty). Ak si chcete overiť celý reťazec ešte pred zverejnením u FS, pošlite testovací POST na váš registračný endpoint; na neznámy/nepodpísaný obsah odpovie bezpečne a nič nezaloží. Otázky: Podpora.

Integrácia sa autentifikuje API tokenom v hlavičke Authorization: Bearer vpt_…. Token vytvoríte v portáli (API tokeny); má formát vpt_ + 40 hex znakov, ukladáme len jeho SHA-256 hash a má rovnaký prístup ako váš účet. Otestujte ho cez /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)

Pri chýbajúcom alebo neplatnom tokene API vráti:

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

Stránkovanie & idempotencia

Chyby majú jednotný tvar s machine-readable error kódom. Validačné chyby pridávajú mapu fields (prvá 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

úspech (OK / vytvorené / bez obsahu)

400

neplatný vstup (pozri error / fields)

401

chýbajúca alebo neplatná autentifikácia

403

nedostatočné oprávnenie (rola)

404

zdroj neexistuje alebo naň nemáte prístup

409

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

429

prekročený rate limit

Kompletný katalóg chýb

API je chránené rate limitingom v 60-sekundovom okne (per inštancia). Limit a zostatok vraciame v každej odpovedi cez hlavičky; pri prekročení vráti 429 Too Many Requests s Retry-After.

Bežné volania

dynamický limit s veľkou rezervou, na API token (alebo session, inak IP); aktuálnu hodnotu vracia hlavička RateLimit-Limit

Auth (/auth/*)

prísnejší limit na IP (anti brute-force; mimo /auth/me a /auth/logout)

RateLimit-Limit

limit v okne

RateLimit-Remaining

koľko ešte ostáva

RateLimit-Reset

sekúnd do resetu okna

Retry-After

sekúnd do ďalšieho pokusu (pri 429)

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

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

Opaque tokeny vpt_… pre server-to-server prístup. Plaintext sa zobrazí iba raz pri vytvorení. Uložte si ho. Ukladáme len SHA-256 hash a 12-znakový prefix na zobrazenie.

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

Firmy (IČO / IČ DPH), ktoré spravujete. Prístup je viazaný na členstvo: vidíte len firmy, ktorých ste členom. Tvorca firmy sa stáva jej 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 vytvorení; odosielanie ešte nie je odomknuté

active

overená, odosielanie odomknuté

Rola člena

owner

tvorca firmy (plný prístup)

admin

správca (úpravy, webhooky, overenie)

member

člen (čítanie)

viewer

iba čítanie

Pred odosielaním treba firmu overiť cez Verifikačný údaj (VÚ), podpísaný token od Finančnej správy. Po úspešnom overení sa status firmy zmení na active a odomkne sa odosielanie.

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 dokladov (prijatých a odoslaných) za firmu. Napĺňa sa, ako cez Access Point tečú faktúry. Viazané na členstvo vo firme, zoradené createdAt zostupne.

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 štandardizované národné REST rozhranie medzi klientskym/ERP systémom a Access Pointom (sapi-sk.sk). Implementujeme ho v plnom rozsahu. Vďaka tomu nie ste viazaní na náš proprietárny tvar API a integráciu napíšete raz pre ktorýkoľvek SAPI-SK Access Point.

Base URL

https://peppol.verteco.digital/sapi

Autentifikácia

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

client_id

UUID vášho API tokenu (zoznam v sekcii API tokeny / dashboard)

client_secret

samotný vpt_… token z portálu

Verzia

1.3 (10 operácií: 4× auth, 6× dokumenty)

Sandbox (skúšobné prostredie)

Chcete si SAPI-SK vyskúšať bez registrácie a bez rizika? Použite verejné sandbox prihlasovacie údaje. Sandbox validuje požiadavky presne ako ostrá prevádzka, ale nikdy nič neodošle na Peppol sieť a nepracuje s reálnymi dátami; vráti realistické mock odpovede. Ideálne na vývoj, CI a onboarding integrácie.

client_id

sandbox

client_secret

sandbox

send

plná validácia kontraktu + mock 202 (nič sa nedoručí)

receive

1 vzorový doklad sandbox-doc-0001 na test parsovania a acknowledge

# 1) sandbox token (bez registrácie)
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 odoslanie: zvaliduje sa, ale NIČ sa reálne 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>'

Autentifikácia

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…" }

Odoslanie 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": "…" }
# pri status "REJECTED" nesie odpoveď aj pole "detail"
# s dôvodom odmietnutia (validačné pravidlá, napr. BR-CO-15)

Príjem dokumentov

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

Stav odoslaných dokumentov

// 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 }

Hromadné odoslanie

// 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 chýb

Všetky SAPI chyby majú jednotnú obálku s kategóriou, stabilným kódom, príznakom retryable a correlation_id na podporu.

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

Pri prijatej faktúre vieme firmu upozorniť e-mailom alebo webhookom (POST na vašu URL). Doručenie je durable: ukladá sa do výstupnej fronty a doručuje asynchrónne (15 s timeout); pri zlyhaní opakujeme až 8× s exponenciálnym backoffom (30 s → max 1 h), potom dead-letter. Výpadok vášho servera teda notifikáciu nestratí, doručíme ju pri ďalšom pokuse. SSRF ochrana blokuje loopback/lokálne adresy; webhook URL musí byť verejná.

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, ak nie je uložená webhook URL

Payload webhooku

Pri prijatej (invoice.received) aj odoslanej (invoice.sent) faktúre pošleme POST s týmto telom; pole event rozlišuje typ.

Ďalšie dve udalosti oznamujú verdikt siete o faktúre, ktorú ste odoslali: invoice.delivered (príjemcov Access Point potvrdil doručenie doručenkou MLS) a invoice.rejected (odmietnutá, či už sieťou, alebo pri validácii ešte pred odoslaním). Nesú identifikáciu dokladu a firmy (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId) plus status, statusDetail s dôvodom odmietnutia a statusDateTime. Vďaka nim nemusíte stav odoslaných faktúr zisťovať polovaním.

Udalosť company.activated príde, keď zákazník dokončí výber poskytovateľa na portáli Finančnej správy (telo: event, companyId, companyDic, peppolParticipantId, status, verifiedAt); company.deactivated zase pri odregistrovaní firmy zo siete (rovnaké telo bez verifiedAt); detaily v návode /saas:

{
  "event": "invoice.received",
  "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"
}

Polia companyDic a peppolParticipantId identifikujú firmu, ktorej sa udalosť týka (dôležité pre partnerov, ktorí majú jednu webhook URL pre všetkých svojich klientov).

Verdikt siete o odoslanej faktúre:

{
  "event": "invoice.delivered",          // alebo "invoice.rejected"
  "companyId": "08dd…",
  "companyDic": "SK2121358349",
  "peppolParticipantId": "0245:2121358349",
  "documentId": "…",
  "invoiceNumber": "2026001",
  "receiverId": "0245:2120049096",
  "peppolMessageId": "…",
  "status": "delivered",                 // alebo "rejected"
  "statusDetail": null,                  // pri rejected: dôvod odmietnutia
  "statusDateTime": "2026-06-03T10:15:42Z"
}

Aktivácia firmy po výbere na portáli Finančnej správy:

{
  "event": "company.activated",          // company.deactivated má rovnaké telo bez verifiedAt
  "companyId": "08dd…",
  "companyDic": "SK2121358349",
  "peppolParticipantId": "0245:2121358349",
  "status": "active",
  "verifiedAt": "2026-06-03T10:02:11Z"
}

Názov udalosti nesie aj hlavička X-Verteco-Event. Úplný zoznam udalostí: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, company.activated, company.deactivated a testovací webhook.test. Neznámy typ udalosti odporúčame odložiť bokom a zalogovať; nový typ vždy vopred ohlásime.

Partnerský notifikačný webhook (sprostredkovatelia)

Ak ste zapísaný sprostredkovateľ, nemusíte nastavovať webhook pri každej firme zvlášť: jeden partnerský notifikačný webhook dostáva všetky udalosti firiem pod vaším partnerským účtom a má prednosť pred webhookmi jednotlivých firiem. Vaši klienti teda nič nenastavujú; firmu rozlíšite podľa companyDic / peppolParticipantId.

// 200 OK (prvé nastavenie)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
  "events": ["company.activated","company.deactivated","invoice.received","invoice.sent","invoice.delivered","invoice.rejected"] }

Podpis X-Verteco-Signature sa počíta rovnako ako pri firemnom webhooku (nižšie), len s partnerským secretom.

Správa klientov cez API (jednostranné odpojenie a brzda odosielania)

Klient, ktorý od partnera odíde, spravidla neurobí nič – preto sú tieto operácie jednostranné a nevyžadujú žiadnu súčinnosť klienta. Príjem faktúr nimi nie je dotknutý: je viazaný na registráciu firmy v centrálnom SMP, nie na spravujúci účet.

Fakturačný model partnera

V partner konzole (a cez GET/PUT /api/v1/resellers/me/billing) si volíte fakturačný model (voľba je dostupná len zapísaným sprostredkovateľom): per_company = 2 € mesačne za aktívne odosielajúce IČO, alebo per_document = 0,01 € za každú odoslanú faktúru vašich firiem (prijaté doklady zadarmo) s minimálnou mesačnou fakturáciou 300 € + DPH. Zmena modelu platí vždy od 1. dňa nasledujúceho mesiaca (v odpovedi pendingModel a pendingFrom); odpoveď oboch volaní vracia aj prepočet aktuálneho mesiaca pod modelmi, takže prepínate informovane.

Odporúčaný postup pri ukončenom klientovi (strop nákladov na vašej strane): priebežný stav čerpania vidíte v GET /api/v1/companies/usage?month=YYYY-MM (rozpis sent/received po firmách presne na preúčtovanie) a v GET /api/v1/resellers/me/clients (počty za aktuálny mesiac); o každom odoslanom aj prijatom doklade vašich firiem navyše chodí udalosť na partnerský webhook, takže „ukončenú" firmu zachytíte hneď pri prvom doklade. Potom stačí zavolať pause-sending alebo release.

Overenie podpisu

Ak má firma secret, posielame hlavičku X-Verteco-Signature v tvare sha256=HMAC-SHA256(secret, raw telo) (lowercase hex). Vždy počítajte HMAC nad presnými bajtmi tela:

import crypto from 'node:crypto';

// rawBody = presné bajty tela requestu (nie znova 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));
}

Hromadné nastavenie: jeden token, viac firiem

Jeden API token (viazaný na váš účet/e-mail) spravuje všetky firmy, ktoré vlastní: kto firmu založí cez POST /companies, stáva sa jej ownerom a vie jej nastaviť webhook. Webhook je per firma (vlastná URL aj secret), takže rovnakým tokenom napojíte ľubovoľný počet firiem:

# 1) zoznam vašich firiem (stránkovane, viď Firmy)
curl 'https://peppol.verteco.digital/api/v1/companies?page=0&limit=100' -H 'Authorization: Bearer vpt_8f2a…'

# 2) pre KAŽDÚ firmu {id}: nastavte webhook (a/alebo 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) vyzdvihnite podpisový secret (vráti sa LEN RAZ) a uložte si ho pre overovanie podpisu
curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → { "secret": "…" }

• Token musí byť owner/admin danej firmy; pri firme, kde je len member/viewer, vráti 403 forbidden (žiadny cross-tenant zásah).
• Každej firme môžete dať inú URL alebo všetkým rovnakú; v payloade ich rozlíšite podľa companyId (a receiverId).
• Pri stovkách firiem rešpektujte rate-limit na token (aktuálnu hodnotu vracia hlavička RateLimit-Limit); dávkujte s backoffom na 429 (hlavička Retry-After).
• Webhook reálne chodí, až keď je firma aktívna v Peppole (po výbere Verteco ako poskytovateľa u Finančnej správy) a teda skutočne prijíma doklady.

Polia objektov vracaných API.

Company

Document

User · Token · Webhook

Nad rámec Peppol BIS Billing 3.0 sa slovenskí výrobcovia ERP a fakturačných systémov priebežne zhodujú na spoločnej interpretácii voliteľných polí (diskusia prebieha v Slack kanáli Finančnej správy). Nižšie sú konvencie, ktoré náš portál už dnes rešpektuje – všetko sú platné BIS konštrukcie, cez naše API prechádzajú bez zmeny a prijaté doklady ich zobrazujú aj v ľudsky čitateľnom náhľade a PDF.

• Odpočet zdanenej zálohy na riadku: záporný riadok s cac:DocumentReference, kde cbc:ID nesie číslo daňového dokladu k prijatej platbe a cbc:DocumentTypeCode je 130 (BIS: invoice line object identifier, max. 1 na riadok). Prijatá faktúra s takýmto riadkom sa v našom náhľade zobrazí s poznámkou „odpočet zálohy – daňový doklad č. …".
• Daňový doklad k prijatej platbe: podľa FAQ Finančnej správy sa používa InvoiceTypeCode 388 (Tax invoice). Naším API aj validáciou prechádza; odpočet neuhradenej (nezdanenej) zálohy sa vyjadruje cez cbc:PrepaidAmount.
• Storno faktúry: dobropis 381 (CreditNote) s cac:BillingReference na pôvodnú faktúru – nie záporná faktúra 380. Pozor: kód 384 sieť pre slovenské strany odmieta (pravidlo PEPPOL-EN16931-P0112 ho povoľuje len medzi nemeckými subjektmi); na opravu nahor slúži ťarchopis 383.
• BT-83 PaymentID: v SK praxi sa presadzuje tvar referencie platiteľa /VS…/SS…/KS…; samotný variabilný symbol je tiež bežný. Naše spracovanie hodnotu prenáša bez zmeny a zobrazuje ju pri platobných údajoch.
• Doplnkové údaje položiek (šarže, sériové čísla, expirácie) cez cac:AdditionalItemProperty s ustálenými názvami ako BatchNumber, SerialNumber, ExpirationDate.

K e-faktúre je možné pripojiť prílohy (PDF, obrázky) ako base64 v elemente cac:AdditionalDocumentReference (BT-125). Náš limit je 25 MB na prílohu – Peppol jednotný celosieťový limit neurčuje, jednotliví poskytovatelia si ho stanovujú sami (FS FAQ 9/DPH/2025/IM, príklad č. 67), takže pri veľmi veľkých prílohách si overte aj limit poskytovateľa druhej strany.

Dva pomocné endpointy bez autentifikácie – rovnaké validačné jadro a rovnaký SML/SMP lookup, aké používa náš Access Point. Hodia sa do CI aj do predodoslacích kontrol; platí na ne prísnejší verejný 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ázdne telo (empty_document) alebo 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"
}

Verejný health-check endpoint, vhodný na monitoring.

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

Živý prehľad všetkých komponentov nájdete na stránke stavu systémov.

• POST/companies/{id}/peppol/register· Manuálna registrácia do Peppol SMP cez API (dnes prebieha automaticky pri výbere poskytovateľa na portáli FS).

Chcete skorý prístup k integrácii, sandbox alebo máte otázku? Ozvite sa priamo:

Váš Peppol kontakt

Miriama Mrkávková

+421 944 488 269·peppol​@​verteco.digital