ePošťák.sk

Neviete, ktoré API zvoliť? Tri alebo štyri otázky stačia.

Vybrať správny postup

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 ACCEPTED znamená iba prijatie na spracovanie, nikdy nie dôkaz doručenia. Uložte providerDocumentId a konečný transportný stav zistite cez Enterprise GET /api/v1/documents/{id}/status alebo Enterprise webhook.

Endpoint

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

SAPI payload example

Toto je ilustrácia, nie spustiteľný doklad. Payload nahraďte kompletným platným UBL XML. Voliteľný checksum vynechajte alebo vypočítajte SHA-256 z presných bajtov payloadu. Ukážka 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}

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>

Finálny outbound status cez Enterprise API

Použite rovnaký Bearer JWT a providerDocumentId zo SAPI odpovede. X-Firm-Id je povinné iba pri centrálnom sk_int_*; pri firemnom sk_live_* ho neposielajte. Token aj firemný súhlas musia obsahovať documents:read. Ak namiesto pollingu vytvárate Enterprise webhook subscription, pridajte webhooks:write.

curl
1curl https://dev.epostak.sk/api/v1/documents/bec4f875-996f-4794-b42e-8f3b5b2f1ba4/status \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "X-Firm-Id: <UUID_ODOSIELAJUCEJ_FIRMY>"

Outbound status response

json
1{
2  "id": "bec4f875-996f-4794-b42e-8f3b5b2f1ba4",
3  "status": "delivered",
4  "statusHistory": [
5    { "status": "queued", "timestamp": "2026-05-06T10:00:00.000Z" },
6    { "status": "sent", "timestamp": "2026-05-06T10:00:03.000Z" },
7    { "status": "delivered", "timestamp": "2026-05-06T10:00:08.000Z" }
8  ],
9  "deliveredAt": "2026-05-06T10:00:08.000Z",
10  "invoiceResponseStatus": null,
11  "as4MessageId": "msg_peppol_xyz"
12}

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.
response.providerDocumentIdstringánoePošťák ID outbound dokumentu. Uložte ho a použite ako {id} v Enterprise status endpointe.

Práca so stavmi

202 ACCEPTED
Request prešiel vstupnou validáciou a bol prijatý na spracovanie. Nejde o potvrdenie doručenia Access Pointom príjemcu.
delivered
Enterprise lifecycle potvrdil transport k Access Pointu príjemcu; deliveredAt obsahuje čas potvrdenia.
sent
Dokument bol odoslaný do Peppol transportu, ale ešte nejde o finálne potvrdenie doručenia príjemcovmu Access Pointu.
rejected / send_failed / delivery_failed / validation_failed
Terminálna chyba alebo odmietnutie; detail hľadajte v statusHistory a validationResult.
status / tdd.status
status je vždy malými písmenami. Pri odoslanom doklade: queued, sending, sent, accepted, acknowledged, delivered, delivery_failed, send_failed, recipient_not_found, validation_failed, failed, rejected; neskôr aj paid, cancelled, archived, overdue. Neznámu hodnotu spracujte bez chyby. Veľké písmená (SENT, FAILED …) sú len hodnoty filtra GET /documents/outbox. statusHistory je záznam udalostí, nie zoznam stavov: obsahuje aj fs_reported alebo invoice_response_*_received. Hlásenie Finančnej správe je v poli tdd.status: not_started, submitted, unconfirmed, accepted, rejected, failed; konečné sú accepted a rejected, unconfirmed sa ešte zmení na accepted alebo rejected.
recipient_not_found
Terminálny stav, nie chyba: príjemca nie je zaregistrovaný v Peppol sieti (deliveryFailure.code = participant_not_found). Povinnosť odosielateľa je splnená odovzdaním dokladu (SA v1.2.1 §5.5, § 85o ods. 11), TDD zabezpečuje ePošťák. Doručte ho príjemcovi inou cestou. Opätovné odoslanie nie je povinné: ak sa odberateľ v zákonnej 15-dňovej lehote dodatočne zaregistruje, ten istý doklad môžete poslať znova (nový Idempotency-Key, rovnaký payload) a ePošťák potom Finančnej správe automaticky nahlási opravu (TDD Resubmit).
409 CONFLICT
Idempotency-Key sa ešte spracováva alebo bol použitý s iným telom requestu; documentId už existuje; alebo rovnaký UBL XML payload už bol odoslaný pod iným kľúčom či documentId (SAPI-DOC-024).
409 SAPI-DOC-024
Duplicitný UBL XML, nie chyba dátumu. details[].issue obsahuje duplicate_payload; nový kľúč ani metadata.documentId nevytvorí nový doklad. Zistite stav pôvodného dokladu: duplicita sama nepotvrdzuje doručenie. Pri nejasnom výsledku pôvodnej požiadavky opakujte rovnaké telo s rovnakým Idempotency-Key. Nesúlad dátumu vystavenia pri odovzdaní má samostatný kód 422 SAPI-DOC-027 a issue handoff_date_mismatch; uplatňuje sa od 1. 1. 2027.
422 BUSINESS
Registrovaný príjemca neprijíma daný document type. Neregistrovaný príjemca nie je chyba požiadavky: send vráti 202 s upozornením SAPI-DOC-014 v messages a doklad skončí v terminálnom stave recipient_not_found (povinnosť odosielateľa splnená, TDD zabezpečuje ePošťák; po dodatočnej registrácii odberateľa sa ten istý doklad pošle znova s novým Idempotency-Key a TDD ide ako Resubmit).

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.
422 SAPI-DOC-027
Od 1. 1. 2027 musí UBL IssueDate zodpovedať dňu odovzdania v Europe/Bratislava. Ak je tento deň po zákonnej lehote vystavenia, faktúru prijmeme s 202 a upozornením SAPI-DOC-028 v messages.
422 SAPI-DOC-029
Ťarchopis (InvoiceTypeCode 383) musí obsahovať číslo pôvodnej faktúry v BillingReference/InvoiceDocumentReference/ID (BT-25).
422 SAPI-DOC-042
Príjemca (receiverParticipantId) nemôže byť ten istý účastník ako odosielateľ, ani v testovacej sieti. Na test pošlite doklad inému účastníkovi.
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.
  • Enterprise webhook subscription vytvorená pre odosielajúcu firmu pokrýva aj SAPI dokumenty. Na vytvorenie alebo zmenu subscription je potrebné webhooks:write. Použite document.sent, document.delivered, document.delivery_failed, document.mls_received, document.rejected a document.response_received; staršie udalosti spred aktivácie sa spätne nedopĺňajú. MLS a Invoice Response sú oddelené udalosti; odmietnutie (RE) príde ako document.rejected.
  • invoiceResponseStatus je obchodná odpoveď príjemcu (napr. AP alebo RE), nie dôkaz transportného doručenia.
  • 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. Každé nové kolo začnite od prvej strany status=RECEIVED; uložený pageToken z predchádzajúceho kola nepoužívajte.
  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": "complete AS4 envelopes retained for 12 months; minimal transport evidence 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 archiveretentionnieKompletné AS4 obálky uchovávame 12 mesiacov; samostatný minimálny transportný dôkaz bez obsahu faktúry 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

Tieto kľúče sú zámerne verejné a fungujú len v sandboxe dev.epostak.sk.

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_test_5e188b91708ca938e1ee50678b345a3c152b4d4a83d31eac

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_test_e8a28d2e5ec006b2e27a3a1a92739fd93f1d71e70abe6733

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). Samotné SAPI nemá firma-management, outbound status endpoint ani webhook endpointy. Pošlete UBL XML, dostanete UBL XML, hotovo. ePošťák vie nad tým istým SAPI dokumentom sprístupniť outbound lifecycle cez Enterprise API. Ak váš ERP vie generovať UBL Peppol BIS 3.0 faktúru, technická integrácia je otázka 1-2 dní.
Potrebujete viac? Pre outbound status a webhooky nad dokumentmi odoslanými cez SAPI, OCR rozpoznávanie PDF/skenov, JSON režim, hromadné operácie alebo správu viacerých klientskych firiem používajte Enterprise API a jeho samostatný Enterprise OpenAPI JSON. SAPI zostáva čistý kompatibilný profil s 8 štandardnými endpointmi.
Kto podpisuje a kto platí, určuje typ spolupráce, nie rozhranie. Priama firma si API objedná sama v Nastaveniach → API, platí ho sama a používa vlastný kľúč sk_live_*; kľúč môže odovzdať aj dodávateľovi softvéru. Technický partner (dodávateľ ERP) podpíše bezplatnú zmluvu o technickom partnerstve a používa jeden vlastný kľúč sk_int_* pre všetky pripojené firmy. Každá firma platí API sama podľa cenníka: potvrdením odkazu od partnera mu povolí prístup a zároveň si objedná API, žiadny kľúč partnerovi neposiela a prístup môže kedykoľvek odvolať. Spravovaný integrátor podpíše integrátorskú zmluvu a platí za všetky firmy jednou faktúrou. Technický partner aj spravovaný integrátor používajú cez jeden sk_int_* SAPI, Enterprise API aj Connector, ktorý firmu vyberá cez customerRef. Porovnanie s príkladmi je na stránke API integrácia. 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ť v SMP zaregistrované na príjem cez ePošťáka; 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 zaregistrované v SMP s ePošťákom ako prijímajúcim poskytovateľom. 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. Bezplatný sandbox si vyžiadate na <a href="https://dev.epostak.sk/dev">dev.epostak.sk/dev</a>. Prístup pripravíme v pracovný deň do 4 hodín, príde e-mailom; účet a dve testovacie firmy A a B sú pripravené a prepojené. Vlastný API kľúč si vytvoríte v portáli. 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.
Pozvánky z ERP. Chránený odkaz vytvoríte cez POST /api/v1/consent-offers v Enterprise Core; stav sledujte cez GET /api/v1/consent-offers/{offerId}. Použite existujúci partnerský JWT z /sapi/v1/auth/token. Tieto onboardingové operácie nevyžadujú nesúvisiace oprávnenie na Enterprise doklady a nesprístupňujú ostatné Enterprise operácie. SAPI štandard zostáva bez zmeny. Firma súhlas sama potvrdí a accepted ešte nepotvrdzuje dokončenú aktiváciu. Postup a príklady.
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 z dev portálu (vlastné client_id a ID účastníkov nájdete na stránke Začíname). 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.
Jeden centrálny kľúč pre viac sandbox participantov. Pri integrátorskom sk_int_* používate jeden client_id a client_secret pre všetky pridelené testovacie firmy; pre druhý participant nepotrebujete druhú sadu credentials. Konkrétnu firmu vyberá každý SAPI request cez X-Peppol-Participant-Id. Ak s tým istým JWT voláte Enterprise endpoint, firmu vyberte jej UUID cez X-Firm-Id. Firemný sk_live_* je naopak viazaný iba na jednu firmu.
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. Enterprise status endpoint vyžaduje documents:read, preto samotný send-only scope na jeho volanie nestačí. 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

OAuth2 client_credentials grant. Vráti access_token (15 min) a refresh_token (30 dní). Telo môže byť JSON alebo application/x-www-form-urlencoded. Limit 10 požiadaviek za 60 s na IP adresu a na dvojicu client_id a client_secret. 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_idstringREQClient identifier shown with the key. Must match the API key row UUID or displayed key prefix; it is not the sk_live_*/sk_int_* secret.
client_secretstringREQFull sk_live_* or sk_int_* API key.
grant_typestringREQ (povolené: client_credentials)
scopestringoptionalOptional. Space-separated subset of the key scopes (documents:send, documents:read, documents:write); omitted = all scopes of the key.
api_interfacestringoptionalOptional. On /sapi only sapi is accepted (any other value is 400 SAPI-AUTH-004 path_mismatch). (povolené: sapi)

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 Token vydaný
{
  "access_token": "eyJhbGc...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "documents:send documents:read"
}

Odpovede

  • 200Token vydaný
  • 400Neplatné telo požiadavky: grant_type, scope alebo api_interface (details[].field)
  • 401Neplatné credentials
  • 403IP address not allowed for this client
  • 413Telo požiadavky je príliš veľké
  • 423Účet dočasne zablokovaný
  • 429Prekročený rate limit (RATE_LIMITED); počkajte podľa Retry-After
  • 503Dočasne nedostupná závislosť; opakujte po Retry-After
GET/sapi/v1/auth/token/status

Stav tokenu

Skontrolovať platnosť tokenu

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;access_token&gt; získaný cez POST /sapi/v1/auth/token (OAuth2 client_credentials).

Príklady volania

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

Príklady odpovedí

200 Stav tokenu
{
  "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

  • 200Stav tokenu
  • 401Neplatný token
POST/sapi/v1/auth/renew

Obnoviť token

Vymení refresh_token za nový pár tokenov. Starý refresh token sa zneplatní. Voliteľné api_interface môže byť na /sapi iba sapi. Limit 10 požiadaviek za 60 s na IP adresu.

Parametre

NázovTypPovinnéPopis
refresh_tokenstringREQ
api_interfacestringoptional (povolené: sapi)

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 Tokeny obnovené
{
  "access_token": "eyJhbGc...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 900
}

Odpovede

  • 200Tokeny obnovené
  • 400Neplatné telo požiadavky (refresh_token, api_interface)
  • 401Neplatný refresh token
  • 403Prístup pre toto rozhranie nie je povolený
  • 413Telo požiadavky je príliš veľké
  • 429Prekročený rate limit (RATE_LIMITED); počkajte podľa Retry-After
  • 500Interná chyba; opakujte neskôr
  • 503Dočasne nedostupná závislosť; opakujte po Retry-After
POST/sapi/v1/auth/revoke

Zrušiť token

Zruší refresh alebo access token. Bez token_type_hint server typ tokenu rozpozná sám. Limit 10 požiadaviek za 60 s na IP adresu.

Parametre

NázovTypPovinnéPopis
tokenstringREQ
token_type_hintstringoptionalOptional. Omitted = the server detects the token type. (povolené: 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

  • 200Token zrušený
  • 400Chýba token (SAPI-AUTH-014) alebo token_type_hint nemá povolenú hodnotu (SAPI-AUTH-015); rozlišuje details[].field
  • 401Token nie je platný
  • 413Telo požiadavky je príliš veľké
  • 429Prekročený rate limit (RATE_LIMITED); počkajte podľa Retry-After
  • 500Interná chyba; opakujte neskôr
  • 503Dočasne nedostupná závislosť; opakujte po Retry-After

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. Uloženú odpoveď garantujeme 24 hodín; neskorší pokus s rovnakým kľúčom a nezmeneným XML už neodošle nič, vráti 409 SAPI-DOC-024 s pôvodným providerDocumentId v details[]. Hodnotu metadata.creationDateTime uložíme k dokladu tak, ako ju pošlete; receivedAt v odpovedi je čas nášho servera.
Oprava a retry. Pri validačnej chybe 422 opravte UBL a použite nový Idempotency-Key; rovnaké metadata.documentId môžete zachovať, pretože neplatný payload sa neuloží ani neúčtuje. Pri retryable 503 opakujte nezmenený request s rovnakým kľúčom a exponenciálnym backoffom. Nový účtovný doklad vystavujte iba z obchodného dôvodu, nie kvôli technickej chybe SAPI.
Príjemca mimo siete Peppol a opätovné odoslanie. Pri neregistrovanom príjemcovi vráti send 202 s upozornením SAPI-DOC-014, doklad skončí v stave recipient_not_found a údaje Finančnej správe nahlásime (TDD); cez Peppol sa nedoručí. Opätovné odoslanie nie je povinné; ak doklad znova nepošlete, Finančnej správe sa už nič ďalšie nehlási. Ak sa odberateľ v zákonnej 15-dňovej lehote dodatočne zaregistruje a chcete mu doklad doručiť aj cez Peppol, pošlite ten istý doklad znova: nový Idempotency-Key a nezmenené UBL XML v poli payload (bajt po bajte, rovnaký odosielateľ, príjemca a typ dokladu); metadata.documentId môže ostať rovnaké. Doklad doručíme a Finančnej správe automaticky nahlásime opravu pôvodného hlásenia (TDD Resubmit). Pôvodný kľúč nič neodošle, vráti iba uloženú odpoveď. Kým príjemca zaregistrovaný nie je, vrátime znova 202 so SAPI-DOC-014 a pôvodným providerDocumentId bez nového dokladu, účtovania či hlásenia, takže pokus môžete opakovať. XML negenerujte nanovo: zmenené XML s rovnakým metadata.documentId odmietneme ako 409 SAPI-DOC-018. Dodržanie lehoty API nekontroluje. Postup vychádza zo stanoviska Finančnej správy SR z 8. 10. 2026 a zo Slovakia Solution Reference Architecture v1.2.1 (§5.5, §7.4.1).
Veľkosť dokladu a prílohy. Pole payload (celé UBL XML vrátane príloh BG-24 v cbc:EmbeddedDocumentBinaryObject) môže mať najviac 22 MB, celé telo požiadavky najviac 25 MB; väčší doklad vráti 413 SAPI-DOC-016. Base64 zväčší prílohu asi o tretinu, prílohy sa teda zmestia spolu do približne 15 MB. SAPI-SK 1.0 uvádza 10 MB, ePošťák prijme viac; rovnaký limit 22 MB platí pre hotové UBL v Enterprise API (XML režim) aj v Connectore. SAPI nekontroluje počet príloh ani veľkosť jednotlivej prílohy, iba veľkosť celého payload. Limity 20 súborov, 10 MB na súbor a 15 MB spolu z Enterprise API platia len pre pole attachments v JSON režime, kde prílohy posielate ako samostatné súbory a UBL zostaví ePošťák. Povolené mimeCode podľa Peppol BIS 3.0: application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.oasis.opendocument.spreadsheet. Väčšie podklady priložte odkazom cac:ExternalReference/cbc:URI (BT-124) alebo podklad zmenšite. Produkcia a sandbox majú rovnaké limity.
Outbound lifecycle po odpovedi 202. SAPI-SK 1.0 nemá samostatný outbound status endpoint. ePošťák však ukladá SAPI dokument do rovnakého lifecycle modelu: providerDocumentId zo send odpovede použite ako {id} v Enterprise GET /api/v1/documents/{id}/status alebo GET /api/v1/documents/{id}/events. Endpointy vyžadujú scope documents:read; pri centrálnom sk_int_* pridajte X-Firm-Id odosielajúcej firmy. document.mls_received rozlišuje AP/confirmed, AB/forwarded_unconfirmed a RE/rejected; AB nepotvrdzuje doručenie na C4. document.response_received je samostatná obchodná Invoice Response príjemcu; jej odmietnutie (RE) príde ako document.rejected. Alternatívou k pollingu sú Enterprise webhooky document.sent, document.delivered, document.delivery_failed, document.mls_received, document.rejected a document.response_received. Vytvorenie alebo zmena subscription vyžaduje scope webhooks:write; subscription zachytáva iba nové udalosti po aktivácii.
POST/sapi/v1/document/send

Odoslať dokument

Vyžaduje scope documents:send. Odošle UBL XML dokument (faktúra, dobropis, samozdanenie) cez Peppol sieť. Neplatný UBL sa odmietne pred uložením a účtovaním; po oprave použite nový Idempotency-Key, pričom metadata.documentId môžete zachovať. Odpoveď 202 ACCEPTED znamená iba prijatie na spracovanie, nie potvrdené doručenie. Ak príjemca nie je zaregistrovaný v Peppol sieti, odpoveď je tiež 202 s upozornením SAPI-DOC-014 v poli messages; dokument je uložený v terminálnom stave recipient_not_found, povinnosť odosielateľa je splnená odovzdaním (SA v1.2.1 §5.5, § 85o ods. 11 zákona o DPH), hlásenie Finančnej správe (TDD) zabezpečuje ePošťák, cez Peppol doručený nebude; doručte ho odberateľovi inou cestou. Faktúru vystavenú po zákonnej lehote (15 dní od dodania, pri súhrnnej faktúre od konca mesiaca; do 31. 12. 2026 sa posudzuje cbc:IssueDate, od 1. 1. 2027 deň odovzdania) neodmietame: odpoveď je 202 s upozornením SAPI-DOC-028 v poli messages a faktúru odošleme, doručíme a nahlásime Finančnej správe (§ 85o zákona o DPH, FAQ eFaktúra 2. 11. 2026). Opätovné odoslanie nie je povinné: ak sa odberateľ v zákonnej 15-dňovej lehote dodatočne zaregistruje, ten istý doklad môžete poslať znova (nový Idempotency-Key, rovnaký payload) a ePošťák potom Finančnej správe automaticky nahlási opravu (TDD Resubmit). providerDocumentId je ePošťák ID dokumentu a pri aktívnom Enterprise prístupe so scope documents:read sa používa ako {id} v GET /api/v1/documents/{id}/status a GET /api/v1/documents/{id}/events. Použite rovnaký Bearer JWT; pri centrálnom sk_int_* pridajte X-Firm-Id odosielajúcej firmy. document.mls_received rozlišuje AP/confirmed, AB/forwarded_unconfirmed a RE/rejected; AB nepotvrdzuje doručenie na C4. document.response_received je samostatná obchodná Invoice Response; jej odmietnutie (RE) príde ako document.rejected. Enterprise webhook subscription pre túto firmu pokrýva aj SAPI dokumenty cez document.sent, document.delivered, document.delivery_failed, document.mls_received, document.rejected a document.response_received; jej vytvorenie alebo zmena vyžaduje webhooks:write a udalosti spred aktivácie sa spätne nedopĺňajú.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;access_token&gt; získaný cez POST /sapi/v1/auth/token (OAuth2 client_credentials).
Idempotency-KeyuuidREQUUID pre deduplikáciu (platnosť 24h)
X-Peppol-Participant-IdstringREQPeppol ID odosielateľa (napr. 0245:12345678). Pri centrálnom sk_int_* vyberá jednu z pridelených firiem; pre druhého sandbox participanta netreba druhú sadu credentials.

Parametre

NázovTypPovinnéPopis
metadataobjectREQ
metadata.documentIdstringREQmax 255 znakov / chars
metadata.documentTypeIdstringREQ
metadata.processIdstringREQ
metadata.senderParticipantIdstringREQ
metadata.receiverParticipantIdstringREQ
metadata.creationDateTimedatetimeREQ
payloadstringREQUBL XML obsah dokumentu (max 23068672 znakov / chars)
payloadFormatstringREQ (default: XML) (povolené: XML)
payloadEncodingstringoptionalOptional. Only "UTF-8" is supported. (default: UTF-8) (povolené: UTF-8)
checksumstringoptionalSHA-256 hash payloadu (hex, voliteľné)

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 Dokument prijatý na spracovanie. Nejde o potvrdenie doručenia Access Pointom príjemcu. Uložte providerDocumentId pre následné sledovanie cez Enterprise status endpoint alebo Enterprise webhook.
{
  "providerDocumentId": "bec4f875-996f-4794-b42e-8f3b5b2f1ba4",
  "status": "ACCEPTED",
  "receivedAt": "2026-05-06T10:00:00.000Z",
  "timestamp": "2026-05-06T10:00:00.000Z",
  "messages": [
    {
      "code": "SAPI-DOC-014",
      "severity": "WARNING",
      "message": "Príjemca nie je zaregistrovaný v sieti Peppol. Dokument je uložený, povinnosť odoslať faktúru cez doručovaciu službu je splnená (§ 85o ods. 11 zákona o DPH) a hlásenie údajov Finančnej správe (TDD) zabezpečuje ePošťák. Cez Peppol dokument doručený nebude; doručte ho odberateľovi inou cestou. Opätovné odoslanie nie je povinné: ak sa odberateľ v zákonnej 15-dňovej lehote dodatočne zaregistruje, ten istý dokument môžete poslať znova s novým Idempotency-Key a ePošťák potom Finančnej správe automaticky nahlási opravu (TDD Resubmit).",
      "field": "metadata.receiverParticipantId",
      "issue": "participant_not_found",
      "value": "0245:4564564561"
    }
  ]
}

Odpovede

  • 202Dokument prijatý na spracovanie. Nejde o potvrdenie doručenia Access Pointom príjemcu. Uložte providerDocumentId pre následné sledovanie cez Enterprise status endpoint alebo Enterprise webhook.
  • 400Neplatný request
  • 401Authentication error
  • 403Authorization error (no organization access)
  • 409Konflikt Idempotency-Key (SAPI-PROC-002/003), duplicitný metadata.documentId (SAPI-DOC-018) alebo identický UBL XML payload (SAPI-DOC-024)
  • 422Príjemca nepodporuje dokument alebo dokument nespĺňa UBL/Peppol pravidlá (SAPI-DOC-015). Hodnota v UBL sa nedá uložiť, napríklad suma nad 9 999 999 999,99 (SAPI-DOC-036). Od 1. 1. 2027 nesúlad dátumu vystavenia pri odovzdaní používa SAPI-DOC-027 (details[].issue = handoff_date_mismatch). Prekročenie lehoty na vystavenie (15 dní od dodania) nie je chyba: faktúru prijmeme s 202 a upozornením SAPI-DOC-028 v poli messages.
  • 429Prekročená kvóta tarify (SAPI-PROC-004) alebo rate limit 150 zápisov za 60 s na kľúč (client_id) (RATE_LIMITED)
  • 500Interná chyba (SAPI-DOC-099); opakujte s rovnakým Idempotency-Key
  • 502Chyba Peppol siete
  • 503Dočasná nedostupnosť validácie alebo lookupu príjemcu (SAPI-DOC-012), uloženia (SAPI-DOC-010/011) alebo výsledok predchádzajúceho pokusu sa ešte dohľadáva (SAPI-PROC-005). Nezmenený request opakujte s rovnakým Idempotency-Key.
GET/sapi/v1/document/receive

Zoznam prijatých

Vyžaduje scope documents:read. Vráti stránkovaný zoznam dokumentov prijatých cez Peppol. Každé nové kolo pollingu začnite od prvej strany.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;access_token&gt; získaný cez POST /sapi/v1/auth/token (OAuth2 client_credentials).
X-Peppol-Participant-IdstringREQ

Parametre

NázovTypPovinnéPopis
limitinteger (query)optional1–100 (default: 20)
statusstring (query)optional (povolené: RECEIVED, ACKNOWLEDGED)
pageTokenstring (query)optionalKurzor pre ď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 Zoznam dokumentov
{
  "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

  • 200Zoznam dokumentov
  • 401Authentication error
  • 403Authorization error (no organization access)
GET/sapi/v1/document/receive/{documentId}

Detail prijatého dokumentu

Vyžaduje scope documents:read. Vráti kompletný dokument vrátane XML payloadu.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;access_token&gt; získaný cez POST /sapi/v1/auth/token (OAuth2 client_credentials).
X-Peppol-Participant-IdstringREQ

Parametre

NázovTypPovinnéPopis
documentIdstringREQ

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 Detail dokumentu
{
  "metadata": { "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec", "documentTypeId": "...", "processId": "...", "senderParticipantId": "...", "receiverParticipantId": "...", "creationDateTime": "..." },
  "payload": "<Invoice xmlns=...>...</Invoice>",
  "payloadFormat": "XML"
}

Odpovede

  • 200Detail dokumentu
  • 401Authentication error
  • 403Authorization error (missing scope or no access to the participant); a document of another receiver returns 404, not 403
  • 404Dokument neexistuje alebo patrí inému príjemcovi (SAPI-DOC-030 / SAPI-DOC-040)
POST/sapi/v1/document/receive/{documentId}/acknowledge

Potvrdiť prijatie

Vyžaduje scope documents:write. Lokálne označí prijatý dokument ako spracovaný (idempotentná operácia). Nie je to transportné potvrdenie pre odosielateľa a nemení jeho outbound delivery status.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;access_token&gt; získaný cez POST /sapi/v1/auth/token (OAuth2 client_credentials).
X-Peppol-Participant-IdstringREQ

Parametre

NázovTypPovinnéPopis
documentIdstringREQ

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 Dokument potvrdený
{
  "documentId": "48b703c6-6fbb-4cfa-90e3-736b1d6fa2ec",
  "status": "ACKNOWLEDGED",
  "acknowledgedDateTime": "2026-05-06T10:05:00.000Z"
}

Odpovede

  • 200Dokument potvrdený
  • 401Authentication error
  • 403Authorization error (missing scope or no access to the participant); a document of another receiver returns 404, not 403
  • 404Dokument neexistuje alebo patrí inému príjemcovi (SAPI-DOC-030 / SAPI-DOC-040)

Referencia

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

Cenník

Transparentné ceny bez skrytých poplatkov.

Sandbox

Testovacie prostredie pre integráciu (testovacie firmy z dev portálu).

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á

  • GET /document/receive, GET /document/receive/{id}200 / 60 s na kľúč (client_id); všetky tokeny z jedného kľúča majú spoločné počítadlo
  • POST /document/send, POST /document/receive/{id}/acknowledge150 / 60 s na kľúč (client_id); spoločné počítadlo s čítaním a s Enterprise API volaniami toho istého kľúča
  • POST /auth/token, /auth/renew, /auth/revoke10 / 60 s na IP adresu (token aj na dvojicu client_id a client_secret)
  • GET /auth/token/status60 / 60 s na IP adresu

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
401SAPI-AUTH-001Neplatné client_id alebo client_secret, prípadne demo kľúče na produkčnom hoste.
401SAPI-AUTH-002Access token expiroval. Získajte nový cez /auth/renew alebo /auth/token.
400SAPI-AUTH-002grant_type musí byť client_credentials.
401SAPI-AUTH-003Neplatný access token v hlavičke Authorization.
400SAPI-AUTH-003Chýba client_id.
400SAPI-AUTH-004Chýba client_secret alebo neplatný api_interface (token endpoint SAPI vydáva iba sapi).
403SAPI-AUTH-005Kľúč alebo produkčná zmluva nepovoľuje rozhranie SAPI.
423SAPI-AUTH-005retryableKlient je dočasne zablokovaný po opakovaných neúspešných prihláseniach.
403SAPI-AUTH-006Klient je deaktivovaný alebo token nemá požadovaný scope.
403SAPI-AUTH-007Požiadavka z IP adresy mimo povoleného zoznamu.
401SAPI-AUTH-008Chýba alebo je chybná hlavička Authorization (token status).
400SAPI-AUTH-008Reťazec scope je dlhší ako 512 znakov.
403SAPI-AUTH-008Požadovaný scope nie je povolený alebo ho kľúč už nemá.
401SAPI-AUTH-009Klient bol zrušený alebo už nie je aktívny.
400SAPI-AUTH-010Neplatné JSON telo alebo api_interface pri renew.
413SAPI-AUTH-010Telo požiadavky je príliš veľké.
400SAPI-AUTH-011Chýba refresh_token.
401SAPI-AUTH-012Neplatný alebo expirovaný refresh token. Prihláste sa znova cez /auth/token.
401SAPI-AUTH-013Refresh token bol zrušený.
400SAPI-AUTH-014Chýba token pri /auth/revoke.
401SAPI-AUTH-014Klient už nie je aktívny (renew).
403SAPI-AUTH-014Kľúč nemá oprávnenie pre firmu z X-Peppol-Participant-Id. Príčinu udáva details[0].issue: firm_not_available (firma nie je schválená alebo chýba aktívny API prístup), legacy_client_not_allowed, sapi_not_authorized (zmluva nepovoľuje SAPI), sapi_not_permitted (kľúč nemá zapnuté SAPI v Nastavenia → API), firm_outside_key_scope (participant nepatrí firme kľúča), integrator_not_authorized (participant nie je pridelený integrátorovi alebo chýba súhlas).
400SAPI-AUTH-015token_type_hint musí byť access_token alebo refresh_token.
401SAPI-AUTH-015Väzba klienta na firmu sa zmenila. Prihláste sa znova cez /auth/token.
401SAPI-AUTH-017Neplatný alebo expirovaný token.
401SAPI-AUTH-018Token bol zrušený.
503SAPI-AUTH-019retryableOverenie je dočasne nedostupné.
500SAPI-AUTH-099retryableInterná chyba pri vydaní alebo zrušení tokenu.
503SAPI-AUTH-099retryableZávislosť overenia je dočasne nedostupná.
400SAPI-VAL-001Telo požiadavky je neplatné. Opravte ho podľa špecifikácie endpointu a polí z details[].
400SAPI-VAL-002Chýba povinné pole, napríklad hlavička X-Peppol-Participant-Id.
404SAPI-VAL-003Požadovaný doklad sa nenašiel. Skontrolujte identifikátor dokladu a že patrí firme, pre ktorú ste autentifikovaní.
400SAPI-VAL-004X-Peppol-Participant-Id nie je platné Peppol ID (schéma:identifikátor), alebo ho nevieme priradiť firme. details[0].issue: participant_not_found (žiadna firma s týmto ID), participant_ambiguous (ID zodpovedá viacerým firmám), participant_mismatch (ID nepatrí firme tokenu).
400SAPI-DOC-001Chýba Idempotency-Key alebo nie je platné UUID.
400SAPI-DOC-002Neplatné JSON telo.
400SAPI-DOC-003Chýba objekt metadata.
400SAPI-DOC-004Chýbajú povinné polia v metadata.
400SAPI-DOC-005Chýba payload alebo je prázdny.
400SAPI-DOC-006payloadFormat musí byť "XML".
403SAPI-DOC-007senderParticipantId nesedí s firmou z tokenu a X-Peppol-Participant-Id.
400SAPI-DOC-008checksum musí byť neprázdny reťazec.
400SAPI-DOC-009Checksum nesedí s payloadom.
503SAPI-DOC-010retryablePayload sa nepodarilo uložiť, úložisko je dočasne nedostupné (details[0].issue storage_unavailable). Zopakujte rovnaký request s rovnakým Idempotency-Key po Retry-After.
503SAPI-DOC-011retryableZáznam dokladu sa nepodarilo vytvoriť alebo pripraviť odoslanie. details[0].issue: persistence_failed alebo tdd_in_flight (TDD predchádzajúceho pokusu sa ešte odosiela). Zopakujte rovnaký request s rovnakým Idempotency-Key po Retry-After.
502SAPI-DOC-012Prenos cez Peppol zlyhal alebo jeho výsledok treba dohľadať. providerDocumentId nájdete v details[]. Pri details[].issue = delivery_failed doklad doručený nebol (opakované pokusy počas približne 24 hodín zlyhali): pošlite nezmenené UBL XML a metadata s novým Idempotency-Key a pokus prevezme ten istý providerDocumentId. V ostatných prípadoch stav overte cez providerDocumentId a nový doklad neposielajte.
503SAPI-DOC-012retryableValidácia alebo vyhľadanie príjemcu v SMP je dočasne nedostupné. Po čase z hlavičky Retry-After zopakujte rovnaký request s rovnakým Idempotency-Key.
400SAPI-DOC-013receiverParticipantId nie je vo formáte schéma:identifikátor alebo je dlhšie ako 100 znakov (details[].issue too_long).
202SAPI-DOC-014Upozornenie v poli messages, nie chyba: príjemca nie je v sieti Peppol. Doklad je uložený, ale nedoručí sa. Po dodatočnej registrácii príjemcu pošlite to isté UBL XML znova s novým Idempotency-Key.
422SAPI-DOC-015UBL neprešiel validáciou (XSD, EN 16931, Peppol BIS) alebo príjemca daný typ dokladu neprijíma. Každá chyba v details[] má pravidlo (rule, napr. BR-CO-15 alebo PEPPOL-EN16931-R003), miesto v XML (location), text (issue) a slovenské vysvetlenie (message_sk).
413SAPI-DOC-016Pole payload je väčšie ako 22 MB alebo celé telo požiadavky väčšie ako 25 MB. details[].value uvádza veľkosť v bajtoch; väčšie prílohy priložte odkazom cac:ExternalReference.
400SAPI-DOC-017payloadEncoding: podporované je iba UTF-8.
409SAPI-DOC-018metadata.documentId už existuje pre odoslaný doklad tohto odosielateľa. Ak ho poznáme, details[] uvádza providerDocumentId pôvodného dokladu.
400SAPI-DOC-019Payload nie je platné XML.
400SAPI-DOC-020limit mimo povoleného rozsahu.
400SAPI-DOC-021status musí byť RECEIVED alebo ACKNOWLEDGED.
400SAPI-DOC-022Neplatný pageToken.
422SAPI-DOC-023metadata.documentTypeId nesedí s koreňovým elementom UBL.
409SAPI-DOC-024Rovnaké UBL XML už bolo odoslané. Nový Idempotency-Key ani documentId nový doklad nevytvorí. Výnimka: ak všetky predchádzajúce odoslania tohto UBL XML skončili v stave recipient_not_found (SAPI-DOC-014), opätovné odoslanie s novým Idempotency-Key prijmeme ako nový pokus a ePošťák nahlási opravu (TDD Resubmit). Je určené pre príjemcu, ktorý sa dodatočne zaregistroval v zákonnej 15-dňovej lehote; dodržanie lehoty API nekontroluje. details[] uvádza providerDocumentId pôvodného dokladu.
422SAPI-DOC-025EndpointID odosielateľa alebo príjemcu v UBL nesedí s metadata.
400SAPI-DOC-026metadata.documentId je dlhšie ako 255 znakov.
422SAPI-DOC-027Od 1. 1. 2027: IssueDate v UBL sa líši od dátumu odovzdania (Europe/Bratislava).
202SAPI-DOC-028Upozornenie v messages, nie chyba: dátum vystavenia je po zákonnej lehote (15 dní od dodania, pri súhrnnej faktúre od konca mesiaca). Faktúru odošleme, doručíme a nahlásime Finančnej správe. Do 31. 12. 2026 sa posudzuje cbc:IssueDate, od 1. 1. 2027 deň odovzdania.
422SAPI-DOC-029Ťarchopis (383) vyžaduje odkaz na predchádzajúcu faktúru (BT-25).
404SAPI-DOC-030Prijatý doklad neexistuje alebo nepatrí firme.
404SAPI-DOC-031Payload dokladu nie je dostupný.
503SAPI-DOC-031retryablePayload prijatého dokladu je dočasne nedostupný. Zopakujte neskôr.
500SAPI-DOC-032retryablePayload sa nepodarilo načítať.
409SAPI-DOC-033DPH obdobie pre dátum zdaniteľného plnenia už bolo podané. Dátum je v správe a v details[] (field payload, issue taxable_date).
422SAPI-DOC-034metadata.documentTypeId nie je typ dokladu, ktorý SAPI prijíma, alebo daný Peppol profil nie je zapnutý na odosielanie (details[].issue profile_disabled).
422SAPI-DOC-035UBL v poli payload sa nedá prečítať ako deklarovaný typ dokladu, takže nevieme overiť odosielateľa a príjemcu. Dôvod je v details[].message; skontrolujte koreňový element a metadata.documentTypeId.
422SAPI-DOC-036Hodnota v UBL sa nedá uložiť: suma presahuje 9 999 999 999,99 alebo údaj presahuje dĺžku poľa (details[].field, value). Nič sa neodoslalo; opravte UBL a použite nový Idempotency-Key.
404SAPI-DOC-040Doklad na potvrdenie (acknowledge) neexistuje.
500SAPI-DOC-041retryablePotvrdenie (acknowledge) zlyhalo.
422SAPI-DOC-042Odosielateľ a príjemca sú ten istý účastník. Nič sa neodoslalo.
500SAPI-DOC-099retryableInterná chyba.
500SAPI-PROC-001retryableOdoslanie dokladu zlyhalo kvôli internej chybe. Zopakujte s rovnakým Idempotency-Key; ak chyba pretrváva, kontaktujte podporu s request_id.
409SAPI-PROC-002Idempotency-Key už bol použitý s iným telom požiadavky.
409SAPI-PROC-003retryablePožiadavka s týmto Idempotency-Key sa ešte spracováva. Zopakujte o chvíľu.
429SAPI-PROC-004Prekročená kvóta odoslaných dokladov pre tarifu. Telo obsahuje plan, limit, current, fix_hint a upgrade_url; Retry-After udáva čas do obnovenia kvóty.
503SAPI-PROC-005retryableVýsledok predchádzajúceho odoslania sa ešte dohľadáva. Zopakujte neskôr.
500PEPPOL-PROC-001retryableOverenie firmy z hlavičky X-Peppol-Participant-Id zlyhalo kvôli internej chybe. Zopakujte neskôr.
500SAPI-PROC-001Rezervovaný kód SAPI-SK 1.0; ePošťák namiesto neho vracia konkrétnejší kód z tejto tabuľky.
503SAPI-TEMP-001Rezervovaný kód SAPI-SK 1.0; ePošťák namiesto neho vracia konkrétnejší kód z tejto tabuľky.
400SAPI-VAL-001Rezervovaný kód SAPI-SK 1.0; ePošťák namiesto neho vracia konkrétnejší kód z tejto tabuľky.
404SAPI-VAL-003Rezervovaný kód SAPI-SK 1.0; ePošťák namiesto neho vracia konkrétnejší kód z tejto tabuľky.
429RATE_LIMITEDretryablePrekročený rate limit (150 zápisov / 200 čítaní za minútu na kľúč).

Uchovávanie dát

Archív AS4 a dôkazov doručenia

Kompletné AS4 obálky uchovávame v nemennom archíve 12 mesiacov. Samostatný minimálny transportný dôkaz bez obsahu faktúry uchovávame 10 rokov. Historické obálky uložené so staršou desaťročnou lehotou zostávajú pod pôvodným zámkom. Ide o infraštruktúrnu retenciu nezávislú od plánu firmy.

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.

SAPI

Návody

Postupy odosielania a príjmu cez SAPI nad referenciou ôsmich volaní.

SAPI odosielanie

Odošlete hotový Peppol UBL 2.1 dokument cez SAPI a overíte jeho stav.

  • Platný token zo /sapi/v1/auth/token a oprávnenie konať za odosielajúcu firmu.
  • Dokument s kompletnými fakturačnými údajmi a Peppol BIS Billing profilom.
  • Na sledovanie outbound stavu potrebujete Enterprise API so scope documents:read; pri centrálnom sk_int_* kľúči aj X-Firm-Id odosielajúcej firmy.

Postup odoslania

  1. Získajte token

    POST /sapi/v1/auth/token. Priamy firemný prístup alebo kľúč so scopedFirmId je obmedzený na jednu firmu. Centrálny partnerský token môže obsluhovať oprávnené firmy výberom X-Peppol-Participant-Id.

  2. Odošlite dokument

    POST /sapi/v1/document/send s UBL 2.1 dokumentom. Príjemca musí byť dostupný participant v Peppol sieti.

  3. Overte stav a dôkaz

    SAPI nemá outbound status endpoint. providerDocumentId zo send odpovede overte cez Enterprise GET /api/v1/documents/{id}/status alebo /events so scope documents:read; úspešná HTTP odpoveď nie je potvrdenie doručenia.

Odoslanie UBL dokumentu
curl -X POST "https://epostak.sk/sapi/v1/document/send" \
  -H "Authorization: Bearer <SAPI_TOKEN>" \
  -H "Idempotency-Key: <UUID>" \
  -H "X-Peppol-Participant-Id: 0245:<SENDER_DIC>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "documentId": "INV-2026-001",
      "documentTypeId": "<PEPPOL_DOCUMENT_TYPE_ID>",
      "processId": "<PEPPOL_PROCESS_ID>",
      "senderParticipantId": "0245:<SENDER_DIC>",
      "receiverParticipantId": "0245:<RECEIVER_DIC>",
      "creationDateTime": "2026-09-20T10:00:00Z"
    },
    "payload": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>",
    "payloadFormat": "XML"
  }'

Čo si pri odoslaní strážiť

  • X-Peppol-Participant-Id nerozširuje oprávnenia tokenu. Centrálne partnerské prístupy vyžadujú platnú väzbu a súhlas pre vybranú firmu; firemne obmedzený kľúč nemožno použiť pre inú firmu.
  • Príjemca musí byť platný Peppol participant; neznámy participant nie je odložená doručiteľnosť.
  • Úspešná odpoveď znamená prijatie na spracovanie, nie doručenie príjemcovi.

Očakávaný výsledok a chyby

Dokument je prijatý na odoslanie. Ak máte Enterprise documents:read, providerDocumentId môžete sledovať cez status alebo events endpoint až po výsledok doručenia.

  • 401 alebo expirovaný token: obnovte token cez /sapi/v1/auth/renew.
  • Dokument neprejde: chýbajúce alebo neplatné fakturačné údaje, prípadne nesprávny profil dokumentu.
  • Príjemca nedostupný: overte, že ide o existujúceho participanta v Peppol sieti.

SAPI príjem

Prevezmete prijaté dokumenty cez SAPI a potvrdíte prevzatie po ich uložení.

  • Participant-scoped prístup s oprávnením na čítanie prijatých dokumentov.
  • Vlastné úložisko, do ktorého doklad uložíte pred potvrdením.

Postup prevzatia

  1. Zoznam prijatých dokumentov

    GET /sapi/v1/document/receive vráti dostupné dokumenty pre vášho participanta.

  2. Stiahnite konkrétny dokument

    GET /sapi/v1/document/receive/{documentId} prevezme dokument; uložte ho skôr, než pošlete potvrdenie.

  3. Potvrďte prevzatie

    POST /sapi/v1/document/receive/{documentId}/acknowledge až po úspešnom uložení. Potvrdenie nie je obchodná odpoveď.

Čo si pri príjme strážiť

  • Potvrdenie mení lokálny stav RECEIVED na ACKNOWLEDGED. Dokument zmizne zo zoznamu filtrovaného na RECEIVED, ale zostáva dostupný na stiahnutie; stav odosielateľa ani transportné potvrdenie nemení.
  • Opakovaný download spracujte idempotentne a doklad neukladajte dvakrát.
  • Prípadná obchodná odpoveď na faktúru je samostatný krok, nie podmienka technického prevzatia.

Očakávaný výsledok a chyby

Doklad je uložený vo vašom systéme a potvrdenie je odoslané až po uložení.

  • Ak ste potvrdili pred uložením, stiahnite dokument znovu cez jeho detail. Nájdete ho aj v zozname so status=ACKNOWLEDGED alebo bez filtra stavu; potvrdenie dokument nemaže.
  • Opakovaný download: spracujte ho idempotentne, ten istý doklad neukladajte dvakrát.