Integrácia · Aktualizované 6. októbra 2026 · 10 min čítania
Ako integrovať digitálneho poštára do vášho softvéru
Tento návod je pre výrobcov softvéru a ERP systémov a pre firmy s vlastným softvérom, ktoré chcú od 1. januára 2027 posielať a prijímať e-faktúry cez sieť Peppol. Prejdeme celú cestu: registráciu zákazníka cez Finančnú správu SR, API kľúč a SDK a odoslanie prvej faktúry.
Čo robí digitálny poštár a čo váš softvér
Od 1. januára 2027 musia slovenskí platitelia DPH pri tuzemských B2B a B2G plneniach vyhotovovať a prijímať elektronické faktúry. Faktúra sa doručuje v sieti Peppol cez certifikovaného poskytovateľa doručovacej služby, teda digitálneho poštára. PDF poslané e-mailom už nestačí.
ePošťák je certifikovaný digitálny poštár s označením EFSK000012, ktorý prevádzkuje Kaja Solutions s.r.o. Váš softvér vystaví faktúru a odovzdá ju ePošťákovi cez API. ePošťák ju overí, doručí poštárovi odberateľa a údaje z nej oznámi Finančnej správe SR. Faktúry pre vašich zákazníkov prichádzajú opačnou cestou.
1. Vyberte rozhranie: SAPI, Enterprise API alebo Connector
Všetky tri rozhrania doručujú rovnaké e-faktúry v sieti Peppol. Líšia sa tým, čo posiela váš softvér a koľko práce s formátom a stavmi zostane na vás.
| Rozhranie | Čo posielate | Pre koho | Viac firiem | Príklad |
|---|---|---|---|---|
| SAPI | Hotový UBL dokument (Peppol BIS 3.0) podľa štandardu SAPI-SK 1.0, presne 8 endpointov | Softvér, ktorý už rozhranie SAPI-SK podporuje alebo ho chce použiť u viacerých poštárov | Firmu vyberá hlavička X-Peppol-Participant-Id s hodnotou 0245:DIČ | Microsoft Dynamics 365 Business Central s rozšírením E-faktúra SK Connector od Navitec systems (návod) |
| Enterprise API | JSON (ePošťák z neho vytvorí UBL) alebo hotový UBL v poli xml | Vlastný softvér, ktorý nechce skladať UBL, potrebuje webhooky, stav doručenia a dôkazy | Jeden integrátorský kľúč pre viac firiem, firmu vyberá hlavička X-Firm-Id | Fakturačný alebo skladový systém s vlastnou databázou faktúr |
| Connector | Vlastné JSON doklady ERP s jeho číslami dokladov a zákazníkov (customerRef), mapper pre vlastný formát | Výrobca ERP, ktorý chce spravovaný tok: príprava, odoslanie, udalosti a príjem bez Peppol detailov | Firmy schvaľuje ePošťák, ERP ich rozlišuje vlastným customerRef | ERP pre mnoho klientskych firiem (návod na Connector) |
SAPI má adresu https://epostak.sk/sapi/v1 a testovaciu https://dev.epostak.sk/sapi/v1. Obsahuje presne 8 endpointov podľa SAPI-SK 1.0: štyri na token (/auth/token, /auth/renew, /auth/revoke, /auth/token/status) a štyri na doklady (/document/send, /document/receive, /document/receive/{documentId}, /document/receive/{documentId}/acknowledge). Webhooky SAPI nemá.
Enterprise API má adresu https://epostak.sk/api/v1 a testovaciu https://dev.epostak.sk/api/v1. Okrem odoslania a príjmu ponúka overenie príjemcu, stav doručenia, webhooky, dôkazy o doručení a odpovede na faktúru.
Connector (/api/v1/connector) je určený pre výrobcov ERP. ERP posiela doklady so svojimi číslami a s vlastným označením zákazníka a ePošťák sa postará o formát, odoslanie a udalosti.
2. Vyberte model účtu
Jedna firma s vlastným softvérom
Firma, ktorá má ePošťáka, si API objedná v časti Nastavenia → API. Štandardná objednávka podľa cenníka sa aktivuje hneď po potvrdení. Firma si potom vygeneruje vlastný kľúč sk_live_*, ktorý platí iba pre ňu.
Kľúč môže firma zadať do svojho softvéru sama alebo ho odovzdať dodávateľovi softvéru. Súhlas s prístupom partnera v tomto prípade netreba, lebo softvér koná priamo za firmu jej vlastným kľúčom. Hlavičky X-Firm-Id ani X-Peppol-Participant-Id pri Enterprise API nepotrebujete; pri SAPI posielate vlastné Peppol ID firmy.
Dodávateľ softvéru pre viac klientskych firiem
Výrobca softvéru, ktorý obsluhuje viac firiem jedným kľúčom, potrebuje integrátorský účet a kľúč sk_int_*. Každá firma musí prístup výslovne povoliť. Kto platí, závisí od typu spolupráce: ako technický partner podpíšete bezplatnú zmluvu a každá firma platí API sama podľa cenníka (potvrdením vášho odkazu si ho zároveň objedná); ako spravovaný integrátor platíte za všetky firmy vy. Porovnanie nájdete na stránke API integrácia.
Pripojenie firmy prebieha takto:
- Cez
POST /api/v1/consent-offersvytvoríte pozvánku pre konkrétne IČO alebo DIČ s požadovanými rozhraniami a oprávneniami. Z odpovede si uložteida jednorazovýconsentUrl; volanie nie je idempotentné. - Vlastník alebo admin firmy otvorí odkaz a súhlas potvrdí. Stav overíte cez
GET /api/v1/consent-offers/{offerId}. - Až potom firmu obsluhujete svojím kľúčom: v Enterprise API s hlavičkou
X-Firm-Id, v SAPI s hlavičkouX-Peppol-Participant-Id.
Bez prijatého súhlasu firmu k účtu nepripojíte a API vráti 403 CONSENT_REQUIRED. Integrátorský účet a produkčnú zmluvu vám pripravíme po e-maile na info@epostak.sk.
Jedna vlastná firma žiadosť nepodáva: API objedná a kľúč vytvorí v Nastavenia → Prepojenie s účtovným programom. Skupina vlastných firiem s jedným kľúčom a jednou faktúrou sa prihlási ako spravovaný integrátor.
3. Postup od registrácie po prvú faktúru
Krok 1: Zákazník vyberie ePošťáka na portáli Finančnej správy
Zákazník sa prihlási na portál Finančnej správy SR a ako certifikovaného poskytovateľa doručovacej služby vyberie Kaja Solutions s.r.o. (ePošťák). Finančná správa potom ePošťákovi odovzdá údaje firmy a ePošťák firmu zaregistruje v sieti Peppol pod identifikátorom 0245:DIČ. Tento krok za zákazníka nemôže urobiť dodávateľ softvéru ani ePošťák.

Krok 2: Otestujte integráciu v sandboxe
Testovacie prostredie beží na dev.epostak.sk. Je oddelené od produkcie a používa testovaciu sieť Peppol. Odoslanie vyskúšate na testovacích protistranách, ktoré na doklad odpovedia vopred určeným výsledkom: prijaté, odmietnuté, spochybnené alebo nedoručiteľné.
Vlastný sandbox s dvoma testovacími firmami A a B si vyžiadate na dev.epostak.sk/dev. Prístup s testovacími firmami príde e-mailom do pár minút. DIČ klientskych firiem do sandboxu neposielajte. Vlastný API kľúč si potom vytvoríte v portáli.
Krok 3: Získajte token
API používa OAuth 2.0 client_credentials. Kľúč vymeníte za krátkodobý JWT token a ten posielate v hlavičke Authorization: Bearer. Pole client_id je ID kľúča alebo jeho zobrazený prefix, nie samotný tajný kľúč. Pre SAPI použite rovnaké telo na /sapi/v1/auth/token.
# Testovacie prostredie. Na produkcii použite https://epostak.sk
curl -X POST https://dev.epostak.sk/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "<ID kľúča alebo jeho zobrazený prefix>",
"client_secret": "<celý kľúč sk_live_... alebo sk_int_...>"
}'
# Odpoveď: access_token (platí 15 minút) a refresh_token.
# Token si uložte v pamäti a obnovte cez POST /api/v1/auth/renew.Krok 4: Odošlite prvú faktúru
V Enterprise API stačí poslať údaje faktúry v JSON. ePošťák z nich vytvorí UBL dokument Peppol BIS 3.0. Odosielateľa berie z overenej firmy, nie z tela požiadavky. Ak už UBL skladáte sami, pošlite ho v poli xml. Pred odoslaním ePošťák overí, či je odberateľ v sieti Peppol. Ak nie je, vráti chybu 422 a faktúru neodošle.
curl -X POST https://dev.epostak.sk/api/v1/documents/send \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: FV-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"receiverPeppolId": "0245:0000000001",
"receiverName": "Odberateľ s.r.o.",
"invoiceNumber": "FV-2026-0001",
"issueDate": "2026-10-06",
"dueDate": "2026-10-20",
"currency": "EUR",
"items": [
{ "description": "Služba", "quantity": 1, "unitPrice": 100, "vatRate": 23 }
]
}'
# Pri integrátorskom kľúči sk_int_* pridajte hlavičku X-Firm-Id: <UUID firmy>.Rovnaké volanie cez oficiálne TypeScript SDK @epostak/sdk (inštalácia npm install @epostak/sdk). SDK si token vyžiada a obnovuje samo. SDK pre Python, PHP, .NET, Java a Ruby sú ako zdrojový kód na GitHube.
import { EPostak } from "@epostak/sdk";
const client = new EPostak({
clientId: process.env.EPOSTAK_CLIENT_ID!,
clientSecret: process.env.EPOSTAK_CLIENT_SECRET!,
baseUrl: "https://dev.epostak.sk/api/v1", // na produkcii vynechajte
// firmId: "<UUID firmy>", // iba pri integrátorskom kľúči sk_int_*
});
const sent = await client.enterprise.documents.send(
{
receiverPeppolId: "0245:0000000001",
receiverName: "Odberateľ s.r.o.",
invoiceNumber: "FV-2026-0001",
issueDate: "2026-10-06",
dueDate: "2026-10-20",
items: [{ description: "Služba", quantity: 1, unitPrice: 100, vatRate: 23 }],
},
{ idempotencyKey: "FV-2026-0001" },
);
const status = await client.enterprise.documents.status(sent.documentId);Cez SAPI posielate hotový UBL dokument s metadátami a povinným Idempotency-Key vo formáte UUID:
curl -X POST https://dev.epostak.sk/sapi/v1/document/send \
-H "Authorization: Bearer <access_token z /sapi/v1/auth/token>" \
-H "Idempotency-Key: $(uuidgen)" \
-H "X-Peppol-Participant-Id: 0245:<DIČ odosielateľa>" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"documentId": "FV-2026-0001",
"documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
"processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
"senderParticipantId": "0245:<DIČ odosielateľa>",
"receiverParticipantId": "0245:<DIČ odberateľa>",
"creationDateTime": "2026-10-06T10:00:00Z"
},
"payload": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>",
"payloadFormat": "XML"
}'
# Odpoveď 202 ACCEPTED znamená prijatie na spracovanie, nie doručenie.Všetky polia faktúry sú v dokumentácii Enterprise API a v dokumentácii SAPI.
Krok 5: Sledujte stav doručenia
Úspešná odpoveď API znamená, že ePošťák faktúru prijal na spracovanie. Nie je to doručenie. Faktúra je doručená až vtedy, keď poštár odberateľa vráti doklad o doručení (MLS).
GET /api/v1/documents/{id}/statusvráti stav faktúry, napríkladsentalebodelivered, a samostatne stav hlásenia Finančnej správe SR v politdd.status.- Webhooky cez
POST /api/v1/webhooksposielajú udalostidocument.sent,document.delivered,document.delivery_failedadocument.mls_received. Bez verejnej adresy ich čítate cezGET /api/v1/events/pull. - Pri SAPI si uložte
providerDocumentIdz odpovede. S prístupom k Enterprise API ho použijete v stavovom endpointe vyššie.
Krok 6: Prijímajte faktúry a potvrďte spracovanie
GET /api/v1/documents/inboxvráti zoznam prijatých faktúr,GET /api/v1/documents/inbox/{id}detail s UBL dokumentom. Novú faktúru vám oznámi aj webhookdocument.received.- Po uložení vo vašom systéme zavolajte
POST /api/v1/documents/inbox/{id}/acknowledge. V SAPI je toPOST /sapi/v1/document/receive/{documentId}/acknowledge. - Potvrdenie spracovania nie je odpoveď na faktúru (Invoice Response). Odosielateľovi nič neposiela. Akceptáciu alebo zamietnutie faktúry pošlete samostatne cez
POST /api/v1/documents/{id}/respond.
Krok 7: Kontrolný zoznam pred produkciou
- Zákazník vybral ePošťáka (Kaja Solutions s.r.o.) na portáli Finančnej správy SR a jeho Peppol ID 0245:DIČ je aktívne.
- Máte produkčný kľúč a produkčnú adresu https://epostak.sk. Testovacie kľúče, ID firiem a nastavenia sa na produkciu neprenášajú.
- Pri integrátorskom účte má každá firma prijatý súhlas s vaším prístupom.
- Každé odoslanie nesie stabilný Idempotency-Key, takže opakovanie po výpadku siete nevytvorí druhú faktúru.
- Pred odoslaním overujete príjemcu cez POST /api/v1/documents/preflight alebo spracujete chybu, ak odberateľ nie je v sieti Peppol.
- Faktúru za doručenú považujete až po doklade o doručení (MLS), nie po úspešnej odpovedi API.
- Prijaté faktúry sťahujete, ukladáte a až potom potvrdzujete cez acknowledge.
- Webhooky na produkcii máte nastavené zvlášť a overujete ich podpis X-Webhook-Signature.
Čo za vás urobí ePošťák
- Formát a kontrola. Z JSON vytvorí UBL Peppol BIS 3.0 a každú faktúru pred odoslaním overí podľa pravidiel Peppol a EN 16931. Chybu vráti so zrozumiteľným popisom.
- Doručenie. Vyhľadá poštára odberateľa a faktúru mu doručí cez protokol AS4. Certifikáty AS4 a opakované pokusy pri dočasnom výpadku rieši ePošťák.
- Hlásenie Finančnej správe SR. Údaje z odoslaných aj prijatých faktúr oznamuje automaticky a stav hlásenia ukáže v API.
- Dôkazy a archív. Faktúry, doklady o doručení (MLS) a dôkazy o prenose sú dostupné v API aj vo webovom rozhraní.
Koľko to stojí
Ceny API, integrátorských účtov a prijímania sú v cenníku ePošťáka. Pri skupine firiem alebo vyššom objeme nám napíšte na info@epostak.sk.
Časté otázky
Ako napojiť vlastný softvér alebo ERP na digitálneho poštára?
Zákazník si na portáli Finančnej správy SR vyberie ePošťáka (Kaja Solutions s.r.o.) ako svojho digitálneho poštára. Váš softvér potom získa API kľúč, vymení ho za krátkodobý token cez POST /api/v1/auth/token alebo POST /sapi/v1/auth/token a faktúru odošle cez POST /api/v1/documents/send (JSON alebo UBL) alebo POST /sapi/v1/document/send (UBL). ePošťák faktúru overí, doručí v sieti Peppol a údaje z nej oznámi Finančnej správe SR.
Aký je rozdiel medzi SAPI, Enterprise API a Connectorom?
SAPI je štandardné rozhranie SAPI-SK 1.0 s presne 8 endpointmi pre hotové UBL dokumenty, vhodné pre softvér, ktorý už SAPI-SK podporuje. Enterprise API prijíma JSON aj UBL, má webhooky a jedným integrátorským kľúčom obslúži viac firiem. Connector je spravovaný tok pre ERP, v ktorom ERP posiela vlastné čísla dokladov a zákazníkov a ePošťák ich mapuje na Peppol.
Čo musí urobiť zákazník sám?
Zákazník musí na portáli Finančnej správy SR vybrať ePošťáka ako svojho certifikovaného poskytovateľa doručovacej služby. Tento krok za neho nemôže urobiť dodávateľ softvéru ani ePošťák. Ak jeho firmu napája dodávateľ softvéru s integrátorským účtom, zákazník musí navyše potvrdiť súhlas s prístupom tohto dodávateľa.
Potrebuje firma súhlas partnera, ak dá svoj API kľúč dodávateľovi softvéru?
Nie. Firma si API objedná v ePošťákovi v časti Nastavenia → API, objednávka sa aktivuje hneď a firma si vygeneruje vlastný kľúč sk_live_*. Ten môže zadať do svojho softvéru sama alebo ho odovzdať dodávateľovi softvéru. Súhlas s prístupom partnera je potrebný iba vtedy, keď dodávateľ obsluhuje viac firiem jedným integrátorským kľúčom sk_int_*.
Ako získam testovací prístup do sandboxu?
Na testovacom prostredí dev.epostak.sk fungujú verejné demo kľúče z API dokumentácie, s ktorými hneď vyskúšate odoslanie aj príjem. Vlastný sandbox s dvoma syntetickými testovacími firmami vytvorí operátor ePošťáka po vyplnení formulára na epostak.sk/dev. Stačí uviesť e-mail, pre ktorý chcete prístup.
Znamená úspešná odpoveď API, že faktúra bola doručená?
Nie. Úspešná odpoveď znamená, že ePošťák dokument prijal na spracovanie. Doručenie potvrdzuje až doklad o doručení (MLS) od poštára odberateľa. Stav sledujte cez GET /api/v1/documents/{id}/status alebo webhook document.delivered. Hlásenie Finančnej správe SR má v odpovedi samostatný stav tdd.status.
Je potvrdenie prijatia v API to isté ako odpoveď na faktúru (Invoice Response)?
Nie. POST /api/v1/documents/inbox/{id}/acknowledge iba zapíše, že váš systém prijatú faktúru spracoval. Odosielateľovi nič neposiela a nemení stav faktúry v sieti Peppol. Obchodnú odpoveď odosielateľovi, napríklad akceptáciu alebo zamietnutie faktúry, pošlete samostatne cez POST /api/v1/documents/{id}/respond.
Existuje SDK pre ePošťák API?
Áno. Oficiálne TypeScript SDK je na npm ako balík @epostak/sdk; faktúru odošlete metódou client.enterprise.documents.send. SDK pre Python, PHP, .NET, Java a Ruby sú dostupné ako zdrojový kód na GitHube. Každé SDK je tenký obal nad REST API, takže môžete volať API aj priamo cez HTTP.