SAPI-SK: prehľad
SAPI-SK (Standardised Access Point Interface) je slovenský otvorený štandard, ktorý definuje jednotné rozhranie medzi Peppol Access Pointmi („digitálnymi poštármi") a účtovným či ERP softvérom. Integrujete sa raz, a viete odosielať aj prijímať e-faktúry cez ľubovoľného poskytovateľa, ktorý štandard podporuje.
Čo je SAPI-SK
Štandard vzniká pod hlavičkou Finančnej správy SR a OpenPeppol komunity ako dobrovoľná, poskytovateľsky nezávislá vrstva. eFaktúra ho implementuje vo verzii v1.0: každá interakcia (autentifikácia, odoslanie, príjem, potvrdenie) má vlastnú normatívnu schému požiadavky a odpovede. Oficiálnu špecifikáciu nájdete na www.sapi-sk.sk.
Prečo cez SAPI-SK
Namiesto proprietárneho API konkrétneho AP sa napojíte na jeden štandardizovaný kontrakt. Ak zmeníte poskytovateľa (alebo ich používate viac), integráciu nemusíte prepisovať. eFaktúra je vaším Access Pointom: odbaví validáciu, prenos cez Peppol sieť aj archiváciu.
Základné informácie
Základná URL je https://api.efaktura.sk/sapi. Všetky dokumentové volania sú chránené OAuth 2.0 prístupovým tokenom (Bearer) a hlavičkou X-Peppol-Participant-Id, ktorá určuje organizáciu (Peppol účastníka), v mene ktorej konáte.
Prehľad endpointov
| Metóda | Cesta | Popis |
|---|---|---|
| POST | /auth/token | Výmena client credentials za access + refresh token. |
| GET | /auth/token/status | Stav a expirácia access tokenu (odporúčanie na obnovu). |
| POST | /auth/renew | Obnova tokenov cez refresh token (s rotáciou). |
| POST | /auth/revoke | Zneplatnenie refresh tokenu (idempotentné). |
| POST | /document/send | Odoslanie dokumentu (UBL XML) na doručenie cez Peppol. |
| GET | /document/receive | Zoznam prijatých dokumentov (cursor stránkovanie). |
| GET | /document/receive/{id} | Detail a obsah konkrétneho prijatého dokumentu. |
| POST | /document/receive/{id}/acknowledge | Potvrdenie prevzatia dokumentu (idempotentné). |
Prihlasovacie údaje
Prihlasovacie údaje vydáva eFaktúra daňovému subjektu, nie výrobcovi softvéru — presne ako to predpokladá štandard. Sú dve cesty:
Firma (koncový zákazník) si client ID a client secret vygeneruje priamo v aplikácii eFaktúra: Nastavenia → API kľúče → karta SAPI-SK — napojenie účtovného softvéru (vlastník alebo administrátor firmy, od plánu Pro). Údaje vloží do svojho účtovného softvéru spolu s Peppol identifikátorom firmy (0245:DIČ), ktorý softvér posiela v hlavičke X-Peppol-Participant-Id. Klient je viazaný na túto jednu firmu; funguje po aktivácii e-faktúr (výber eFaktúry na portáli Finančnej správy) — dovtedy vracia SAPI-AUTH-003.
Partner (výrobca softvéru, integrátor) si klientov vytvára v partnerskom developer portáli (developers.efaktura.sk → SAPI-SK, cesta /dashboard/sapi; samoobslužná registrácia na developers.efaktura.sk/register) — testovací klient okamžite, ostrý po podpise zmluvy a aktivácii produkcie. Partnerský klient smie pracovať len s firmami, ktoré partner sám založil.
Secret sa v oboch prípadoch zobrazí iba raz pri vytvorení, takže bezpečne si ho uložte. Ďalší postup nájdete v sekcii Autentifikácia (OAuth2).
Kredity
Odoslanie cez SAPI-SK sa účtuje presne ako každé iné odoslanie e-faktúry: najprv sa čerpá bezplatná mesačná kvóta plánu, potom kredity (v roku 2026 platí promo zdarma). Príjem dokumentov je vždy zdarma.