SAPI

SAPI rozhranie pre Access Point

SprievodcoviaSprievodcovia

Sprievodcovia

Praktické integračné postupy pre tokeny, odosielanie, príjem, bezpečnosť, Box a prevádzku.

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 sprievodcoviaOdosielanieAko zabaliť hotový UBL XML do SAPI requestu a bezpečne ho odoslať.1 sprievodcoviaPríjemAko čítať doručené dokumenty a potvrdiť ich spracovanie.2 sprievodcovia

Získať SAPI token

Vymeňte client_id a client_secret konkrétnej firmy za krátkodobý Bearer token.

1

Odoslať UBL dokument

SAPI neprerába faktúru z JSON-u. Posielate hotový UBL XML plus metadata a idempotency key.

2

Prijať a potvrdiť dokumenty

Pollujte dokumenty pre konkrétne Peppol ID, stiahnite detail a po spracovaní zavolajte acknowledge.

3

Bezpečnosť a go-live

Čo je bezpečné dokumentovať verejne: secret handling, oddelené prostredia, tokeny, WORM archív a ownership dát.

4

1. Získať SAPI token

SAPI token je viazaný na konkrétne credentialy a firmu. Secret nikdy neposielajte ako Bearer token priamo; najprv ho vymeňte cez client_credentials a výsledný access_token cacheujte do expirácie.

Postup

  1. 1Použite sandbox credentialy firmy A alebo B z demo účtov.
  2. 2Zavolajte POST /sapi/v1/auth/token s grant_type client_credentials.
  3. 3Cacheujte access_token 15 minút a refresh_token 30 dní.
  4. 4Pri 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_iduuidánoUUID vydané pre konkrétnu firmu/Peppol ID.
client_secretstringánoTajný sk_live_* 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

Po opakovaných chybných pokusoch je účet dočasne zablokovaný.

Ďalšie kroky

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

2. 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 firmu, v ktorej mene posielate. Ak chcete JSON faktúru, OCR alebo Connector mapping, použite Enterprise API/Connector.

Postup

  1. 1V ERP vygenerujte validný Peppol BIS 3.0 UBL dokument.
  2. 2Vyplňte metadata podľa UBL: documentId, documentTypeId, processId, senderParticipantId a receiverParticipantId.
  3. 3Pridajte Authorization, X-Peppol-Participant-Id a Idempotency-Key.
  4. 4Odpoveď 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.
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, metadata nesedia s UBL alebo payloadFormat nie je XML.

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.

3. Prijať a potvrdiť dokumenty

SAPI príjem je polling flow. Každé volanie je scoped cez X-Peppol-Participant-Id, takže token a header musia patriť firme, ktorej schránku čítate.

Postup

  1. 1Volajte GET /document/receive?status=RECEIVED&limit=100 s Peppol ID prijímateľa.
  2. 2Zoznam je stránkovaný od najstarších nespracovaných dokumentov; ak príde nextPageToken, pokračujte ďalšou stránkou.
  3. 3Pre každý documentId stiahnite detail a payload.
  4. 4Spracujte UBL vo vlastnom systéme.
  5. 5Po ú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.

4. 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. 1Pred go-live oddeľte dev a produkčné credentialy.
  2. 2Uložte client_secret mimo kódu a logov.
  3. 3Cachujte access_token iba po dobu TTL a revokujte ho pri incidente.
  4. 4Ulož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, SLA, 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. 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. Demo účty sú zaregistrované v testovacej Peppol sieti - môžete medzi nimi reálne posielať dokumenty bez registrácie.

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á 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 používajte Enterprise API a jeho samostatný Enterprise OpenAPI JSON. SAPI zostáva čistý kompatibilný profil s 8 štandardnými endpointmi.
Časový rámec. Klient si ePošťáka volí cez portál Finančnej správy SR; sandbox slúži na technické overenie napojenia pred produkčným go-live. Produkčný integrátorský prístup riešime po schválenom go-live a podpísanej zmluve. 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 sandbox integrátor login na dev.epostak.sk/integrator; po schválení vám vydá sandbox kľúče pre Firmu A / Firmu B nižšie. Produkčná aktivácia na epostak.sk/integrator/aktivacia je až pre schválený go-live po podpísanej zmluve.
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 client_id + secret za JWT a používajte ako Bearer token.

Ž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.
POST/sapi/v1/auth/token

Získať token

OAuth 2.0 client_credentials grant. Vymeňte client_id + client_secret za krátkodobý JWT access_token (15 min) a long-lived refresh_token (30 dní). Volajte tento endpoint raz, token cachujte v pamäti - pri každej požiadavke ho znovu nemintujte.

Parametre

NázovTypPovinnéPopis
client_idstringREQUUID prideľený pri registrácii
client_secretstringREQsk_live_* alebo 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ť. 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 - 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: &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+0,06 €
5 000+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+0,06 €
5 000+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 nemá oprávnenie pre túto firmu/scope
404NOT_FOUNDDokument neexistuje alebo nepatrí volajúcej firme
409CONFLICTretryableIdempotency key sa práve spracováva (in-flight collision)
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. Naša WORM infraštruktúra túto povinnosť pokrýva, ale formálne ju neprenášame na seba.