SAPI rozhranie pre Access Point

SprievodcoviaSAPI: keď ERP už vytvára hotový UBL 2.1

SAPI: keď ERP už vytvára hotový UBL 2.1

Najkratší tok: získajte token, odošlite hotový UBL v SAPI obale a prijaté dokumenty čítajte pollingom. Ak UBL nevytvárate, začnite Connectorom.

Vyberte si integračný tok

Začnite tam, kde sa práve nachádza váš tím: tokeny, odosielanie, príjem alebo prevádzka.

Začať

Najkratšia cesta od sandbox credentialov po prvý SAPI token.

  1. Získať SAPI tokenVymeňte client_id a client_secret za 15-minútový Bearer token.

Odosielanie

Ako zabaliť hotový UBL XML do SAPI requestu a bezpečne ho odoslať.

  1. Odoslať UBL dokumentPošlite hotový UBL XML s metadátami a idempotency key.

Príjem

Ako čítať doručené dokumenty a potvrdiť ich spracovanie.

  1. Prijať a potvrdiť dokumentyNačítajte dokumenty a po lokálnom spracovaní zavolajte acknowledge.
  2. Bezpečnosť a go-liveSecret handling, oddelené prostredia, tokeny, archív a ownership dát.

Získať SAPI token

Secret nikdy neposielajte ako Bearer token priamo; najprv ho vymeňte cez client_credentials a výsledný access_token cacheujte do expirácie. Použiť môžete firemný sk_live_* alebo centrálny sk_int_* technického partnera či spravovaného integrátora. Pri partnerskom tokene vyberte autorizovanú firmu hlavičkou X-Peppol-Participant-Id.

Postup

  1. 01Použite vydané sandbox credentialy firmy alebo sk_int_* credential pridelený partnerovi v jeho sandboxe.
  2. 02Zavolajte POST /sapi/v1/auth/token s grant_type client_credentials.
  3. 03Cacheujte access_token 15 minút a refresh_token 30 dní.
  4. 04Pri prvej 401 alebo pred expiráciou zavolajte /auth/renew.

Endpoint

POST/sapi/v1/auth/token
Vyskúšať

Token payload example

json
1{
2  "grant_type": "client_credentials",
3  "client_id": "487d008a-b3a5-49d0-be3e-ba45cc9c4ffe",
4  "client_secret": "sk_live_test_5e188b91708ca938e1ee50678b345a3c152b4d4a83d31eac",
5  "scope": "documents:send documents:read"
6}

Token response

json
1{
2  "access_token": "eyJhbGc...",
3  "refresh_token": "rt_...",
4  "token_type": "Bearer",
5  "expires_in": 900,
6  "scope": "documents:send documents:read"
7}

Povinné polia

NázovTypPovinnéPopis
grant_typestringánoMusí byť client_credentials.
client_idstringánoID alebo prefix vydaného firemného či integrátorského API kľúča.
client_secretstringánoCelý tajný sk_live_* alebo sk_int_* credential; uložte ho v secret manageri.
scopestringnieVoliteľné zúženie oprávnení, napr. documents:send documents:read.

Práca so stavmi

expires_in=900
Access token platí 15 minút; nemintujte ho pred každým volaním.
refresh_token
Refresh token rotuje pri /auth/renew a starý token sa invaliduje.
401
Použite renew alebo token endpoint, nie retry rovnakého expirovaného tokenu.

Chyby

401 AUTH
Credentialy nesedia, kľúč je vypnutý alebo demo kľúč používate na produkčnom hoste.
423 LOCKED
Opakované neúspešné pokusy sú dočasne obmedzené; platný secret ostáva použiteľný aj pri blokovaní chybných pokusov.

Ďalšie kroky

  • Po získaní tokenu zavolajte /auth/token/status ako health check.
  • Pri document endpointoch vždy pridajte X-Peppol-Participant-Id.

Odoslať hotový UBL cez SAPI

Toto je plný SAPI tvar requestu: JSON wrapper obsahuje metadata, payload je hotový UBL XML a hlavička X-Peppol-Participant-Id určuje pridelené Peppol ID, v mene ktorého voláte. Ak chcete JSON faktúru, OCR alebo Connector mapping, použite Enterprise API/Connector.

Postup

  1. 01V ERP vygenerujte validný Peppol BIS 3.0 UBL dokument.
  2. 02Vyplňte metadata podľa UBL: documentId, documentTypeId, processId, senderParticipantId a receiverParticipantId.
  3. 03Pridajte Authorization, X-Peppol-Participant-Id a Idempotency-Key.
  4. 04Odpoveď 202 znamená prijatie na spracovanie; konečný transportný stav sledujte príjmom alebo vlastnou evidenciou.

Endpoint

POST/sapi/v1/document/send
Vyskúšať

SAPI payload example

Ukážka zámerne obsahuje metadata aj UBL fragment, aby bolo jasné, ktoré polia patria do wrapperu a ktoré do samotného XML.

json
1{
2  "metadata": {
3    "documentId": "INV-2026-001",
4    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
5    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
6    "senderParticipantId": "0245:0000000001",
7    "receiverParticipantId": "0245:0000000002",
8    "creationDateTime": "2026-05-06T10:00:00Z"
9  },
10  "payload": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\"><cbc:ID>INV-2026-001</cbc:ID>...</Invoice>",
11  "payloadFormat": "XML",
12  "payloadEncoding": "UTF-8",
13  "checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
14}

UBL fragment

xml
1<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
2  xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
3  xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
4  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
5  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
6  <cbc:ID>INV-2026-001</cbc:ID>
7  <cbc:IssueDate>2026-05-06</cbc:IssueDate>
8  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
9  <cac:AccountingSupplierParty>
10    <cac:Party>
11      <cbc:EndpointID schemeID="0245">0000000001</cbc:EndpointID>
12    </cac:Party>
13  </cac:AccountingSupplierParty>
14  <cac:AccountingCustomerParty>
15    <cac:Party>
16      <cbc:EndpointID schemeID="0245">0000000002</cbc:EndpointID>
17    </cac:Party>
18  </cac:AccountingCustomerParty>
19</Invoice>

SAPI field contract

NázovTypPovinnéPopis
AuthorizationheaderánoBearer access_token z /auth/token.
X-Peppol-Participant-IdheaderánoPeppol ID odosielajúcej firmy, napr. 0245:0000000001.
Idempotency-KeyheaderánoUUID pre bezpečný retry bez duplicitného odoslania.
metadata.documentIdstringánoID faktúry/dokladu z vášho ERP, najviac 255 znakov.
metadata.documentTypeIdstringánoPlný Peppol document type URN.
metadata.processIdstringánoPeppol process ID pre billing flow.
payloadstringánoUBL XML obsah, nie base64.
payloadFormatstringánoMusí byť XML.

Práca so stavmi

202 ACCEPTED
Request prešiel vstupnou validáciou a bol prijatý na spracovanie.
409 CONFLICT
Idempotency-Key sa ešte spracováva alebo bol použitý s iným telom requestu; prípadne documentId už existuje mimo identického retry.
422 BUSINESS
Príjemca nie je v Peppole alebo neprijíma daný document type.

Chyby

400 VALIDATION
Chýba wrapper field, documentId presahuje 255 znakov alebo payloadFormat nie je XML.
422 VALIDATION
metadata.documentTypeId nepasuje k UBL root elementu, napríklad Invoice vs CreditNote.
422 SAPI-DOC-025
EndpointID dodávateľa alebo odberateľa v UBL sa nezhoduje s metadata.senderParticipantId alebo metadata.receiverParticipantId.
503 TEMPORARY
Opakujte s rovnakým Idempotency-Key a exponenciálnym backoffom.

Ďalšie kroky

  • Pre self-billing zachovajte správne party role priamo v UBL; SAPI XML nemení.
  • ID z /document/send je odosielateľský outbound záznam. Prijímateľ si pre detail a acknowledge berie samostatné documentId z odpovede /document/receive.
  • Ak chcete aby ePošťák skladal UBL z JSON-u, použite Enterprise API alebo Connector.

Prijať a potvrdiť dokumenty

SAPI príjem je polling flow. Každé volanie je scoped cez X-Peppol-Participant-Id; server overí aktívne priradenie vybratej schránky k integrátorovi a požadovaný scope tokenu.

Postup

  1. 01Volajte GET /document/receive?status=RECEIVED&limit=100 s Peppol ID prijímateľa.
  2. 02Zoznam je stránkovaný od najstarších nespracovaných dokumentov; ak príde nextPageToken, pokračujte ďalšou stránkou.
  3. 03Pre každý documentId stiahnite detail a payload.
  4. 04Spracujte UBL vo vlastnom systéme.
  5. 05Po úspešnom spracovaní zavolajte acknowledge, aby sa dokument nevracal ako nový.

Endpoint

GET/sapi/v1/document/receive
Vyskúšať

List response

json
1{
2  "documents": [
3    {
4      "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec",
5      "senderParticipantId": "iso6523-actorid-upis::0245:0000000001",
6      "receiverParticipantId": "iso6523-actorid-upis::0245:0000000002",
7      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##...",
8      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
9      "creationDateTime": "2026-05-06T10:00:00.000Z"
10    }
11  ],
12  "nextPageToken": "opaque-page-token"
13}

Acknowledge response

json
1{
2  "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec",
3  "status": "ACKNOWLEDGED",
4  "acknowledgedDateTime": "2026-05-06T10:05:00.000Z"
5}

Povinné polia

NázovTypPovinnéPopis
X-Peppol-Participant-IdheaderánoPeppol ID schránky, ktorú čítate.
statusquerynieRECEIVED pre nové dokumenty, ACKNOWLEDGED pre už potvrdené.
pageTokenqueryniePoužite pri stránkovaní väčších objemov.
documentIdpathánodocumentId z odpovede /document/receive.

Práca so stavmi

RECEIVED
Dokument čaká na spracovanie vo vašom systéme.
ACKNOWLEDGED
Dokument ste potvrdili a nebude sa vracať medzi novými.
nextPageToken
Ak nie je null, pokračujte ďalšou stránkou.

Chyby

403 FORBIDDEN
Token nepatrí Peppol ID v hlavičke.
404 NOT_FOUND
documentId neexistuje alebo nepatrí tejto firme.

Ďalšie kroky

  • Acknowledge volajte až po úspešnom uložení dokumentu vo vašom systéme.
  • Nepárujte príjem podľa providerDocumentId zo send odpovede; prijímateľská strana používa documentId z odpovede /document/receive.
  • Ak potrebujete push namiesto pollingu, použite Enterprise webhooky.

SAPI bezpečnosť a go-live

Security sekcia má byť v dokumentácii, ale v správnej vrstve detailu: používateľ potrebuje vedieť, čo má chrániť a čo sa uchováva; interné kľúče, bucket názvy, presné infra routy a operátorské runbooky sem nepatria.

Postup

  1. 01Pred go-live oddeľte dev a produkčné credentialy.
  2. 02Uložte client_secret mimo kódu a logov.
  3. 03Cachujte access_token iba po dobu TTL a revokujte ho pri incidente.
  4. 04Uložte si vlastnú kópiu dokladu; ePošťák drží AS4 obálky v WORM archíve ako AP infraštruktúru.

Endpoint

GET/sapi/v1/auth/token/status
Vyskúšať

SAPI security contract

json
1{
2  "environmentIsolation": "dev credentials never work on live hosts",
3  "tokenTtlSeconds": 900,
4  "refreshTokenTtlDays": 30,
5  "participantBoundary": "X-Peppol-Participant-Id must match token permissions",
6  "payloadTransport": "UBL XML over HTTPS",
7  "archive": "signed AS4 envelopes retained in WORM storage for 10 years",
8  "doNotPublish": [
9    "client_secret",
10    "private keys",
11    "internal bucket names",
12    "operator runbooks"
13  ]
14}

SAPI security contract

NázovTypPovinnéPopis
client_secretsecretánoNikdy neposielať do frontendu, do logov ani do support screenshotov.
access_tokenJWTánoKrátkodobý Bearer token; revokovateľný a obnoviteľný.
X-Peppol-Participant-IdheaderánoTenant boundary pre SAPI dokumentové volania.
AS4 envelope archiveretentionnieSignované AS4 obálky uchovávame v WORM archíve 10 rokov.
document ownershiplegalnieVlastníkom a zákonným archivárom daňového dokladu ostáva vystaviteľ/príjemca.

Práca so stavmi

DEV
Sandbox credentialy fungujú iba na dev hoste.
LIVE
Produkčné credentialy vydávame po schválenom go-live.
WORM
AS4 obálky sú infraštruktúrny dôkaz doručenia, nie náhrada vašej účtovnej evidencie.

Chyby

credential leak
Okamžite revokujte tokeny a vymeňte secret.
wrong host
Demo secret na produkčnom hoste zámerne vráti Invalid client credentials.

Ďalšie kroky

  • Do verejnej dokumentácie dávame bezpečnostný kontrakt a očakávania, nie operačné internals.
  • Na enterprise procurement pridajte samostatný bezpečnostný balík: DPA, cieľ dostupnosti, incident contacts, IP allowlist podľa dohody.

Demo testovacie účty

Prostredia sú oddelené. DEV/test: tieto verejné demo kľúče fungujú na https://dev.epostak.sk/sapi/v1. Hodnoty jednej demo firmy vždy používajte spolu: demo client_id/client_secret a jej Peppol ID tvoria jeden pár. Ak máte vlastný sandbox v /integrator, nepoužívajte s ním demo ID 0245:0000000001/0000000002; do X-Peppol-Participant-Id aj metadata.senderParticipantId vložte vlastné pridelené ID z /integrator/firms. LIVE/produkcia: vlastné produkčné kľúče používajte na https://epostak.sk/sapi/v1. Demo kľúče na LIVE hoste zámerne vrátia Invalid client credentials.

Firma A - odosielateľ

0245:0000000001
client_id
487d008a-b3a5-49d0-be3e-ba45cc9c4ffe
client_secret
sk_live_••••••••••••••••1eac

Použite na test odoslania faktúry. V hlavičke X-Peppol-Participant-Id, v metadata.senderParticipantId.

Firma B - prijímateľ

0245:0000000002
client_id
b6649c59-2f9d-4ae2-a750-af257c455478
client_secret
sk_live_••••••••••••••••6733

Použite na test prijatia. Token mintnite vlastnými credentialmi B, request pošlite s X-Peppol-Participant-Id: 0245:0000000002.

Onboarding klienta

Čo je SAPI a ako napojiť prvého klienta cez ePošťák - od jeho registrácie u Finančnej správy až po prvý dokument.

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é rozhranie pre firmy a ich ERP. SAPI poskytuje minimálny set 8 endpointov - autentifikáciu (token / renew / revoke / status) a doručovanie dokumentov (send / list / detail / acknowledge). Žiadne firma-management API ani webhooky. Pošlete UBL XML, dostanete UBL XML, hotovo. Ak váš ERP vie generovať UBL Peppol BIS 3.0 faktúru, technická 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 používajte Enterprise API a jeho samostatný Enterprise OpenAPI JSON. SAPI zostáva čistý kompatibilný profil s 8 štandardnými endpointmi.
Obchodný model je nezávislý od API rozhrania a má tri režimy. Priamy klient podpíše vlastnú API objednávku, platí vlastnú spotrebu a používa sk_live_*. Dodávateľ ERP nepotrebuje platenú integrátorskú aktiváciu: ako technický partner podpíše zmluvu o technickom partnerstve a bez poplatku za samotné partnerské oprávnenie používa centrálny sk_int_*. Každá koncová firma však naďalej podpíše vlastnú API objednávku, platí Kaja Solutions vlastnú spotrebu a udelí partnerovi konkrétny odvolateľný súhlas; firemný tajný kľúč sa partnerovi neposiela. V spravovanom režime podpisuje integrátorskú zmluvu a súhrnne platí integrátor. Technický partner aj spravovaný integrátor môžu cez jeden sk_int_* používať SAPI, Enterprise API aj Connector, ktorý firmu vyberá cez customerRef. Produkčná aktivácia je zatiaľ manuálne schvaľovaný krok.
Krok 1: Overte firmu a zvoľte smer. Každá produkčná firma má u nás vlastný overený účet, Peppol ID 0245:DIČ, API oprávnenie a platiteľa. API môže používať iba na odosielanie, iba na príjem alebo oboma smermi. Pri režime iba odosielanie používame ePošťáka ako odosielajúci Access Point a Peppol ID nemusí byť zaregistrované na našom SMP účte; nastavenie príjmu u iného poskytovateľa tým nemeníme. Pre príjem cez ePošťáka musí byť firma priradená k našej prijímajúcej službe a jej Peppol ID publikované cez náš SMP. Detail výberu prijímajúceho poskytovateľa je v článku Ako si zvoliť digitálneho poštára.
Krok 2: Sandbox a produkčné prístupy. Pre bezplatný sandbox napíšte z pracovného e-mailu na info@epostak.sk; po overení operátor vytvorí integrátorský sandbox, testovacie firmy a podľa potreby webové schránky. Sandbox nevytvára produkčnú viazanosť. Produkciu schvaľuje Kaja Solutions. Priamy klient prijme vlastný zmluvný balík API a po spolupodpise spravuje sk_live_* vo firemnom konte. Technický partner najprv podpíše partnerskú zmluvu; po jej spolupodpise spravuje centrálny sk_int_* a v partnerskom konte vytvára chránené odkazy na súhlas. Každá firma sama prijme svoj API zmluvný balík a účtovanie. Spravovaný integrátor podpisuje integrátorskú zmluvu a platí súhrnne.
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 sandbox integrátor účte a testovacích firmách vydaných v dev portáli (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.

Autentifikácia

OAuth 2.0 client_credentials flow. Vymeňte existujúci client_id + secret za JWT a používajte ho ako Bearer token. SAPI podporuje firemné sk_live_* aj centrálne sk_int_* technického partnera alebo spravovaného integrátora.

Ž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.
Autorizácia participanta. Pri partnerskom tokene hlavička X-Peppol-Participant-Id vyberá firmu pre požiadavku. Server vždy overí aktívne priradenie, neodvolaný súhlas firmy, platné produkčné oprávnenie technického partnera alebo spravovaného integrátora a požadovaný rozsah v tokene.
Smerové oprávnenia. Režim iba odosielanie vydá kľúč so scope documents:send. Režim iba príjem používa documents:read documents:write, aby integrácia vedela dokument načítať a potvrdiť jeho prevzatie. Obojsmerný režim obsahuje všetky tri scopes. Pri partnerskom sk_int_* sa rovnaké obmedzenie vynucuje aj cez odvolateľný súhlas konkrétnej firmy.
API nie je bezplatná webová schránka. Bezplatný príjem vo webovom rozhraní nevydáva API credentials. Každá firma s produkčným API má samostatné aktívne API oprávnenie a platiteľa; účtuje sa jej skutočný počet odoslaných a prijatých dokumentov cez API podľa zmluvy a cenníka.
POST/sapi/v1/auth/token

Získať token

OAuth 2.0 client_credentials grant. Vymeňte client_id + client_secret (sk_live_* alebo existujúci integrátorský sk_int_*) za krátkodobý JWT access_token (15 min) a long-lived refresh_token (30 dní). Existujúci SAPI klienti ani ich endpointy sa nemenia. Token, client_id, client_secret a X-Peppol-Participant-Id musia patriť k tomu istému sandboxu: vlastné credentialy nikdy nekombinujte so spoločnými demo Peppol ID 0245:0000000001/0000000002. Vlastné Peppol ID nájdete v /integrator/firms. Token cachujte v pamäti a nevytvárajte ho nanovo pri každom requeste.

Parametre

NázovTypPovinnéPopis
client_idstringREQUUID prideľený pri registrácii
client_secretstringREQsk_live_* alebo existujúci sk_int_* tajný kľúč
grant_typestringREQMusí byť client_credentials
scopestringoptionalVoliteľný subset povolených scope-ov, oddelený medzerami

Príklady volania

cURL
curl -X POST https://dev.epostak.sk/sapi/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "487d008a-b3a5-49d0-be3e-ba45cc9c4ffe",
    "client_secret": "sk_live_test_5e188b91708ca938e1ee50678b345a3c152b4d4a83d31eac",
    "grant_type": "client_credentials"
  }'

Príklady odpovedí

200 OK
{
  "access_token": "eyJhbGc...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "documents:send documents:read"
}

Odpovede

  • 200OK
  • 400Invalid grant_type
  • 401Invalid credentials
  • 403IP not allowed
  • 423Account locked (5 fails / 10 min)
GET/sapi/v1/auth/token/status

Stav tokenu

Skontroluje či je access_token ešte platný, kedy expiruje, a či ho treba obnoviť. issued_at, expires_at a refresh_recommended_at sú ISO 8601 časy v UTC (končia na Z), nie lokálny čas Europe/Bratislava. Pole should_refresh prejde na true ~3 minúty pred expiráciou - vtedy zavolajte /auth/renew.

Parametre

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token>

Príklady volania

cURL
curl https://dev.epostak.sk/sapi/v1/auth/token/status \
  -H "Authorization: Bearer $TOKEN"

Príklady odpovedí

200 OK
{
  "valid": true,
  "token_type": "access",
  "client_id": "487d008a-b3a5-49d0-be3e-ba45cc9c4ffe",
  "firm_id": "b1022d80-5016-4dad-a8d2-53685cab1701",
  "key_type": "sk_live",
  "scope": "documents:send documents:read",
  "issued_at": "2026-05-06T10:00:00.000Z",
  "expires_at": "2026-05-06T10:15:00.000Z",
  "expires_in_seconds": 720,
  "should_refresh": false,
  "refresh_recommended_at": "2026-05-06T10:12:00.000Z"
}

Odpovede

  • 200OK
  • 401Invalid token
POST/sapi/v1/auth/renew

Obnoviť token

Vymeňte refresh_token za nový pár (token rotation). Starý refresh_token sa okamžite invaliduje - opätovné použitie vráti 401 (replay protection).

Parametre

NázovTypPovinnéPopis
grant_typestringREQMusí byť refresh_token
refresh_tokenstringREQPlatný refresh token rt_...

Príklady volania

cURL
curl -X POST https://dev.epostak.sk/sapi/v1/auth/renew \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","refresh_token":"rt_..."}'

Príklady odpovedí

200 Nový pár tokenov
{
  "access_token": "eyJhbGc...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 900
}

Odpovede

  • 200Nový pár tokenov
  • 401Invalid or replayed refresh_token
POST/sapi/v1/auth/revoke

Zrušiť token

Idempotentne zruší prístup access alebo refresh tokenu. Pri access tokene sa jeho jti pridá do Redis blocklistu na zvyšok TTL; pri refresh tokene sa zmaže server-side stav. Vždy 200 (idempotent).

Parametre

NázovTypPovinnéPopis
tokenstringREQJWT alebo rt_... token
token_type_hintstringoptionalVoliteľne: "access_token" | "refresh_token"

Príklady volania

cURL
curl -X POST https://dev.epostak.sk/sapi/v1/auth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token":"rt_..."}'

Odpovede

  • 200Revoked (or already revoked)

Dokumenty

Odosielanie a prijímanie Peppol dokumentov ako UBL XML.

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. Hlavička X-Peppol-Participant-Id: 0245:DIČ vyberá firmu; server následne overí jej aktívne priradenie, neodvolaný súhlas a rozsah tokenu. Jeden partnerský credential tak môže obsluhovať iba firmy, ktoré ho výslovne autorizovali, bez zmeny SAPI endpointov.
Idempotency-Key. Pri /document/send je povinné poslať Idempotency-Key: &lt;UUID&gt; - opakovanie po sieťovej chybe s rovnakým UUID vráti uloženú odpoveď, po prijatí zvyčajne 202, namiesto duplicitného odoslania.
POST/sapi/v1/document/send

Odoslať dokument

Odošle dokument cez Peppol sieť (UBL XML). Pred odoslaním overíme cez SMP, že je príjemca v sieti - ak nie, vraciame 422. Idempotency-Key (UUID) je povinný; opakovanie s rovnakým telom vráti uloženú odpoveď, po prijatí zvyčajne 202.

Parametre

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token>
X-Peppol-Participant-IdstringREQPeppol ID odosielateľa, napr. 0245:0000000001
Idempotency-KeystringREQUUID - opakovaný request s rovnakým telom vráti uloženú odpoveď
metadataobjectREQ{ documentId, documentTypeId, processId, senderParticipantId, receiverParticipantId, creationDateTime }
payloadstringREQUBL XML obsah faktúry
payloadFormatstringREQMusí byť "XML"
payloadEncodingstringoptionalVoliteľné, default "UTF-8"
checksumstringoptionalVoliteľný SHA-256 hex digest payloadu

Príklady volania

cURL
curl -X POST https://dev.epostak.sk/sapi/v1/document/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Peppol-Participant-Id: 0245:0000000001" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "documentId": "INV-2026-001",
      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "senderParticipantId": "0245:0000000001",
      "receiverParticipantId": "0245:0000000002",
      "creationDateTime": "2026-05-06T10:00:00Z"
    },
    "payload": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>",
    "payloadFormat": "XML"
  }'

Príklady odpovedí

202 Accepted
{
  "providerDocumentId": "bec4f875-996f-4794-b42e-8f3b5b2f1ba4",
  "status": "ACCEPTED",
  "receivedAt": "2026-05-06T10:00:00.000Z",
  "timestamp": "2026-05-06T10:00:00.000Z"
}

Odpovede

  • 202Accepted
  • 400Invalid request
  • 401Invalid token
  • 403No permission for this firm
  • 409Idempotency key in-flight/mismatch, or duplicate documentId outside an identical retry
  • 422Recipient not registered in Peppol
  • 503Temporarily unavailable
GET/sapi/v1/document/receive

Zoznam prijatých

Vráti zoznam dokumentov, ktoré dorazili na váš Peppol ID. Na čítanie nových dokladov volajte status=RECEIVED. Zoznam je stránkovaný od najstarších nespracovaných dokumentov; pri väčších objemoch pokračujte cez pageToken.

Parametre

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token>
X-Peppol-Participant-IdstringREQPeppol ID prijímateľa, napr. 0245:0000000002
limitintegeroptional1-100, default 20
statusstringoptionalRECEIVED pre nové doklady | ACKNOWLEDGED pre už potvrdené
pageTokenstringoptionalToken na ďalšiu stránku

Príklady volania

cURL
curl "https://dev.epostak.sk/sapi/v1/document/receive?status=RECEIVED&limit=100" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:0000000002"

Príklady odpovedí

200 OK
{
  "documents": [
    {
      "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec",
      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "senderParticipantId": "iso6523-actorid-upis::0245:0000000001",
      "receiverParticipantId": "iso6523-actorid-upis::0245:0000000002",
      "creationDateTime": "2026-05-06T10:00:00.000Z"
    }
  ]
}

Odpovede

  • 200OK
  • 401Invalid token
  • 403No permission
GET/sapi/v1/document/receive/{documentId}

Detail prijatého dokumentu

Vráti plný UBL XML payload prijatého dokumentu vrátane metadát.

Parametre

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token>
X-Peppol-Participant-IdstringREQPeppol ID príjemcu, napr. 0245:0000000001
documentIdstringREQdocumentId z odpovede /document/receive

Príklady volania

cURL
curl https://dev.epostak.sk/sapi/v1/document/receive/{documentId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:0000000002"

Príklady odpovedí

200 OK
{
  "metadata": { "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec", "documentTypeId": "...", "processId": "...", "senderParticipantId": "...", "receiverParticipantId": "...", "creationDateTime": "..." },
  "payload": "<Invoice xmlns=...>...</Invoice>",
  "payloadFormat": "XML"
}

Odpovede

  • 200OK
  • 401Invalid token
  • 404Document not found
POST/sapi/v1/document/receive/{documentId}/acknowledge

Potvrdiť prijatie

Označí dokument ako spracovaný - prejde zo stavu RECEIVED do ACKNOWLEDGED. Po potvrdení sa už nevracia v zozname so status=RECEIVED.

Parametre

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token>
X-Peppol-Participant-IdstringREQPeppol ID príjemcu, napr. 0245:0000000001
documentIdstringREQdocumentId z odpovede /document/receive

Príklady volania

cURL
curl -X POST https://dev.epostak.sk/sapi/v1/document/receive/{documentId}/acknowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Peppol-Participant-Id: 0245:0000000002"

Príklady odpovedí

200 Acknowledged
{
  "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec",
  "status": "ACKNOWLEDGED",
  "acknowledgedDateTime": "2026-05-06T10:05:00.000Z"
}

Odpovede

  • 200Acknowledged
  • 401Invalid token
  • 404Document not found

Referencia

Chybové kódy, rate limity, uchovávanie dát.

Cenník

Transparentné ceny bez skrytých poplatkov.

Sandbox

Testovacie prostredie pre integráciu (Firma A / Firma B vydané v dev portáli).

ObjemCena
Neobmedzenezadarmo

Odoslané

Cena za dokument odoslaný cez Peppol cez POST /document/send.

ObjemCena
1 – 1 0000,10 €
1 001 – 2 0000,08 €
2 001 – 5 0000,06 €
5 001 – 20 0000,05 €
20 001+individuálne

Prijaté

Cena za dokument prijatý cez Peppol a sprístupnený cez GET /document/receive.

ObjemCena
1 – 1 0000,08 €
1 001 – 2 0000,07 €
2 001 – 5 0000,06 €
5 001 – 20 0000,05 €
20 001+individuálne

Ceny sú bez DPH. Platí sa len za dokumenty skutočne doručené cez Peppol - ak SMP príjemcu nenájde alebo doručenie zlyhá, neúčtujeme. Sandbox je neobmedzený a zadarmo.

Rate limity

Limitácia požiadaviek na API kľúč.

Pravidlá

  • Štandardné endpointy200 / 60 s
  • POST /document/send150 / 60 s

Hlavičky odpovede (HTTP 429)

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After

Hlavičky sa vracajú len v HTTP 429 odpovediach. Odporúčame exponenciálny backoff.

Chybové kódy

Chyby sa vracajú vo formáte {"error":{"code":"...","message":"...","requestId":"..."}}. Kódy označené ako retryable je bezpečné opakovať s exponenciálnym backoffom.

StatusKódPopis
400VALIDATIONNeplatný request - chýbajúce alebo zlé pole
401AUTHNeplatný alebo expirovaný token
403FORBIDDENToken je platný, ale X-Peppol-Participant-Id nepatrí tomuto integrátorovi alebo chýba požadovaný scope. Použite Peppol ID pridelené v /integrator/firms; spoločné demo ID fungujú iba s príslušnými demo credentialmi.
404NOT_FOUNDDokument neexistuje alebo nepatrí volajúcej firme
409CONFLICTretryableIdempotency key sa práve spracováva (in-flight collision)
422VALIDATIONUBL metadata nesedia so samotným XML dokumentom
422BUSINESSPríjemca nie je v Peppol sieti, alebo SMP neakceptuje doctype
423LOCKEDÚčet zablokovaný (5 zlých prihlásení / 10 min)
429RATE_LIMITEDretryablePrekročený rate limit
503TEMPORARYretryableDočasná nedostupnosť - opakujte s exponenciálnym backoffom

Uchovávanie dát

Trvalý archív AS4 obálok

Každá signovaná AS4 obálka - odoslaná aj prijatá - sa automaticky ukladá do WORM MinIO bucketu so S3 Object Lock v režime COMPLIANCE na 10 rokov ako infraštruktúra Access Pointu. Platí pre všetky firmy bez ohľadu na plán.

Vlastník dokumentov

Zákonná povinnosť uchovávať daňové doklady 10 rokov (zákon 431/2002 §35) je na vystaviteľovi/príjemcovi faktúry - vy zostávate vlastníkom dokumentov. WORM archív AS4 obálok slúži ako infraštruktúrny dôkaz doručenia, nie ako náhrada vašej účtovnej archivácie.