Čo je SAPI-SK a prečo ho používať?

Štandardizované národné REST rozhranie medzi klientskym alebo ERP systémom a prístupovým bodom Peppol (sapi-sk.sk). Implementujeme ho v plnom rozsahu, takže nie ste viazaní na náš proprietárny tvar API a integráciu napíšete raz pre ktorýkoľvek SAPI-SK Access Point. Prehľad bez technických detailov je v článku SAPI-SK pre vývojárov, úplná referencia v dokumentácii pre vývojárov.

OAuth2 client_credentials: client_id je UUID vášho API tokenu a client_secret je samotný token vpt_ z portálu (ľavé menu API tokeny, záložka API kľúče, tlačidlo Vytvoriť token). POST /sapi/auth/token vráti access token na 15 minút a refresh token na 30 dní; token používajte celých 15 minút, nový token na každé volanie je zbytočná réžia. Zrušenie API tokenu v portáli okamžite zneplatní aj /auth/token aj /auth/renew.

Môžem si API vyskúšať bez registrácie?

Áno. Verejné sandbox údaje client_id = sandbox a client_secret = sandbox validujú požiadavky ako ostrá prevádzka, ale nikdy nič neodošlú do siete Peppol a vracajú mock odpovede. Na reálny tok s doručením, doručenkou a webhookmi slúži testovacie prostredie test.peppol.verteco.digital, kde sa firmy schvaľujú automaticky a doručenie ide cez testovaciu sieť Peppol, zadarmo a bez limitov na skúšanie.

Čo sa stane, keď príjemca nie je v sieti Peppol?

Doklad najprv prejde validáciou. Platný doklad prevezmeme a nahlásime Finančnej správe aj vtedy, keď príjemca v sieti nie je (odpoveď ACCEPTED s undeliverable: true, v zozname odoslaných stav undeliverable). Príjemcovi však tú istú faktúru treba poslať inou cestou, najlepšie jej XML e-mailom; keď sa zaregistruje, pošlete ju cez Peppol znova s rovnakým Idempotency-Key. Pred odoslaním príjemcu overíte cez GET /sapi/discovery.

Ako zistím stav doručenia?

GET /sapi/document/sent vracia pri každom riadku stav (submitted, delivered, rejected, undeliverable), časy sentAt, deliveredAt a fsReportedAt a doručenku MLS. Polling každých 1 až 5 minút je plnohodnotná cesta; webhooky invoice.delivered, invoice.rejected a invoice.undeliverable sú doplnok, nie podmienka.

Prepojenie je zadarmo. Služba stojí od €2/mes bez DPH za IČO, ktoré odosiela alebo má zapnutý Archív dát; príjem s vypnutým archívom je zadarmo (do 1 000 faktúr mesačne). Počas dobrovoľného obdobia pred mandátom 1. 1. 2027 je všetko bezplatné.

Integrácie / Pre vývojárov / REST API (SAPI-SK)

REST API (SAPI-SK)

K dispozícii

SAPI-SK je štandardizované národné REST rozhranie medzi vaším systémom alebo ERP a prístupovým bodom Peppol. Implementujeme ho v plnom rozsahu, takže integráciu napíšete raz pre ktorýkoľvek SAPI-SK Access Point a nie ste viazaní na náš proprietárny tvar API. Odosielanie, príjem, stav doručenia s doručenkou MLS aj hlásenie Finančnej správe máte v jednom rozhraní, s OpenAPI 3.1 špecifikáciou a plnohodnotným testovacím prostredím zadarmo.

Získať plugin v portáli Vytvoriť účet zadarmo

Ako to funguje

1Vytvorte si účet v portáli a pridajte firmu. V ľavom menu otvorte API tokeny a na záložke API kľúče kliknite na Vytvoriť token. Token vpt_ sa zobrazí iba raz; pre SAPI-SK je client_id ID tokenu (UUID) a client_secret samotný token.
2Vyskúšajte si celý tok na test.peppol.verteco.digital: kompletná kópia portálu s oddelenými dátami, kde sa firmy schvaľujú automaticky a doručenie ide reálne cez testovaciu sieť Peppol. Stačí vymeniť doménu a použiť tokeny vytvorené v testovacom prostredí. Na rýchly test bez registrácie slúžia verejné údaje client_id = sandbox a client_secret = sandbox (nič sa nikdy nedoručí).
3Získajte access token cez POST /sapi/auth/token (grant_type client_credentials; platí 15 minút, refresh token 30 dní). Doklad odošlite cez POST /sapi/document/send s hlavičkami X-Peppol-Participant-Id a Idempotency-Key; pred odoslaním môžete zavolať POST /sapi/document/validate a GET /sapi/discovery.
4Prijaté doklady sťahujte cez GET /sapi/document/receive (parametre ?since a ?until na inkrementálne sťahovanie) a stav odoslaných cez GET /sapi/document/sent, prípadne cez webhooky invoice.delivered, invoice.rejected a invoice.undeliverable.
5Pri prechode do produkcie vymeňte doménu za peppol.verteco.digital a vytvorte produkčný účet aj tokeny. Odosielanie odomyká Verifikačný údaj, ktorý firma získa výberom Verteco ako poskytovateľa na portáli Finančnej správy.

Čo integrácia rieši

✓Odoslanie (POST /sapi/document/send), hromadné odoslanie až 100 dokladov (POST /sapi/document/batch) a validácia bez odoslania (POST /sapi/document/validate)
✓Príjem dokladov s filtrom ?since a ?until, originál XML, HTML, PDF aj prílohy ku každému prijatému dokladu
✓Stav odoslaných dokladov s doručenkou MLS, časmi sentAt, deliveredAt a fsReportedAt a časovou osou dokladu (events)
✓Idempotency-Key: opakované volanie nikdy nedoručí faktúru dvakrát; po oprave chyby pošlete doklad znova s rovnakým kľúčom
✓OpenAPI 3.1 špecifikácia na /api/v1/openapi.json: import do Postmanu alebo vygenerovanie typovaného klienta (TS, Java, PHP, Python)
✓Jedným tokenom obslúžite viac firiem cez hlavičku X-Peppol-Participant-Id; sandbox aj testovacie prostredie sú zadarmo

Časté otázky: e-faktúry pre REST API (SAPI-SK)

Čo je SAPI-SK a prečo ho používať?: Štandardizované národné REST rozhranie medzi klientskym alebo ERP systémom a prístupovým bodom Peppol (sapi-sk.sk). Implementujeme ho v plnom rozsahu, takže nie ste viazaní na náš proprietárny tvar API a integráciu napíšete raz pre ktorýkoľvek SAPI-SK Access Point. Prehľad bez technických detailov je v článku SAPI-SK pre vývojárov, úplná referencia v dokumentácii pre vývojárov.
Ako sa prihlásim?: OAuth2 client_credentials: client_id je UUID vášho API tokenu a client_secret je samotný token vpt_ z portálu (ľavé menu API tokeny, záložka API kľúče, tlačidlo Vytvoriť token). POST /sapi/auth/token vráti access token na 15 minút a refresh token na 30 dní; token používajte celých 15 minút, nový token na každé volanie je zbytočná réžia. Zrušenie API tokenu v portáli okamžite zneplatní aj /auth/token aj /auth/renew.
Môžem si API vyskúšať bez registrácie?: Áno. Verejné sandbox údaje client_id = sandbox a client_secret = sandbox validujú požiadavky ako ostrá prevádzka, ale nikdy nič neodošlú do siete Peppol a vracajú mock odpovede. Na reálny tok s doručením, doručenkou a webhookmi slúži testovacie prostredie test.peppol.verteco.digital, kde sa firmy schvaľujú automaticky a doručenie ide cez testovaciu sieť Peppol, zadarmo a bez limitov na skúšanie.
Čo sa stane, keď príjemca nie je v sieti Peppol?: Doklad najprv prejde validáciou. Platný doklad prevezmeme a nahlásime Finančnej správe aj vtedy, keď príjemca v sieti nie je (odpoveď ACCEPTED s undeliverable: true, v zozname odoslaných stav undeliverable). Príjemcovi však tú istú faktúru treba poslať inou cestou, najlepšie jej XML e-mailom; keď sa zaregistruje, pošlete ju cez Peppol znova s rovnakým Idempotency-Key. Pred odoslaním príjemcu overíte cez GET /sapi/discovery.
Ako zistím stav doručenia?: GET /sapi/document/sent vracia pri každom riadku stav (submitted, delivered, rejected, undeliverable), časy sentAt, deliveredAt a fsReportedAt a doručenku MLS. Polling každých 1 až 5 minút je plnohodnotná cesta; webhooky invoice.delivered, invoice.rejected a invoice.undeliverable sú doplnok, nie podmienka.
Koľko to stojí?: Prepojenie je zadarmo. Služba stojí od €2/mes bez DPH za IČO, ktoré odosiela alebo má zapnutý Archív dát; príjem s vypnutým archívom je zadarmo (do 1 000 faktúr mesačne). Počas dobrovoľného obdobia pred mandátom 1. 1. 2027 je všetko bezplatné.

Začnite ešte dnes: stačí výber na portáli Finančnej správy

Príjem zadarmo · bez viazanosti a skrytých poplatkovSplňte si zákonnú povinnosť 2027 za 2 minúty

Vybrať Verteco na portáli Finančnej správy →Na portáli dáte „Pokračovať", prihlásite sa (slovensko.sk / eID alebo prihlasovacie údaje do portálu FS) a potvrdíte výber. Zvyšok spravíme automatickyCertifikovaný poskytovateľ (EFSK000031) · bez viazanosti · poskytovateľa môžete kedykoľvek zmeniť

Ako výber prebieha? (3 kroky, ~2 minúty)

1Kliknete na tlačidlo vyššie. Otvorí sa oficiálna stránka Finančnej správy „Výber certifikovaného poskytovateľa" s predvybraným Verteco. Kliknete „Pokračovať".
2Prihlásite sa na Portál finančnej správy, cez slovensko.sk (eID / občiansky s čipom) alebo svojimi prihlasovacími údajmi do PFS, a potvrdíte výber poskytovateľa.
3Hotovo. Príde vám e-mail s prihlásením. Účet, firmu aj registráciu v sieti Peppol vytvoríme automaticky. Ak váš príjem už drží iný poskytovateľ, záznam nepreberáme: pošleme vám postup s migračným kódom, alebo si v portáli zvolíte, že príjem ostáva u neho a cez nás len odosielate.
Nemáte eID? Na portál Finančnej správy sa prihlásite aj identifikátorom a heslom (prihlasovacie údaje PFS). Prípadne sa zaregistrujte e-mailom a heslom, firmu pridajte ručne a výber dokončte neskôr.
Nevidíte svoju firmu vo výbere daňového subjektu? Ponúkajú sa len subjekty, za ktoré máte na portáli FS autorizáciu. Pridajte si ju v Osobnej internetovej zóne (Autorizácie → Pridať autorizovaného používateľa) a výber dokončíte.
Podrobný návod k výberu na portáli FS →

Súvisiace: Peppol overenie firmy · sprievodca e-faktúrou 2027 · cenník · všetky integrácie