Ako integrovať digitálneho poštára do vášho softvéru

Stále sa nás pýtate: ako vlastne začať? V tomto článku vám krok po kroku vysvetlíme, čo musí váš ERP systém urobiť, aby sa napojil na ePoštáka. Prejdeme od úplne prvého kroku (keď si váš zákazník zvolí ePoštáka u Finančnej správy) až po odoslanie prvej faktúry cez Peppol sieť. Žiadna mágia, žiadny nedokumentovaný postup. Len jasné kroky, ktoré viete implementovať za jedno poobede.

Od 1. januára 2027 bude elektronická fakturácia povinná pre všetkých platiteľov DPH na Slovensku. Papierové faktúry ani PDF v mailovej prílohe už nebudú stačiť. Každá firma bude musieť posielať a prijímať faktúry cez Peppol — európsku sieť, ktorá spája firmy naprieč krajinami od Nórska po Maltu.

Na to, aby sa vaša firma do tejto siete pripojila, potrebuje digitálneho poštára. Digitálny poštár je certifikovaný poskytovateľ doručovacích služieb — v technickom jazyku sa tomu hovorí Peppol Access Point. Je to firma, ktorá má povolenie od Finančnej správy a od OpenPeppol (organizácia, ktorá Peppol sieť riadi) prijímať a odosielať elektronické dokumenty v mene vašej firmy.

ePošťák (prevádzkovateľ: Kaja Solutions s.r.o.) je certifikovaný digitálny poštár pod číslom EFSK000012. Viac o tom, čo digitálny poštár robí a prečo ho potrebujete, nájdete v našom sprievodcovi o digitálnom poštárovi.

Skôr než budete môcť posielať faktúry v mene vášho zákazníka (firmy), ten zákazník musí najprv vykonať jeden krok: zvolí si ePoštáka ako svojho digitálneho poštára u Finančnej správy. Ako to vyzerá v praxi:

1. Prihlásenie na portáli Finančnej správy. Zákazník (firma alebo jej zástupca) sa prihlási na e-Faktúra portáli PFS. Prihlásenie prebieha cez slovensko.sk login alebo cez eID — rovnako ako pri daňových priznaniach.
2. Výber digitálneho poštára. Na portáli si z ponuky certifikovaných poštárov vyberie Kaja Solutions s.r.o. (obchodný názov: ePošťák).Portál Finančnej správy — výber certifikovaného poskytovateľa doručovacej služby
3. Registrácia do Peppol siete. My (ePošťák) zákazníka automaticky zaregistrujeme v Peppol sieti s jeho unikátnym identifikátorom 0245:DIČ — kde DIČ je daňové identifikačné číslo firmy. Od tohto momentu je firma viditeľná v celej európskej sieti Peppol a môže prijímať faktúry.
4. Webhook s údajmi. Portál Finančnej správy nám pošle webhook (automatickú správu) s tokenom a údajmi zákazníka. Zákazník sa objaví v našom systéme a je pripravený na ďalšie kroky.

Z vášho pohľadu ako integrátora (ERP výrobcu) je toto jediný krok, ktorý musí urobiť zákazník sám. Všetko ostatné už riadi váš kód.

Keď je zákazník zaregistrovaný u nás, potrebujete ho prepojiť s vaším ERP systémom. To znamená: povedzte ePoštákovi, že táto firma patrí pod vašu integrátorskú správu. Najprv nás kontaktujte na info@epostak.sk a dostanete testovací integrátorský API kľúč — začínajúci na sk_int_*. S ním si overíte celú integráciu v sandbox prostredí. Pre produkčný kľúč je nutné podpísať s nami zmluvu o poskytovaní služieb — podmienky vám radi vysvetlíme na rovnakom e-maile.

Prepojenie zákazníka s vaším systémom môžete urobiť dvomi spôsobmi:

• (a) OAuth flow — odporúčaná cesta. Toto je hlavný spôsob, ako prvý raz prepojiť firmu zákazníka s vaším integrátorským účtom. Pošlete majiteľa alebo administrátora firmy na ePoštákov autorizačný link /oauth/authorize?client_id=…&redirect_uri=…&response_type=code&code_challenge=…&code_challenge_method=S256&state=…. Tam sa prihlási do svojho ePoštákovho účtu, uvidí jasnú obrazovku „Súhlasím s prepojením" a klikne potvrdiť. ePostak ho vzápätí presmeruje späť na vašu redirect_uri a pripojí jednorazový code a váš state parameter. Tento kód si potom na serveri vymeníte cez POST /api/oauth/token so grant_type=authorization_code, vaším client_secret a code_verifier (PKCE) za prístupový JWT token a integrátorský API kľúč pre danú firmu. V tej istej operácii sa firma prepne na spravovaný plán integrator-managed a priradí sa pod váš účet — všetko v jednej transakcii a s preukázateľným súhlasom majiteľa. Pred prvým použitím nám pošlite zoznam povolených redirect_uris na info@epostak.sk — kontrolujeme ich na presnú zhodu, žiadne hviezdičky ani vzory.
• (b) Priradenie cez API — len obmedzené prípady. Volanie POST /api/v1/firms/assign s telom { "ico": "..." } (alebo hromadná verzia POST /api/v1/firms/assign/batch) funguje iba v dvoch situáciách: (1) keď obnovujete prepojenie, ktoré už v minulosti existovalo a majiteľ s ním kedysi súhlasil, alebo (2) keď je firma už na pláne integrator-managed (t. j. súhlas bol udelený skôr). Prvotné priradenie bezplatnej firmy cez tento endpoint API odmietne s chybou 403 CONSENT_REQUIRED a správou „First-time firm claim requires explicit owner consent. Use OAuth authorization_code flow." V praxi je tento endpoint užitočný hlavne na hromadné obnovenie prepojení s vaším existujúcim portfóliom firiem — napríklad po výmene API kľúča — nie však na získavanie nových zákazníkov.

Po prepojení môžete v každej API požiadavke zadať hlavičku X-Firm-Id s identifikátorom zákazníkovej firmy a konať tak v jej mene — posielať faktúry, čítať došlé dokumenty, potvrdzovať prijatie a podobne.

Ak používate TypeScript alebo JavaScript, najjednoduchšie je nainštalovať si náš oficiálny SDK:

npm install @epostak/sdk

Pre ďalšie jazyky (Python, PHP, Java, C#, Ruby) je zdrojový kód dostupný na GitHube — každý SDK je len tenký obal nad naším REST API, takže ak máte radšej priame HTTP volania, môžete použiť aj tie.

Autentifikácia funguje cez štandardný client_credentials flow (to znamená: pošlete nám svoje prístupové údaje a my vám vrátime dočasný token). Konkrétne: pošlete POST požiadavku na /api/v1/auth/token s vaším client_id a client_secret. Dostanete JWT token (textový reťazec) s platnosťou 15 minút. Tento token potom pridávate do každého ďalšieho volania v hlavičke Authorization: Bearer ....

V praxi to s naším SDK vyzerá takto:

import { EPostak } from "@epostak/sdk";

const client = new EPostak({
  clientId: "váš-client-id",
  clientSecret: "sk_int_...",
});

// Odoslanie faktúry za konkrétnu firmu
const invoice = await client.documents.send({
  firmId: "uuid-firmy-zákazníka",
  // ... dáta faktúry (viď ďalšiu sekciu)
});

SDK sa o výmenu tokenu postará automaticky — nemusíte riešiť obnovu tokenu po 15 minútach. Kompletnú dokumentáciu autentifikácie nájdete v Enterprise API dokumentácii — sekcia Autentifikácia.

Teraz prichádza to najdôležitejšie: odoslanie faktúry cez Peppol sieť. ePošťák podporuje tri vstupné formáty:

• JSON — pošlete nám štruktúrované dáta (číslo faktúry, dátum, položky, sumy) a my z nich automaticky vygenerujeme platný UBL XML dokument podľa štandardu Peppol BIS 3.0. Toto je najjednoduchšia cesta a odporúčame ju pre väčšinu integrácií.
• UBL XML — ak si UBL dokument zostavujete sami (napríklad ak už máte vlastný generátor), môžete nám poslať hotový XML súbor. My ho zvalidujeme a doručíme.
• PDF alebo sken — ak máte len PDF faktúru alebo naskenovaný papier, naša OCR (optický systém na čítanie textu) z neho vytiahne údaje a vyrobí elektronickú faktúru. Toto je vhodné pre firmy, ktoré ešte nemajú štruktúrované dáta.

Pre väčšinu ERP integrátorov bude najvhodnejší JSON formát. Nemusíte sa učiť XML ani Peppol UBL špecifikáciu — jednoducho pošlete nám dáta, ktoré už aj tak máte vo vašom systéme (číslo faktúry, dátum vystavenia, dátum splatnosti, mena, položky s cenou a sadzbou DPH) a my sa postaráme o zvyšok.

Tu je príklad volania v podobe curl (príkazový riadok) — rovnaký princíp samozrejme funguje z ľubovoľného programovacieho jazyka:

curl -X POST https://epostak.sk/api/v1/documents/send \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Firm-Id: uuid-firmy" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverPeppolId": "0245:2020202020",
    "invoiceNumber": "FV-2026-0001",
    "issueDate": "2026-05-05",
    "dueDate": "2026-05-19",
    "currency": "EUR",
    "items": [
      {
        "description": "Služba",
        "quantity": 1,
        "unitPrice": 100,
        "vatRate": 23
      }
    ]
  }'

Čo sa deje v pozadí: ePošťák z vášho JSON vytvorí platný UBL XML dokument, zvaliduje ho podľa slovenských pravidiel aj podľa európskej normy EN 16931, digitálne ho podpíše a doručí ho cez Peppol AS4 protokol priamo do schránky príjemcu. Vy sa nemusíte starať o XML, o podpisy, ani o to, ktorý Access Point používa firma na druhej strane — to všetko rieši ePošťák.

Detailný popis všetkých parametrov a možností nájdete v Enterprise API dokumentácii — sekcia Odoslanie dokumentu.

Odosielanie faktúr je jedna strana mince. Tá druhá je prijímanie — keď vaši zákazníci dostávajú faktúry od svojich dodávateľov. ePošťák faktúry automaticky prijme, zvaliduje a uloží. Váš ERP systém si ich potom môže vyzdvihnúť dvomi spôsobmi:

• Webhooky (odporúčame). Nastavíte si URL adresu, na ktorú vám ePošťák pošle správu vždy, keď príde nová faktúra. Váš systém okamžite reaguje — bez nutnosti sa pravidelne pýtať.
• Pravidelné dotazovanie (pull). Váš systém sa v pravidelných intervaloch (napríklad každých 5 minút) spýta ePoštáka, či prišli nové dokumenty. Jednoduchšie na implementáciu, ale s miernym oneskorením.

V oboch prípadoch používate tieto tri koncové body:

• GET /api/v1/documents/inbox — zoznam prijatých dokumentov s filtrovaním podľa dátumu, stavu a podobne.
• GET /api/v1/documents/{id} — kompletný detail konkrétneho dokumentu vrátane všetkých položiek, súm a metadát.
• POST /api/v1/documents/inbox/{id}/acknowledge — potvrdenie prijatia. Tým ePoštákovi poviete: „Túto faktúru sme spracovali, môže sa označiť ako vybavená." Toto je dôležité pre auditnú stopu aj pre vášho zákazníka.

Kompletnú dokumentáciu prijímacích koncových bodov nájdete v Enterprise API dokumentácii — sekcia Prijímanie dokumentov.

Nechcete testovať na živých firmách? Nemusíte. ePošťák poskytuje zdieľané demo účty, ktoré sú zaregistrované v testovacom prostredí Peppol siete (SMK). Môžete odoslať faktúru, prijať ju na druhej strane, otestovať webhooky a celý flow — všetko beží cez reálnu Peppol infraštruktúru, ale v testovacou režime bez dopadu na produkčné dáta ani na Finančnú správu.

Demo účty dostanete spolu s vaším integrátorským API kľúčom. Môžete začať testovať okamžite — bez toho, aby ste museli mať reálnu firmu zaregistrovanú na portáli Finančnej správy.

Detaily o sandbox účtoch a testovacom prostredí nájdete v Enterprise API dokumentácii — sekcia Demo účty.

Možno sa pýtate: prečo by som mal použiť ePoštáka a nerobiť to sám? Tu je zhrnutie toho, čo za vás rieši ePošťák, aby ste sa mohli sústrediť na to, v čom ste dobrí — na váš produkt:

• Generovanie UBL XML. Nemusíte sa učiť 500-stránkovú špecifikáciu. Pošlete JSON, my vyrobíme platný Peppol BIS 3.0 dokument.
• Validácia. Každá faktúra prejde validáciou podľa slovenských pravidiel (§74 zákona o DPH) aj podľa európskej normy EN 16931. Ak je niečo zle, dostanete zrozumiteľnú chybovú hlášku — nie 200-riadkový XML log.
• Digitálny podpis a doručenie. Faktúru podpíšeme a doručíme cez Peppol AS4 protokol. Nemusíte riešiť certifikáty, SMP registráciu, ani opakovanie pri dočasných výpadkoch.
• Reporting na Finančnú správu. Podľa zákona musí každý digitálny poštár oznamovať fakturačné dáta na Finančnú správu. Toto robíme automaticky za každú firmu, ktorú spravujeme.
• Archivácia. Faktúry uchovávame v súlade s legislatívou. Váš zákazník sa k nim vie kedykoľvek dostať cez dashboard aj cez API.
• Nepretržité sledovanie prevádzky. Ak sa niečo pokazí — či už na našej strane, alebo na strane príjemcu — vieme o tom skôr než váš zákazník.

Počas roka 2026 platia vaši zákazníci len za skutočne doručené faktúry. Ak firma pošle faktúru a príjemca nie je v sieti Peppol, nič sa neúčtuje. Konkrétne cenové plány nájdete na našej cenníkovej stránke. Pre integrátorov s vyšším objemom pripravujeme individuálne podmienky — napíšte nám na info@epostak.sk.

Celá integrácia je navrhnutá tak, aby ste sa mohli sústrediť na váš produkt — nie na Peppol. My riešime XML, validáciu, doručovanie a reporting na Finančnú správu. Vy pošlete JSON a dostanete faktúru na druhom konci.

Ak máte otázky alebo chcete začať s integráciou, ozvite sa nám na info@epostak.sk. Odpovieme do 24 hodín. Alebo si rovno pozrite kompletnú Enterprise API dokumentáciu a začnite s demo účtami už dnes.

Túto integráciu už zvládli desiatky ERP systémov. Vášmu môže trvať jedno poobede.