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 zákonom určené tuzemské transakcie. Samotné PDF v mailovej prílohe už nebude e-faktúrou. Základnou doručovacou cestou je certifikovaný digitálny poštár v sieti Peppol; prechodný režim pozná aj podmienenú alternatívnu štruktúrovanú výmenu.

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) po overení firmy a dokončení výberu poskytovateľa koordinujeme aktiváciu identifikátora 0245:DIČ — kde DIČ je daňové identifikačné číslo firmy. Po úspešnom publikovaní podporovaných profilov možno identifikátor overiť v sieti Peppol a používať pre podporované dokumenty.
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.

Produkčné prepojenie má povinný súhlasový krok a voliteľné vydanie samostatného firemného kľúča:

• (a) Žiadosť o integrátorský súhlas — povinná cesta. V partnerskom konte alebo cez Enterprise Core endpointPOST /api/v1/consent-offers vytvoríte časovo obmedzenú pozvánku pre konkrétne IČO alebo DIČ. Prihlásený vlastník alebo admin firmy v nej potvrdí konkrétne oprávnenia; systém uloží nemenný KYC dôkaz a až potom firmu pripojí k vášmu integrátorskému účtu. Bez prijatej žiadosti nemožno firmu aktivovať ani obnoviť po odvolaní súhlasu.
• (b) Sledujte prijatie pozvánky. Uložte id a jednorazový consentUrl z odpovede POST. Odkaz otvorte oprávnenej osobe firmy; stav overujte cez GET /api/v1/consent-offers/{offerId}. Pozvánka nie je OAuth URL a prijatie nemá callback do ERP. Partner naďalej používa vlastný centrálny sk_int_*; klient mu nedáva firemný sk_live_*. Stav accepted znamená prijatý súhlas, nie dokončenú aktiváciu zmluvy a účtovania. Celý postup nájdete v návode automatizácie.
• (c) Assign API — len obnova bezpečne doloženého stavu. Volanie POST /api/v1/firms/assign s telom { "dic": "..." } (IČO funguje ďalej ako fallback) (alebo hromadná verzia POST /api/v1/firms/assign/batch) funguje iba pre firmu s aktívnym, neodvolaným integrátorským súhlasom. Nová firma alebo firma, ktorá súhlas odvolala, musí najprv prijať čerstvú žiadosť o súhlas zabezpečenú operátorom ePošťáka po kontakte na info@epostak.sk. Plán integrator-managed sám osebe súhlas nepreukazuje. Bez prijatého súhlasu endpoint vráti 403 CONSENT_REQUIRED . OAuth authorization_code flow môže až následne vydať samostatný firemný kľúč; nevytvára ani neobnovuje súhlas.

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; jeho aktuálnu platnosť čítajte z odpovede a živej dokumentácie, nie z pevnej hodnoty v tomto článku. 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 rieši výmenu a obnovu tokenu podľa aktuálnej konfigurácie. 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. Pri mapovaní elementov vám pomôže vizualizácia UBL XML pole po poli, ktorá prepája technické BT/BG polia s ich miestom na čitateľnej faktúre.
• 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 podporované pravidlá a pokúsi sa o prenos cez príslušný Peppol profil. Výsledný stav treba sledovať; prijatie požiadavky ani technické odoslanie nie sú automaticky dôkazom doručenia, zaúčtovania alebo úhrady príjemcom.

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. Pri aktívnom a podporovanom toku môže ePošťák dokument prijať a sprístupniť podľa programu, oprávnení a aktuálneho API kontraktu. Váš ERP systém ich môže čítať 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ť vo webovom rozhraní 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.

API cena sa riadi aktuálnym cenníkom podľa smeru, objemu a použitia. Pred integráciou overte, ktorý stav dokumentu vytvára účtovaný záznam a ako sa riešia neúspešné prenosy. Konkrétne 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, podporovaný doručovací tok a reporting na Finančnú správu. Vy pošlete požiadavku a následne overíte spracovanie aj výsledný stav dokumentu.

Ak máte otázky alebo chcete začať s integráciou, ozvite sa nám na info@epostak.sk. Aktuálny režim podpory a čas odpovede overte v zvolenom programe. Alebo si 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.