Co je SAPI-SK a proč ho používat?

Standardizované národní REST rozhraní mezi klientským nebo ERP systémem a přístupovým bodem Peppol (sapi-sk.sk). Implementujeme ho v plném rozsahu, takže nejste vázáni na náš proprietární tvar API a integraci napíšete jednou pro kterýkoli SAPI-SK Access Point. Přehled bez technických detailů je v článku SAPI-SK pro vývojáře, úplná reference v dokumentaci pro vývojáře.

OAuth2 client_credentials: client_id je UUID vašeho API tokenu a client_secret je samotný token vpt_ z portálu (levé menu API tokeny, záložka API klíče, tlačítko Vytvořit token). POST /sapi/auth/token vrátí access token na 15 minut a refresh token na 30 dní; token používejte celých 15 minut, nový token na každé volání je zbytečná režie. Zrušení API tokenu v portálu okamžitě zneplatní i /auth/token i /auth/renew.

Mohu si API vyzkoušet bez registrace?

Ano. Veřejné sandbox údaje client_id = sandbox a client_secret = sandbox validují požadavky jako ostrý provoz, ale nikdy nic neodešlou do sítě Peppol a vracejí mock odpovědi. Pro reálný tok s doručením, doručenkou a webhooky slouží testovací prostředí test.peppol.verteco.digital, kde se firmy schvalují automaticky a doručení jde přes testovací síť Peppol, zdarma a bez limitů na zkoušení.

Co se stane, když příjemce není v síti Peppol?

Doklad nejprve projde validací. Platný doklad převezmeme a nahlásíme Finanční správě i tehdy, když příjemce v síti není (odpověď ACCEPTED s undeliverable: true, v seznamu odeslaných stav undeliverable). Příjemci však tutéž fakturu je třeba poslat jinou cestou, nejlépe její XML e-mailem; když se zaregistruje, pošlete ji přes Peppol znovu se stejným Idempotency-Key. Před odesláním příjemce ověříte přes GET /sapi/discovery.

Jak zjistím stav doručení?

GET /sapi/document/sent vrací u každého řádku stav (submitted, delivered, rejected, undeliverable), časy sentAt, deliveredAt a fsReportedAt a doručenku MLS. Polling každých 1 až 5 minut je plnohodnotná cesta; webhooky invoice.delivered, invoice.rejected a invoice.undeliverable jsou doplněk, ne podmínka.

Propojení je zdarma. Služba stojí od €2/měs bez DPH za IČO, které odesílá nebo má zapnutý Archiv dat; příjem s vypnutým archivem je zdarma (do 1 000 faktur měsíčně). Během dobrovolného období před mandátem 1. 1. 2027 je všechno bezplatné.

Integrace / Pro vývojáře / REST API (SAPI-SK)

REST rozhraní SAPI-SK

K dispozici

SAPI-SK je standardizované národní REST rozhraní mezi vaším systémem nebo ERP a přístupovým bodem Peppol. Implementujeme ho v plném rozsahu, takže integraci napíšete jednou pro kterýkoli SAPI-SK Access Point a nejste vázáni na náš proprietární tvar API. Odesílání, příjem, stav doručení s doručenkou MLS i hlášení Finanční správě máte v jednom rozhraní, s OpenAPI 3.1 specifikací a plnohodnotným testovacím prostředím zdarma.

Získat plugin v portálu Vytvořit účet zdarma

Jak to funguje

1Vytvořte si účet v portálu a přidejte firmu. V levém menu otevřete API tokeny a na záložce API klíče klikněte na Vytvořit token. Token vpt_ se zobrazí pouze jednou; pro SAPI-SK je client_id ID tokenu (UUID) a client_secret samotný token.
2Vyzkoušejte si celý tok na test.peppol.verteco.digital: kompletní kopie portálu s oddělenými daty, kde se firmy schvalují automaticky a doručení jde reálně přes testovací síť Peppol. Stačí vyměnit doménu a použít tokeny vytvořené v testovacím prostředí. Na rychlý test bez registrace slouží veřejné údaje client_id = sandbox a client_secret = sandbox (nic se nikdy nedoručí).
3Získejte access token přes POST /sapi/auth/token (grant_type client_credentials; platí 15 minut, refresh token 30 dní). Doklad odešlete přes POST /sapi/document/send s hlavičkami X-Peppol-Participant-Id a Idempotency-Key; před odesláním můžete zavolat POST /sapi/document/validate a GET /sapi/discovery.
4Přijaté doklady stahujte přes GET /sapi/document/receive (parametry ?since a ?until na inkrementální stahování) a stav odeslaných přes GET /sapi/document/sent, případně přes webhooky invoice.delivered, invoice.rejected a invoice.undeliverable.
5Při přechodu do produkce vyměňte doménu za peppol.verteco.digital a vytvořte produkční účet i tokeny. Odesílání odemyká Verifikační údaj, který firma získá výběrem Verteco jako poskytovatele na portálu Finanční správy.

Co integrace řeší

✓Odeslání (POST /sapi/document/send), hromadné odeslání až 100 dokladů (POST /sapi/document/batch) a validace bez odeslání (POST /sapi/document/validate)
✓Příjem dokladů s filtrem ?since a ?until, originál XML, HTML, PDF i přílohy ke každému přijatému dokladu
✓Stav odeslaných dokladů s doručenkou MLS, časy sentAt, deliveredAt a fsReportedAt a časovou osou dokladu (events)
✓Idempotency-Key: opakované volání nikdy nedoručí fakturu dvakrát; po opravě chyby pošlete doklad znovu se stejným klíčem
✓OpenAPI 3.1 specifikace na /api/v1/openapi.json: import do Postmanu nebo vygenerování typovaného klienta (TS, Java, PHP, Python)
✓Jedním tokenem obsloužíte více firem přes hlavičku X-Peppol-Participant-Id; sandbox i testovací prostředí jsou zdarma

Časté otázky: e-faktury pro REST API (SAPI-SK)

Co je SAPI-SK a proč ho používat?: Standardizované národní REST rozhraní mezi klientským nebo ERP systémem a přístupovým bodem Peppol (sapi-sk.sk). Implementujeme ho v plném rozsahu, takže nejste vázáni na náš proprietární tvar API a integraci napíšete jednou pro kterýkoli SAPI-SK Access Point. Přehled bez technických detailů je v článku SAPI-SK pro vývojáře, úplná reference v dokumentaci pro vývojáře.
Jak se přihlásím?: OAuth2 client_credentials: client_id je UUID vašeho API tokenu a client_secret je samotný token vpt_ z portálu (levé menu API tokeny, záložka API klíče, tlačítko Vytvořit token). POST /sapi/auth/token vrátí access token na 15 minut a refresh token na 30 dní; token používejte celých 15 minut, nový token na každé volání je zbytečná režie. Zrušení API tokenu v portálu okamžitě zneplatní i /auth/token i /auth/renew.
Mohu si API vyzkoušet bez registrace?: Ano. Veřejné sandbox údaje client_id = sandbox a client_secret = sandbox validují požadavky jako ostrý provoz, ale nikdy nic neodešlou do sítě Peppol a vracejí mock odpovědi. Pro reálný tok s doručením, doručenkou a webhooky slouží testovací prostředí test.peppol.verteco.digital, kde se firmy schvalují automaticky a doručení jde přes testovací síť Peppol, zdarma a bez limitů na zkoušení.
Co se stane, když příjemce není v síti Peppol?: Doklad nejprve projde validací. Platný doklad převezmeme a nahlásíme Finanční správě i tehdy, když příjemce v síti není (odpověď ACCEPTED s undeliverable: true, v seznamu odeslaných stav undeliverable). Příjemci však tutéž fakturu je třeba poslat jinou cestou, nejlépe její XML e-mailem; když se zaregistruje, pošlete ji přes Peppol znovu se stejným Idempotency-Key. Před odesláním příjemce ověříte přes GET /sapi/discovery.
Jak zjistím stav doručení?: GET /sapi/document/sent vrací u každého řádku stav (submitted, delivered, rejected, undeliverable), časy sentAt, deliveredAt a fsReportedAt a doručenku MLS. Polling každých 1 až 5 minut je plnohodnotná cesta; webhooky invoice.delivered, invoice.rejected a invoice.undeliverable jsou doplněk, ne podmínka.
Kolik to stojí?: Propojení je zdarma. Služba stojí od €2/měs bez DPH za IČO, které odesílá nebo má zapnutý Archiv dat; příjem s vypnutým archivem je zdarma (do 1 000 faktur měsíčně). Během dobrovolného období před mandátem 1. 1. 2027 je všechno bezplatné.

Začněte ještě dnes: stačí výběr na portálu Finanční správy

Příjem zdarma · bez závazků a skrytých poplatkůSplňte si zákonnou povinnost 2027 za 2 minuty

Vybrat Verteco na portálu Finanční správy →Na portálu kliknete na „Pokračovať" (Pokračovat), přihlásíte se (slovensko.sk / eID nebo přihlašovací údaje do portálu FS) a potvrdíte výběr, zbytek zařídíme automatickyCertifikovaný poskytovatel Finanční správy (EFSK000031) · bez závazku · poskytovatele můžete kdykoli změnit

Jak výběr probíhá? (3 kroky, ~2 minuty)

1Kliknete na tlačítko výše, otevře se oficiální stránka Finanční správy „Výber certifikovaného poskytovateľa" (Výběr certifikovaného poskytovatele) s předvybraným Verteco. Kliknete na „Pokračovať" (Pokračovat).
2Přihlásíte se do Portálu finanční správy, přes slovensko.sk (eID / občanský průkaz s čipem) nebo svými přihlašovacími údaji do PFS, a potvrdíte výběr poskytovatele.
3Hotovo, přijde vám e-mail s přihlášením. Účet, firmu i registraci v síti Peppol vytvoříme automaticky. Pokud váš příjem už drží jiný poskytovatel, záznam nepřebíráme: pošleme vám postup s migračním kódem, nebo si v portálu zvolíte, že příjem zůstává u něj a přes nás jen odesíláte.
Nemáte eID? Na portál Finanční správy se přihlásíte i identifikátorem a heslem (přihlašovací údaje PFS). Případně se zaregistrujte e-mailem a heslem, firmu přidejte ručně a výběr dokončete později.
Nevidíte svou firmu ve výběru daňového subjektu? Nabízejí se jen subjekty, ke kterým máte na portálu FS autorizaci. Přidejte si ji v Osobní internetové zóně (Autorizácie → Pridať autorizovaného používateľa) a výběr dokončíte.
Podrobný návod k výběru na portálu FS (slovensky) →

Související: Peppol ověření firmy · průvodce e-fakturou 2027 · ceník · všechny integrace