ePošťák API pre e-fakturáciu, ERP a integrátorov

Od 1. januára 2027 sa povinnosť vyhotovovať štruktúrované e-faktúry vzťahuje na tuzemských platiteľov DPH pri zákonom vymedzených tuzemských plneniach; zákon zároveň zavádza povinnosť dotknutých príjemcov vedieť e-faktúru prijať. ePošťák pre tieto procesy ponúka REST API, ktoré pokrýva celý životný cyklus faktúry: odoslanie, príjem, validáciu, archiváciu, reporting pre Finančnú správu aj pripojenie ERP alebo účtovného softvéru. Popri portáli ide o infraštruktúru, na ktorej môžu vývojári, integrátori a ERP dodávatelia stavať vlastné riešenia.

V tomto článku vysvetlíme, prečo je „kompletné API" pre e-fakturáciu dôležité, aký je rozdiel medzi SAPI a Enterprise API a ako sa dá pripojiť cez dostupné SDK podľa aktuálnej verzie a prečo sa REST integrácia hodí firmám s vlastným ERP systémom.

Povinnosť e-fakturácie od roku 2027 nie je len administratívna zmena. Týka sa úplne každého toku faktúry vo firme — od e-shopu cez ERP až po účtovný softvér. Ak firma vystaví mesačne desať faktúr, stačí jej webový formulár digitálneho poštára. Ale ak ich má päťsto, alebo ak faktúry vznikajú automaticky v ERP systéme, ručné prepisovanie do portálu je mŕtva cesta.

API rozhoduje o troch veciach: rýchlosti (faktúra sa odošle automaticky v sekunde po vystavení v ERP), spoľahlivosti (žiadne ručné chyby, žiadne zabudnuté faktúry) a škálovaní (rovnako funguje pre 10 aj 10 000 faktúr mesačne). Podrobný rozbor automatizácie nájdete aj v článku Automatizácia fakturačného toku cez e-faktúru.

„Kompletné" v našom ponímaní znamená, že nad našou sieťou viete postaviť úplne celý produkt — nielen odoslať faktúru, ale aj overiť príjemcu, prijať prichádzajúce faktúry, validovať ich podľa EN 16931, reagovať na ne fakturačnou odpoveďou, reportovať do Finančnej správy a archivovať po zákonnú dobu desať rokov. Toto je všetko, čo kompletné API pokrýva:

Na Slovensku vzniká spoločný otvorený štandard pre komunikáciu s digitálnymi poštármi — tzv. SAPI (Standard API špecifikácia od PASR). Nie je povinný zo zákona, no PASR ho odporúča každému certifikovanému poštárovi, aby mali dodávatelia ERP a fakturačných softvérov jednotné rozhranie. Raz implementované volania potom fungujú proti ktorémukoľvek poštárovi, ktorý SAPI podporuje. ePošťák zverejňuje podporovaný SAPI kontrakt vo svojej dokumentácii; pred integráciou overte konkrétnu verziu, operácie, rozsahy oprávnení a testovacie prostredie.

Enterprise API je naše vlastné rozšírenie nad SAPI — prináša funkcie, ktoré SAPI štandard nepokrýva: OCR, správu viacerých firiem pod jedným účtom, hromadné operácie, rozšírenú archiváciu, webhooky s retry logikou a reporting. Je určené integrátorom, ktorí chcú postaviť plnohodnotné riešenie pre koncových zákazníkov.

SDK môžu zjednodušiť volania a typovanie. Aktuálne podporované jazyky a vydania overte v repozitári a balíčkových registroch. TypeScript SDK je publikovaný na npm, ostatné SDK sú dostupné na GitHube.

Kompletné odoslanie faktúry v TypeScripte vyzerá takto:

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

const client = new EPostak({ apiKey: "sk_live_..." });

const result = await client.documents.send({
  receiverPeppolId: "0245:1234567890",
  invoiceNumber: "FV-2026-001",
  issueDate: "2026-04-23",
  dueDate: "2026-05-07",
  items: [
    { description: "Konzultácia", quantity: 10, unitPrice: 50, vatRate: 23 },
  ],
});

console.log(result.peppolMessageId);

Desať riadkov kódu — faktúra validovaná, odoslaná cez Peppol, archivovaná a nahlásená na FS SR.

Namiesto toho, aby ste sa museli každých pár minút pýtať „prišla mi nová faktúra?", webhooky obrátia smer komunikácie — my vám zavoláme, len čo sa niečo stane. Nastavíte jeden endpoint na svojej strane a prihlásite sa na tieto udalosti:

Každá udalosť obsahuje identifikátor dokumentu, firmu a časovú pečiatku. Každé volanie je kryptograficky podpísané, aby ste si overili, že reálne prišlo z ePošťáka. Pri dočasnom výpadku vašej strany webhook inteligentne opakuje volanie, kým prejde.

Nie každá prichádzajúca faktúra je elektronická. Stále vám chodia papierové faktúry, PDF v maile alebo nascanované dokumenty. Pošlete obrázok alebo PDF a vrátime štruktúrované dáta, ktoré môžete rovno poslať do svojho účtovného systému alebo ich automaticky pretransformovať na plnohodnotnú Peppol e-faktúru.

Extrakcia pokrýva dodávateľa (IČO, DIČ, IČ DPH, adresa), odberateľa, položky faktúry, sumy, DPH sadzby, termíny splatnosti aj bankové spojenie — všetko podľa európskej normy EN 16931, takže výstup je kompatibilný s celým Peppol ekosystémom.

Pretože naše API je postavené na otvorenej špecifikácii OpenAPI 3.1, môže ho zavolať doslova čokoľvek — od moderného Node.js servera po dvadsať rokov starú Delphi aplikáciu cez jednoduchý HTTP klient. V praxi najčastejšie vidíme tieto scenáre:

Cesta od „chcem to vyskúšať" po prvú odoslanú faktúru cez API začína overením dokumentácie, vytvorením testovacích údajov a získaním oprávnení pre zvolený kontrakt. Presný onboarding a dostupnosť sandboxu overte v aktuálnej dokumentácii.

1. 01

   Testovacie prostredie

   Dostupnosť sandboxu, testovacích kľúčov a podporovaných účastníkov overte v aktuálnej Enterprise API dokumentácii. Produkčný prístup závisí od overenia firmy, oprávnení a aktivácie; univerzálnu lehotu nesľubujeme.

   Dokumentácia Enterprise API →
2. 02

   Inštalácia SDK

   Dostupné SDK, podporované jazyky, verzie a spôsob inštalácie overte v živej dokumentácii a oficiálnych repozitároch. Typy pomáhajú so schémou požiadavky, no nenahrádzajú serverovú validáciu ani testovanie chybových stavov.

   Dokumentácia Enterprise API →
3. 03

   Prvé volanie

   Po odoslaní si uchovajte identifikátor dokumentu. Odpoveď 202 znamená prijatie na spracovanie, nie doručenie; životný cyklus sledujte cez dokumentovaný Enterprise status endpoint alebo webhook.

   Príklady v dokumentácii →