SAPI — Standardised Access Point Interface

SAPI-SK 1.0 je otvorený štandard, na ktorom sa zhodli slovenskí Peppol Access Point operátori, aby integrátorov nezaháknuli na jeden konkrétny back-end. Jedna integrácia, ľubovoľný AP — keď to raz urobíte pre jedného poskytovateľa, rovnaké volania fungujú aj proti hocikomu inému kto SAPI implementuje. Špecifikáciu nájdete na sapi-sk.sk.

Zjednodušená verzia pre integrátorov. SAPI poskytuje minimálny set 8 endpointov — autentifikáciu (token / renew / revoke / status) a doručovanie dokumentov (send / list / detail / acknowledge). Žiadne dashboardy, žiadne firma-management API, žiadne webhooky. Pošlete UBL XML, dostanete UBL XML, hotovo. Ak váš ERP vie generovať UBL Peppol BIS 3.0 faktúru, integrácia je otázka 1-2 dní.

Potrebujete viac? Pre webhooky, OCR rozpoznávanie PDF/skenov, JSON režim, hromadné operácie alebo správu viacerých klientskych firiem z jedného účtu odporúčame náš rozšírený Enterprise API. Funguje paralelne so SAPI — môžete ich miešať podľa potreby.

Časový rámec. Voľba digitálneho poštára na portáli Finančnej správy SR sa plánuje spustiť koncom mája 2026, kedy začína obdobie dobrovoľnej elektronickej fakturácie. Od 1. januára 2027 je elektronická fakturácia povinná pre všetkých platiteľov DPH na Slovensku.

Krok 1: Klient si zvolí ePošťáka. Váš klient sa prihlási na portál Finančnej správy SR a v zozname certifikovaných poskytovateľov doručovacej služby si zvolí ePošťáka (Kaja Solutions s.r.o.). Následne si u nás vytvorí konto. My ho automaticky zaregistrujeme do centrálneho SMP a vytvoríme mu Peppol ID v tvare 0245:DIČ. Týmto sa stáva viditeľným v celej európskej Peppol sieti. Detailne v článku Ako si zvoliť digitálneho poštára.

Krok 2: Vyžiadajte si SAPI prístup. SAPI nepoužíva OAuth consent flow ako Enterprise API — namiesto toho dostanete od nás client_id a client_secret priamo viazaný na konkrétne Peppol ID. Pre testovanie použite verejné sandbox kľúče nižšie (Firma A / Firma B). Pre produkčné kľúče napíšte na info@epostak.sk — potrebujeme zoznam Peppol ID, za ktoré budete posielať alebo prijímať.

Krok 3: Implementujte 8 endpointov. Vymeňte client credentials za JWT cez POST /sapi/v1/auth/token, cachujte access_token, posielajte UBL Peppol BIS 3.0 cez POST /sapi/v1/document/send s hlavičkou X-Peppol-Participant-Id identifikujúcou firmu, kontrolujte príjmy cez GET /sapi/v1/document/receive a potvrdzujte spracované dokumenty cez POST /sapi/v1/document/receive/{id}/acknowledge. Detailne v sekcii Authentication a Documents nižšie.

Pred produkciou si všetko overte na zdieľaných sandbox účtoch (Firma A / Firma B nižšie). Krok-za-krokom sprievodca aj s code snippetmi je v článku Ako integrovať digitálneho poštára do vášho ERP.

Životnosť tokenov. access_token platí 15 minút (expires_in: 900), refresh_token 30 dní. Cachujte access_token v pamäti — nevolajte /auth/token pred každým requestom (rate-limit + ~100 ms latencia navyše). Pri prvej 401 alebo proaktívne ~1 minútu pred expiráciou zavolajte /auth/renew.

Refresh token rotation. /auth/renew vždy vráti nový pár — starý refresh_token sa okamžite invaliduje. Replay (opätovné použitie už raz spotrebovaného refresh tokenu) vráti 401.

UBL XML in, UBL XML out. SAPI je transport-only — vy posielate hotový UBL Peppol BIS 3.0 dokument, my ho doručíme cez AS4 a vrátime UBL od protistrany. Validáciu schemou a schematronom robíme na našej strane (UBL 2.1 XSD + EN 16931 + Peppol BIS 3.0 schematrons), ale formát musí prísť od vás.

X-Peppol-Participant-Id header. Posielate alebo prijímate vždy v mene konkrétneho Peppol ID — header X-Peppol-Participant-Id: 0245:DIČ hovorí, ktorá firma je zdrojom alebo cieľom requestu. Token sám o sebe nevie ku ktorej firme akcia patrí.

Idempotency-Key. Pri /document/send je povinné poslať Idempotency-Key: <UUID> — opakovanie po sieťovej chybe s rovnakým UUID vráti cached 202 namiesto duplicitného odoslania.