Enterprise API Core

SprievodcoviaEnterprise API: keď potrebujete riadiť každý krok

Enterprise API: keď potrebujete riadiť každý krok

Najkratší tok: token, overenie príjemcu, idempotentné odoslanie, čítanie udalostí a potvrdenie importu. Pokročilé endpointy a Enterprise Full otvorte až vtedy, keď ich konkrétne potrebujete.

Vyberte si integračný tok

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

Enterprise Core — začnite tu

Jeden päťkrokový tok od credentialu po bezpečne potvrdenú udalosť. Pokročilé možnosti sú o úroveň nižšie, nie v štartovacej ceste.

  1. Prvé odoslanie do 15 minútToken → preflight → idempotentný send → events pull → batch acknowledge po lokálnom commite.

Začať

Najkratšia cesta od sandbox tokenu po prvé bezpečné volanie.

  1. Získať API tokenAPI kľúč vymeníte za krátkodobý JWT. Enterprise podporuje firemný sk_live_* aj existujúci integrátorský sk_int_* flow; pri volaniach za klienta pridáva integrátor X-Firm-Id.
  2. Overiť príjemcuPred odoslaním zistite, či je firma v Peppole a ktoré typy dokumentov prijíma.

Odosielanie

Ako vytvoriť faktúru, poslať hotový UBL a sledovať výsledok.

  1. Vytvoriť faktúruPošlite údaje faktúry v JSON; ePošťák vytvorí, overí a odošle dokument.
  2. DPH režimy a zálohy v JSONHodnoty pre taxTreatment, vatCategoryCode, staršie sadzby DPH a zúčtované zálohy bez hádania UBL kódov.
  3. Poslať hotový UBL XMLAk už máte platný UBL, pošlite ho priamo; odosielateľa stále kontrolujeme voči autentifikovanej firme.
  4. Sledovať životný cyklus dokladuRozlišujte prijatie requestu, AS4 doručenie, Invoice Response a dôkazový archív.

Príjem a import

Ako čítať prijaté dokumenty, importovať mimo-Peppol UBL a rozhodnúť sa medzi pull a webhookmi.

  1. Prijímať dokumentyNajjednoduchší produkčný tok je pull API s cursorom: čítate nové dokumenty a voliteľne ich acknete po spracovaní.
  2. Importovať prijatý UBLPre email, SFTP alebo migráciu z iného AP uložte UBL do rovnakého inbound inboxu ako sieťové Peppol prijatia.
  3. Webhook fallback alebo Events pullWebhooky sú push signalizácia. Ak nemáte stabilný HTTPS receiver, použite Events pull alebo inbound/outbound pull API.

Bezpečnosť a Box

Čo sa berie z tokenu, čo sa mení pri odoslaní, čo je uložené šifrovane a ako funguje durable ePošťák Box.

  1. Bezpečnosť, identita a úložiskoSender identity je odvodená z autentifikovanej firmy, nie z request body. Citlivé technické secrets a Box payload objekty majú samostatné ochranné pravidlá.
  2. ePošťák Box workflowBox je durable vrstva nad Enterprise/Connector sendom: najprv bezpečne uloží payload, potom worker odosiela podľa plánu, limitov a retry pravidiel.
  3. Dôkazy a retenciaPo odoslaní sledujte UBL, AS4 envelope a evidence bundle oddelene od obchodného stavu faktúry.

Prevádzka

Ako riešiť retry, chyby a voľbu medzi Connectorom a plnou Enterprise API.

  1. Riešiť zlyhané odoslanieNajprv rozlíšte validáciu, recipient capability, transport a post-send DB stav.
  2. Enterprise reliability contractJeden stabilný runtime model: capability → preflight → send → events → support.
  3. Vybrať Connector alebo Enterprise APIConnector je riadený ERP tok. Enterprise API je step-level kontrola pre tímy, ktoré chcú skladať vlastný flow.

Enterprise Core golden path

Použite sandbox host a sandbox credential. Firemný sk_live_* JWT je už naviazaný na jednu firmu. Pri sk_int_* JWT pridajte X-Firm-Id schválenej firmy na prvý autentifikovaný Enterprise request a na každý ďalší firm-scoped Enterprise request. Connector customerRef je iný kontrakt a do týchto volaní nepatrí.

Postup

  1. 01Nastavte BASE_URL=https://dev.epostak.sk a credential v secret manageri.
  2. 02Mintnite JWT raz, cacheujte ho do expires_in a pri 401 obnovte token iba raz.
  3. 03Po prvom tokene vytvorte pre firmu raz pull-only subscription cez POST /webhooks s url=null. Bez nej events/pull nemá z čoho plniť queue.
  4. 04Preflight a send používajú rovnaký receiverPeppolId a firm context.
  5. 05Pri nejasnom výsledku send request neopakujte s novým kľúčom; opakujte rovnaký request s rovnakým Idempotency-Key.
  6. 06Events pull je asynchrónny; v DEV môže nová udalosť doraziť až pri nasledujúcom minútovom worker ticku. Pollujte s backoffom, nie tesnou slučkou.
  7. 07Eventy uložte a aplikujte v lokálnej transakcii. Až potom pošlite event_ids do batch-ack.

Endpoint

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

1. Token

client_secret zostáva iba na serveri. access_token cacheujte podľa expires_in.

curl
1curl -sS "$BASE_URL/api/v1/auth/token" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "grant_type": "client_credentials",
5    "client_id": "<key-id-or-prefix>",
6    "client_secret": "<secret>"
7  }'

1b. Jednorazové nastavenie pull queue

Spustite raz pre firmu po získaní tokenu. url=null vytvorí pull-only kanál; push webhook je samostatná subscription.

curl
1curl -sS "$BASE_URL/api/v1/webhooks" \
2  -H "Authorization: Bearer $ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": null,
6    "events": ["document.sent", "document.delivered", "document.received"]
7  }'

2. Preflight

Pri sk_int_* pridajte aj -H "X-Firm-Id: <firm-uuid>". Pri sk_live_* túto hlavičku neposielajte.

curl
1curl -sS "$BASE_URL/api/v1/documents/preflight" \
2  -H "Authorization: Bearer $ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"receiverPeppolId":"0245:2099999999"}'

3. Idempotentný JSON send

Pri retry ponechajte rovnaké telo aj Idempotency-Key.

curl
1curl -sS "$BASE_URL/api/v1/documents/send" \
2  -H "Authorization: Bearer $ACCESS_TOKEN" \
3  -H "Idempotency-Key: erp-fa-2026-0001-v1" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "receiverPeppolId": "0245:2099999999",
7    "receiverName": "Sandbox Receiver s.r.o.",
8    "invoiceNumber": "FA-2026-0001",
9    "currency": "EUR",
10    "items": [{
11      "description": "Implementačná služba",
12      "quantity": 1,
13      "unitPrice": 100,
14      "vatRate": 23
15    }]
16  }'

3b. Hotový UBL

Alternatíva k JSON sendu pre expert tím s hotovým Peppol BIS UBL.

json
1{
2  "receiverPeppolId": "0245:2099999999",
3  "xml": "<?xml version="1.0" encoding="UTF-8"?><Invoice>...</Invoice>"
4}

4. Pull udalostí

Táto Core queue je server-side ack fronta, nie cursor feed.

curl
1curl -sS "$BASE_URL/api/v1/events/pull" \
2  -H "Authorization: Bearer $ACCESS_TOKEN"

5. Batch acknowledge

Volajte až po úspešnom lokálnom commite. Pri páde pred ackom dostanete event znova.

curl
1curl -sS "$BASE_URL/api/v1/events/batch-ack" \
2  -H "Authorization: Bearer $ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"event_ids":["evt_01JZ..."]}'

Povinné polia

NázovTypPovinnéPopis
AuthorizationBearer JWTánoKrátkodobý token z /auth/token, nie raw API key.
X-Firm-Iduuid headerniePovinný na firm-scoped Enterprise volaniach iba pri sk_int_* integrátorskom JWT. Pri sk_live_* ho vynechajte.
Idempotency-Keystring headeránoStabilný pre jeden business send a všetky jeho retry pokusy.
requestIdresponse fieldnieUložte pri chybe alebo nejasnom stave pre support.

Práca so stavmi

2xx
Uložte documentId, event ID a requestId skôr, než pokračujete.
401
Obnovte JWT raz; raw API key nikdy neposielajte ako Bearer.
409
Pri idempotency konflikte neregenerujte kľúč; porovnajte pôvodný business request.
429/5xx
Retry s exponenciálnym backoffom, rovnakým telom a rovnakým Idempotency-Key.

Chyby

Wrong firm
sk_int_* bez X-Firm-Id alebo bez aktívneho consentu zlyhá; Connector customerRef sem nepridávajte.
Ack before commit
Predčasný ack môže skryť event, ktorý ERP ešte durable nespracovalo.

Ďalšie kroky

  • Pre inbound obsah pokračujte GET /api/v1/inbound/documents a lokálnym POST /inbound/documents/{id}/ack.
  • Pre expert možnosti otvorte Enterprise Full. Connector a SAPI majú vlastné technické rozhrania a dokumentáciu; zmluvu a platiteľa určuje zvolený obchodný režim, nie názov rozhrania.

Získať API token

API kľúč sk_live_* alebo sk_int_* nikdy neposielajte ako Bearer token priamo. Použite ho ako client_secret v OAuth client_credentials volaní, získajte krátkodobý JWT a ten cacheujte do expirácie. Pri Enterprise volaní s integrátorským JWT určíte schválenú spravovanú firmu cez X-Firm-Id; Connector namiesto toho používa customerRef.

Postup

  1. 01Vezmite client_id a client_secret z API kľúča.
  2. 02Zavolajte POST /api/v1/auth/token s grant_type client_credentials.
  3. 03Používajte access_token ako Authorization: Bearer.
  4. 04Refreshujte cez /api/v1/auth/renew alebo znovu mintnite token pred expiráciou.

Endpoint

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

Payload example

json
1{
2  "grant_type": "client_credentials",
3  "client_id": "sk_live_abc123",
4  "client_secret": "sk_live_abc123_plaintext_secret"
5}

Response

json
1{
2  "access_token": "eyJhbGciOiJSUzI1NiIs...",
3  "token_type": "Bearer",
4  "expires_in": 900,
5  "refresh_token": "rt_01JZ8...",
6  "scope": "documents:write documents:read webhooks:write"
7}

Povinné polia

NázovTypPovinnéPopis
grant_typestringánoPoužite client_credentials.
client_idstringánoPrefix alebo identifikátor API kľúča.
client_secretstringánoPlaintext sk_live_* alebo sk_int_* hodnota uložená vo vašom secret manageri.
X-Firm-IdheadernieNeposiela sa na token endpoint. Pri následných Enterprise firm-scoped volaniach je povinný pre sk_int_* integrátorský JWT; Connector ho nepoužíva.

Práca so stavmi

expires_in=900
Access token platí 15 minút; cacheujte ho.
refresh_token
Refresh token je one-shot a rotuje sa pri /auth/renew.
scopes
Scope-y určujú, ktoré Enterprise API volania môžete robiť.

Chyby

401 INVALID_CLIENT
client_id alebo client_secret nesedia, kľúč je vypnutý alebo používate demo kľúč na zlom hoste.
429 RATE_LIMITED
Token endpoint voláte príliš často; cacheujte access_token.

Ďalšie kroky

  • Pri sk_int_* Enterprise volaniach za klienta pridajte X-Firm-Id až na následné API requesty. Connector používa ten istý typ integrátorského JWT, ale firmu vyberá cez customerRef nastavené integrátorom pre schválenú firmu a X-Firm-Id neposiela.
  • Po získaní tokenu zavolajte /api/v1/auth/status ako lacný health check.

Overiť príjemcu

Pred odoslaním overte, či príjemca existuje v Peppol SMP a či prijíma presný typ dokladu, ktorý chcete poslať. Toto volanie je lacnejšie a čitateľnejšie ako čakať na chybu pri send-e.

Postup

  1. 01Rozdeľte Peppol ID na scheme a identifier.
  2. 02Pošlite documentType alebo documentTypes[] pre presné typy.
  3. 03Odosielajte až keď accepts alebo networkReady potvrdí správny typ.

Endpoint

POST/api/v1/peppol/capabilities
Vyskúšať

Payload example

json
1{
2  "participant": {
3    "scheme": "0245",
4    "identifier": "0000000001"
5  },
6  "documentTypes": [
7    "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",
8    "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
9  ]
10}

Response

json
1{
2  "found": true,
3  "accepts": true,
4  "participant": {
5    "scheme": "0245",
6    "identifier": "0000000001",
7    "id": "0245:0000000001"
8  },
9  "matchedDocumentTypes": [
10    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."
11  ],
12  "capabilities": [
13    {
14      "routingStatus": "ready",
15      "networkReady": true,
16      "accepts": true
17    }
18  ],
19  "source": "smp"
20}

Povinné polia

NázovTypPovinnéPopis
participant.schemestringánoŠtvormiestny ISO 6523 scheme, pre slovenské DIČ typicky 0245.
participant.identifierstringánoIdentifikátor bez prefixu scheme, napr. DIČ bez SK prefixu.
documentTypes[]string[]niePole 1 až 20 Peppol document-type URN hodnôt; má prednosť pred documentType.
processIdstringnieVoliteľný Peppol process ID, ak potrebujete rozlíšiť proces.

Práca so stavmi

found=true
Účastník existuje v SMP.
networkReady=true
Pre daný typ dokumentu existuje použiteľná routa.
accepts=false
Účastník existuje, ale neprijíma požadovaný document type.

Chyby

400 INVALID_PARAMS
Scheme, identifier alebo documentTypes[] majú neplatný tvar.
404 NOT_FOUND
Účastník nie je registrovaný v Peppol SMP.

Ďalšie kroky

  • Ak je route ready, pokračujte POST /api/v1/documents/send s rovnakým receiverPeppolId.
  • Ak prijíma iba iné typy, ukážte používateľovi presnú chybu namiesto retry odoslania.

Vytvoriť a odoslať faktúru

Tento postup ukazuje praktický outbound payload, nie iba hello-world. JSON režim vytvára štandardnú faktúru a ePošťák z nej skladá Peppol BIS 3.0 UBL. Pre self-billing pošlite hotový UBL s InvoiceTypeCode 389 cez pole xml; tým zachováte správne Peppol party role.

Postup

  1. 01Overte príjemcu cez capabilities, hlavne ak ho ešte nemáte v adresári.
  2. 02Pre štandardnú faktúru pošlite JSON payload na POST /api/v1/documents/send. Odosielateľ sa berie z autentifikovanej firmy, príjemcu a položky posielate v tele.
  3. 03Pre self-billing použite UBL XML mode: receiverPeppolId je dodávateľ, AccountingCustomerParty je vaša autentifikovaná firma a InvoiceTypeCode je 389.
  4. 04Uložte documentId/submissionId, messageId, status link a payloadSha256.
  5. 05Sledujte stav cez /status, Events pull alebo outbound events.

Endpoint

POST/api/v1/documents/send
Vyskúšať

Complete invoice payload

Toto je odporúčaná štruktúra pre ERP integráciu: posielajte split adresu, daňové identifikátory, platobné údaje, buyer reference, DPH kategóriu a prílohy ako base64. Polia odosielateľa neposielajte; berú sa z autentifikovanej firmy.

json
1{
2  "receiverPeppolId": "0245:0000000001",
3  "receiverName": "Zakaznik Demo s.r.o.",
4  "receiverIco": "12345678",
5  "receiverDic": "0000000001",
6  "receiverIcDph": "SK0000000001",
7  "receiverStreet": "Testovacia 1",
8  "receiverCity": "Bratislava",
9  "receiverPostalCode": "811 01",
10  "receiverCountry": "SK",
11  "invoiceNumber": "FA-2026-001",
12  "issueDate": "2026-07-01",
13  "dueDate": "2026-07-15",
14  "currency": "EUR",
15  "paymentMethod": "bank_transfer",
16  "iban": "SK9811000000000000000001",
17  "variableSymbol": "2026001",
18  "buyerReference": "PO-2026-0001",
19  "note": "Služby za obdobie jún 2026. Príloha: akceptačný protokol.",
20  "prepayments": [
21    {
22      "advanceInvoiceRef": "ZAL-2026-0004",
23      "taxDocumentRef": "DDP-2026-0022",
24      "settlementDate": "2026-02-23",
25      "amountWithoutVat": 1000,
26      "vatAmount": 230,
27      "amountWithVat": 1230,
28      "vatRate": 23
29    }
30  ],
31  "items": [
32    {
33      "description": "Implementačné práce",
34      "quantity": 16,
35      "unit": "HUR",
36      "unitPrice": 75,
37      "vatRate": 23,
38      "vatCategoryCode": "S",
39      "discount": 5,
40      "deliveryDate": "2026-06-30"
41    },
42    {
43      "description": "Servisná podpora",
44      "quantity": 1,
45      "unit": "C62",
46      "unitPrice": 240,
47      "vatRate": 23,
48      "vatCategoryCode": "S"
49    }
50  ],
51  "attachments": [
52    {
53      "fileName": "akceptacny-protokol.pdf",
54      "mimeType": "application/pdf",
55      "content": "JVBERi0xLjQKJc...",
56      "description": "Podpísaný akceptačný protokol"
57    }
58  ]
59}

Self-billing UBL payload

JSON line-item mode je pre štandardné faktúry. Pri self-billing pošlite UBL XML v poli xml spolu s receiverPeppolId. receiverPeppolId je dodávateľ, ktorému dokument posielate; AccountingCustomerParty je vaša firma ako kupujúci, ktorý self-billing vystavuje.

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>SB-2026-001</cbc:ID>
7  <cbc:IssueDate>2026-07-01</cbc:IssueDate>
8  <cbc:DueDate>2026-07-15</cbc:DueDate>
9  <cbc:InvoiceTypeCode>389</cbc:InvoiceTypeCode>
10  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
11  <cac:AccountingSupplierParty>
12    <cac:Party>
13      <cbc:EndpointID schemeID="0245">0000000001</cbc:EndpointID>
14      <cac:PartyName><cbc:Name>Dodavatel s.r.o.</cbc:Name></cac:PartyName>
15      <cac:PostalAddress>
16        <cbc:StreetName>Priemyselna 8</cbc:StreetName>
17        <cbc:CityName>Zilina</cbc:CityName>
18        <cbc:PostalZone>010 01</cbc:PostalZone>
19        <cac:Country><cbc:IdentificationCode>SK</cbc:IdentificationCode></cac:Country>
20      </cac:PostalAddress>
21      <cac:PartyTaxScheme>
22        <cbc:CompanyID>SK0000000001</cbc:CompanyID>
23        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
24      </cac:PartyTaxScheme>
25      <cac:PartyLegalEntity>
26        <cbc:RegistrationName>Dodavatel s.r.o.</cbc:RegistrationName>
27        <cbc:CompanyID>12345678</cbc:CompanyID>
28      </cac:PartyLegalEntity>
29    </cac:Party>
30  </cac:AccountingSupplierParty>
31  <cac:AccountingCustomerParty>
32    <cac:Party>
33      <cbc:EndpointID schemeID="0245">2122701339</cbc:EndpointID>
34      <cac:PartyName><cbc:Name>Moja Firma s.r.o.</cbc:Name></cac:PartyName>
35      <cac:PostalAddress>
36        <cbc:StreetName>Street 1</cbc:StreetName>
37        <cbc:CityName>Bratislava</cbc:CityName>
38        <cbc:PostalZone>811 01</cbc:PostalZone>
39        <cac:Country><cbc:IdentificationCode>SK</cbc:IdentificationCode></cac:Country>
40      </cac:PostalAddress>
41      <cac:PartyLegalEntity>
42        <cbc:RegistrationName>Moja Firma s.r.o.</cbc:RegistrationName>
43      </cac:PartyLegalEntity>
44    </cac:Party>
45  </cac:AccountingCustomerParty>
46  <cac:PaymentMeans>
47    <cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
48    <cbc:PaymentID>2026001</cbc:PaymentID>
49    <cac:PayeeFinancialAccount><cbc:ID>SK9811000000000000000001</cbc:ID></cac:PayeeFinancialAccount>
50  </cac:PaymentMeans>
51  <cac:TaxTotal>
52    <cbc:TaxAmount currencyID="EUR">230.00</cbc:TaxAmount>
53    <cac:TaxSubtotal>
54      <cbc:TaxableAmount currencyID="EUR">1000.00</cbc:TaxableAmount>
55      <cbc:TaxAmount currencyID="EUR">230.00</cbc:TaxAmount>
56      <cac:TaxCategory>
57        <cbc:ID>S</cbc:ID>
58        <cbc:Percent>23</cbc:Percent>
59        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
60      </cac:TaxCategory>
61    </cac:TaxSubtotal>
62  </cac:TaxTotal>
63  <cac:LegalMonetaryTotal>
64    <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
65    <cbc:TaxExclusiveAmount currencyID="EUR">1000.00</cbc:TaxExclusiveAmount>
66    <cbc:TaxInclusiveAmount currencyID="EUR">1230.00</cbc:TaxInclusiveAmount>
67    <cbc:PayableAmount currencyID="EUR">1230.00</cbc:PayableAmount>
68  </cac:LegalMonetaryTotal>
69  <cac:InvoiceLine>
70    <cbc:ID>1</cbc:ID>
71    <cbc:InvoicedQuantity unitCode="C62">1</cbc:InvoicedQuantity>
72    <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
73    <cac:Item>
74      <cbc:Name>Self-billed service</cbc:Name>
75      <cac:ClassifiedTaxCategory>
76        <cbc:ID>S</cbc:ID>
77        <cbc:Percent>23</cbc:Percent>
78        <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
79      </cac:ClassifiedTaxCategory>
80    </cac:Item>
81    <cac:Price><cbc:PriceAmount currencyID="EUR">1000.00</cbc:PriceAmount></cac:Price>
82  </cac:InvoiceLine>
83</Invoice>

Response

json
1{
2  "documentId": "clx9abc123",
3  "submissionId": "clx9abc123",
4  "messageId": "msg_peppol_xyz",
5  "status": "SENT",
6  "links": {
7    "document": "/api/v1/documents/clx9abc123",
8    "status": "/api/v1/documents/clx9abc123/status",
9    "events": "/api/v1/documents/clx9abc123/events",
10    "ubl": "/api/v1/documents/clx9abc123/ubl",
11    "evidenceBundle": "/api/v1/documents/clx9abc123/support-packet"
12  },
13  "payloadSha256": "a1b2c3d4e5f6..."
14}

Polia požiadavky

NázovTypPovinnéPopis
receiverPeppolIdstringniePeppol participant ID príjemcu vo formáte <code>scheme:identifier</code>, napr. <code>0245:2123456789</code>. Pri <code>invoice</code>/<code>credit_note</code> je to kupujúci. Pri self-billing môžete namiesto neho poslať <code>supplierPeppolId</code>.
itemsarrayánoPoložky faktúry. Povinné v JSON mode, 1 až 999 riadkov.
items[].descriptionstringánoNázov alebo popis položky. Nesmie byť prázdny.
items[].quantitynumberánoMnožstvo. Musí byť kladné číslo. Záporné množstvo je povolené iba pri <code>items[].lineType=advance_deduction</code> pre odpočet zálohy.
items[].unitPricenumberánoCena za jednotku bez DPH. Nesmie byť záporná.
items[].vatRatenumberánoSadzba DPH v %. Povolené: 0, 5, 10, 19, 20, 23; historická 20 % sadzba je podporovaná pre staršie doklady/opravné doklady.
items[].vatCategoryCodestringnieDPH kategória BT-151 podľa UNCL5305. Ak chýba, odvodíme ju zo sadzby: vatRate > 0 = S, vatRate 0 = Z. Pre prenesenie daňovej povinnosti pošlite AE. Najčastejšie: S = štandardná sadzba, Z = nulová sadzba, AE = prenesenie daňovej povinnosti.
items[].discountnumbernieZľava v percentách, 0 až 100.
items[].unitstringnieUN/ECE Rec 20 kód jednotky. Pre kus použite <code>H87</code>; <code>C62</code> znamená všeobecnú jednotku (one/unit). Ak kód chýba, použije sa <code>C62</code>. Runtime normalizuje aj aliasy: <code>ks→H87</code>, <code>hod→HUR</code>, <code>den→DAY</code>, <code>mes→MON</code>, <code>kg→KGM</code>, <code>m→MTR</code>, <code>l→LTR</code>, <code>km→KTM</code>.
items[].deliveryDatestringnieDátum dodania položky pre BT-134. Ak pošlete ISO timestamp, do UBL sa zapíše dátumová časť. Ak položkové dátumy použijete ako súhrnnú faktúru, musia byť v jednom kalendárnom mesiaci a issueDate musí byť najneskôr 15. deň po skončení tohto mesiaca.
items[].lineTypestringnieTyp riadku. Použite <code>advance_deduction</code> pre záporný odpočet zálohy na finálnej faktúre.
items[].advanceInvoiceReferencestringnieČíslo zálohovej faktúry. Povinné pri <code>lineType=advance_deduction</code>; do UBL sa zapíše ako <code>AdditionalItemProperty</code> s názvom <code>AdvanceInvoiceNumber</code>.
invoiceNumberstringnieČíslo faktúry. Ak chýba alebo je prázdne, vygeneruje sa z číselného radu firmy.
issueDatestringnieDátum vystavenia. Ak chýba, použije sa aktuálny deň v časovej zóne Europe/Bratislava. Zadaný dátum sa zachová a vstup sa neodmietne iba preto, že deň odovzdania je odlišný.
dueDatestringnieDátum splatnosti.
taxPointDatestringnieDátum vzniku daňovej povinnosti (BT-7) vo formáte YYYY-MM-DD.
deliveryDatestringnieSkutočný dátum dodania celého dokladu (BT-72) vo formáte YYYY-MM-DD.
documentDiscountPercentnumbernieCelková zľava dokladu v percentách od 0 do 100. Zapíše sa ako dokumentová zľava BG-20 a kombinuje sa s riadkovými zľavami.
currencystringnieISO 4217 mena. Ak chýba, použije sa default firmy alebo EUR.
prepaidAmountnumbernieSuma zaplatená vopred (BT-113). Do UBL sa zapíše ako <code>LegalMonetaryTotal/PrepaidAmount</code> a zníži <code>PayableAmount</code>. Nekombinujte s riadkom <code>advance_deduction</code>.
paymentMethodstringnieSpôsob platby. Podporované sú ePošťák aliasy <code>bank_transfer</code>, <code>credit_transfer</code>, <code>sepa</code>, <code>card</code>, <code>cash</code>, <code>direct_debit</code>, alebo priamo UNCL4461 kód, napr. <code>30</code>.
variableSymbolstringnieVariabilný symbol / payment reference.
buyerReferencestringnieReferencia kupujúceho, napr. číslo objednávky alebo interný nákupný odkaz.
notestringnieVoľný text poznámky na faktúre. Pri nulovej DPH alebo špecifickom daňovom režime uveďte dôvod/oslobodenie, ktoré má vidieť príjemca.
ibanstringnieIBAN pre platbu. Ak chýba, použije sa IBAN uložený pri firme, ak existuje.
receiverNamestringnieObchodné meno príjemcu. Pri <code>invoice</code>/<code>credit_note</code> je to kupujúci; pri self-billing môžete použiť alias <code>supplierName</code>.
receiverIcostringnieIČO príjemcu.
receiverDicstringnieDIČ príjemcu.
receiverIcDphstringnieIČ DPH príjemcu.
receiverStreetstringnieUlica a číslo príjemcu. Preferované pred parsovaním jedného poľa <code>receiverAddress</code>.
receiverCitystringnieMesto príjemcu.
receiverPostalCodestringniePSČ príjemcu.
receiverAddressstringnieJednoriadková adresa príjemcu. Použite ju, ak neviete poslať split polia <code>receiverStreet</code>, <code>receiverCity</code>, <code>receiverPostalCode</code>.
receiverCountrystringnieISO 3166-1 alpha-2 krajina príjemcu.
attachmentsarrayniePrílohy faktúry (Peppol BG-24) vložené ako base64 do UBL XML. Max 20 súborov, 10 MB na súbor a 15 MB spolu po base64 dekódovaní.
attachments[].fileNamestringánoNázov súboru prílohy. Nesmie byť prázdny.
attachments[].mimeTypestringánoPovolené MIME typy: application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.oasis.opendocument.spreadsheet. Obsah sa overuje magic-byte kontrolou.
attachments[].contentstringánoBase64-encoded obsah súboru bez <code>data:</code> prefixu.
xmlstringnieUBL XML mode — hotový UBL XML string ako alternatíva k JSON poliam vyššie. Posiela sa v JSON tele spolu s <code>receiverPeppolId</code>. Max 5 MB pre XML string. Použite ho pre typy dokladov alebo špecifiká, ktoré JSON mode nepokrýva.
Idempotency-KeyheadernieOdporucane pre retry. Rovnaky payload s rovnakym klucom vrati cache; iny payload s tym istym klucom vrati IDEMPOTENCY_KEY_MISMATCH.

Práca so stavmi

SENT
Payload prešiel validáciou a odoslanie bolo prijaté na spracovanie.
DELIVERED
AS4 doručenie bolo potvrdené access pointom príjemcu.
RESPONSE_RECEIVED
Príjemca poslal Invoice Response; spracujte AP/RE/PD/UQ ako obchodnú odpoveď.

Chyby

422 VALIDATION_ERROR
JSON alebo XML neprešlo vstupnou validáciou. Opravte payload a skúste znova.
422 RECIPIENT_NOT_REACHABLE
Príjemca nie je dostupný pre daný typ dokumentu. Nič sa neodoslalo ani nefakturuje.
503 VALIDATION_SERVICE_UNAVAILABLE
Dočasná chyba validačnej služby. Retryujte s rovnakým Idempotency-Key.

Ďalšie kroky

  • Pre audit stiahnite evidence bundle alebo UBL cez links v odpovedi.
  • Ak nechcete hostovať webhook receiver, použite Events pull alebo outbound events.
  • Pre ERP plug-and-play integráciu zvážte Connector; Enterprise API nechajte pre vlastný lifecycle flow.

DPH režimy a zúčtované zálohy

JSON režim má dve vrstvy daňového popisu. Buď pošlete priamo UBL kategóriu <code>vatCategoryCode</code>, alebo vyšší ePošťák alias <code>taxTreatment</code>, ktorý sa na UBL kategóriu namapuje. Pri finálnej faktúre so zúčtovanou zálohou použite <code>prepayments[]</code>; finančný efekt je <code>PrepaidAmount</code>, nie záporný riadok.

Postup

  1. 01<code>standard</code> → <code>S</code>: bežná kladná sadzba DPH, napr. 23 %, 20 %, 10 % alebo 5 % podľa dokladu.
  2. 02<code>zero_rate</code> → <code>Z</code>: bežná nulová sadzba; použite <code>vatRate=0</code>.
  3. 03<code>reverse_charge_domestic</code> → <code>AE</code>: prenesenie daňovej povinnosti; použite <code>vatRate=0</code> a dôvod uveďte aj v poznámke, ak ho má vidieť príjemca.
  4. 04<code>exempt</code> → <code>E</code>, <code>intra_community_supply</code> → <code>K</code>, <code>export</code> → <code>G</code>, <code>outside_scope</code> → <code>O</code>. Ak potrebujete zriedkavejší UBL kód, pošlite priamo <code>vatCategoryCode</code>.
  5. 05Historická 20 % sadzba je povolená vo <code>vatRate</code> pre staršie alebo opravné doklady. Pri oprave nesprávnej sadzby DPH zvyčajne posielajte dobropis/storno pôvodného dokladu a nový doklad so správnou sadzbou.
  6. 06<code>prepayments[].amountWithVat</code> je povinné a spočítava sa do <code>prepaidAmount</code>. <code>advanceInvoiceRef</code>, <code>taxDocumentRef</code>, <code>settlementDate</code> a sadzba DPH sa zachovajú v poznámke UBL dokladu.
  7. 07Rozpad jednej zálohy podľa viacerých sadzieb zatiaľ nevytvára samostatný UBL daňový rozpad; daňové medzisúčty sa skladajú z položiek faktúry. Ak potrebujete zachovať rozpad 0 % / 23 %, pošlite ho ako viac <code>prepayments[]</code> záznamov s rovnakou referenciou alebo ho doplňte do <code>note</code>.

Endpoint

POST/api/v1/documents/send
Vyskúšať

Mix DPH režimov a zúčtovanej zálohy

Príklad finálnej faktúry s bežnou 23 % položkou, prenesením daňovej povinnosti a jednou zúčtovanou zálohou. Hodnoty sú syntetické.

json
1{
2  "receiverPeppolId": "0245:0000000001",
3  "receiverName": "Zakaznik s.r.o.",
4  "invoiceNumber": "FA-2026-1042",
5  "issueDate": "2026-07-09",
6  "dueDate": "2026-07-09",
7  "currency": "EUR",
8  "buyerReference": "PO-2026-603",
9  "note": "Prenesenie daňovej povinnosti podľa §69 ods. 12 zákona o DPH. Záloha ZAL-2026-0004 zúčtovaná na finálnej faktúre.",
10  "prepayments": [
11    {
12      "advanceInvoiceRef": "ZAL-2026-0004",
13      "taxDocumentRef": "DDP-2026-0022",
14      "settlementDate": "2026-02-23",
15      "amountWithoutVat": 1000,
16      "vatAmount": 230,
17      "amountWithVat": 1230,
18      "vatRate": 23,
19      "vatCategoryCode": "S"
20    }
21  ],
22  "items": [
23    {
24      "description": "Dodanie tovaru",
25      "quantity": 10,
26      "unit": "C62",
27      "unitPrice": 100,
28      "vatRate": 23,
29      "taxTreatment": "standard"
30    },
31    {
32      "description": "Tuzemské prenesenie daňovej povinnosti",
33      "quantity": 1,
34      "unit": "C62",
35      "unitPrice": 400,
36      "vatRate": 0,
37      "taxTreatment": "reverse_charge_domestic"
38    }
39  ]
40}

Najdôležitejšie polia

NázovTypPovinnéPopis
items[].taxTreatmentstringnieBusiness alias pre DPH režim: standard, zero_rate, reverse_charge_domestic, exempt, intra_community_supply, export, outside_scope.
items[].vatCategoryCodestringniePriamy UBL kód BT-151. Má prednosť pred taxTreatment.
items[].vatRatenumberánoSadzba v percentách. Pre AE/Z/E/K/G/O použite 0; pre staršie alebo opravné doklady je povolená aj 20 % sadzba.
prepayments[].amountWithVatnumberánoZúčtovaná suma vrátane DPH; spočítava sa do BT-113 PrepaidAmount.
prepayments[].vatRatenumbernieSadzba DPH zúčtovanej zálohy, ak ju ERP vie poslať; zapíše sa do poznámky k zálohe.
notestringnieVoľný text pre dôvod nulovej DPH, prenesenia daňovej povinnosti alebo detailný rozpad zálohy, ktorý má vidieť príjemca.

Poslať hotový UBL XML

Ak váš ERP už generuje Peppol BIS Billing 3.0 UBL, nemusíte ho mapovať späť do JSON line-item payloadu. Pošlite JSON telo s poľom xml; ePošťák ho overí, skontroluje party voči autentifikovanej firme a odošle cez AS4.

Postup

  1. 01Vygenerujte UBL Invoice alebo CreditNote v Peppol BIS Billing 3.0.
  2. 02Pošlite { receiverPeppolId, xml } na /documents/send s Idempotency-Key.
  3. 03Uložte documentId, messageId, links a payloadSha256.

Endpoint

POST/api/v1/documents/send
Vyskúšať

Payload example

Toto je UBL hodnota pre pole xml v JSON requeste. receiverPeppolId posielajte vedľa nej v tom istom JSON tele.

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>FA-2026-001</cbc:ID>
7  <cbc:IssueDate>2026-07-01</cbc:IssueDate>
8  <cac:AccountingSupplierParty>...</cac:AccountingSupplierParty>
9  <cac:AccountingCustomerParty>
10    <cac:Party>
11      <cbc:EndpointID schemeID="0245">0000000001</cbc:EndpointID>
12    </cac:Party>
13  </cac:AccountingCustomerParty>
14  <cac:InvoiceLine>...</cac:InvoiceLine>
15</Invoice>

Response

json
1{
2  "documentId": "clx9ubl123",
3  "messageId": "msg_peppol_ubl_xyz",
4  "status": "SENT",
5  "links": {
6    "status": "/api/v1/documents/clx9ubl123/status",
7    "ubl": "/api/v1/documents/clx9ubl123/ubl",
8    "supportPacket": "/api/v1/documents/clx9ubl123/support-packet"
9  },
10  "payloadSha256": "b4c5d6..."
11}

Povinné polia

NázovTypPovinnéPopis
Content-Typeheaderánoapplication/json. UBL XML posielajte ako string v poli xml.
Invoice/CreditNoteXMLánoUBL 2.1 doklad kompatibilný s Peppol BIS Billing 3.0.
AccountingSupplierPartyXML nodeánoPri štandardnej faktúre musí zodpovedať autentifikovanej firme: buď firme viazanej na sk_live_* JWT, alebo firme vybranej cez X-Firm-Id pri sk_int_* JWT. Pri self-billing je to dodávateľ, ktorému dokument posielate.
AccountingCustomerParty/EndpointIDXML nodeánoPri štandardnej faktúre Peppol ID príjemcu. Pri self-billing musí zodpovedať autentifikovanej firme ako kupujúcemu.

Práca so stavmi

SENT
UBL prešiel validáciou a bol odoslaný alebo prijatý na odoslanie.
SENT_DB_PENDING
Transport prebehol, lokálny stav sa dorovná reconciliation workerom.

Chyby

422 UBL_VALIDATION_ERROR
XML je dobre formované, ale porušuje Peppol/CEN pravidlo.
403 SENDER_MISMATCH
Party, ktorá má patriť autentifikovanej firme, sa nezhoduje. Pri štandardnej faktúre je to supplier; pri self-billing customer.

Ďalšie kroky

  • Pre preflight bez odoslania použite POST /api/v1/payloads/validate.
  • Ak migrujete hotové UBL prijaté mimo Peppolu, použite inbound import, nie outbound send.

Sledovať životný cyklus dokladu

Odpoveď zo send endpointu znamená, že request bol prijatý a odosielanie prebehlo alebo beží. Pre účtovný a supportný stav sledujte samostatne technický transport, business odpoveď príjemcu a dôkazový archív.

Postup

  1. 01Pollujte /documents/{id}/status pre aktuálny stav.
  2. 02Použite /outbound/events pre cursor stream udalostí.
  3. 03Pre audit stiahnite UBL, AS4 envelope alebo evidence bundle.

Endpoint

GET/api/v1/documents/{id}/status
Vyskúšať

Payload example

curl
1curl https://epostak.sk/api/v1/documents/clx9abc123/status \
2  -H "Authorization: Bearer eyJhbGc..."

Response

json
1{
2  "documentId": "clx9abc123",
3  "status": "DELIVERED",
4  "messageId": "msg_peppol_xyz",
5  "sentAt": "2026-07-01T09:02:11.000Z",
6  "deliveredAt": "2026-07-01T09:02:18.000Z",
7  "invoiceResponseStatus": "AP",
8  "links": {
9    "events": "/api/v1/documents/clx9abc123/events",
10    "evidenceBundle": "/api/v1/documents/clx9abc123/support-packet"
11  }
12}

Povinné polia

NázovTypPovinnéPopis
idstringánodocumentId alebo submissionId zo send odpovede.
cursorstringniePri event streame cursor z predchádzajúcej odpovede.

Práca so stavmi

SENT
Doklad bol odoslaný na Peppol transport alebo je prijatý na odoslanie.
DELIVERED
Access point príjemcu potvrdil doručenie.
REJECTED
Príjemca alebo validačná vrstva odmietla doklad.

Chyby

404 NOT_FOUND
Doklad neexistuje, patrí inej firme alebo ešte nie je v danej projekcii.
409 PENDING
Niektoré dôkazové artefakty môžu vzniknúť až pár minút po transporte.

Ďalšie kroky

  • Pre customer support ukladajte messageId a event IDs spolu s vaším externalId.
  • Invoice Response AP/RE/PD/UQ spracujte ako obchodný stav, nie ako transportný stav.

Prijímať dokumenty

Najspoľahlivejší produkčný príjem je cursor-based pull API. ERP pravidelne číta nové dokumenty, ukladá next_cursor a po spracovaní môže dokument explicitne acknúť.

Postup

  1. 01Pollujte /inbound/documents s limitom.
  2. 02Spracujte metadata a stiahnite raw UBL podľa links.ubl.
  3. 03Ak potrebujete checkpoint, zavolajte ack až po úspešnom importe.

Endpoint

GET/api/v1/inbound/documents
Vyskúšať

Payload example

curl
1curl "https://epostak.sk/api/v1/inbound/documents?limit=50" \
2  -H "Authorization: Bearer <firm_access_token>"

Response

json
1{
2  "items": [
3    {
4      "id": "inb_01JZ8...",
5      "direction": "inbound",
6      "documentType": "invoice",
7      "senderPeppolId": "0208:987654321",
8      "receiverPeppolId": "0245:0000000001",
9      "receivedAt": "2026-07-01T09:15:30.000Z",
10      "links": {
11        "document": "/api/v1/inbound/documents/inb_01JZ8...",
12        "ubl": "/api/v1/inbound/documents/inb_01JZ8.../ubl",
13        "ack": "/api/v1/inbound/documents/inb_01JZ8.../ack"
14      }
15    }
16  ],
17  "next_cursor": "eyJpZCI6ImluYl8wMU..."
18}

Povinné polia

NázovTypPovinnéPopis
cursorstringnieCursor z predchádzajúcej odpovede next_cursor.
limitintegernieMax počet dokumentov na stránku; držte stabilnú hodnotu pri pollingu.

Práca so stavmi

received
Dokument je uložený a pripravený na čítanie.
acknowledged
Vaša integrácia potvrdila, že dokument spracovala.

Chyby

401 UNAUTHORIZED
Token chýba alebo expiroval.
403 FORBIDDEN
Token nemá potrebný scope, firma nie je API-eligible alebo sk_int_* integrátor nemá aktívny súhlas k firme z X-Firm-Id.

Ďalšie kroky

  • Pre surový XML payload použite links.ubl a parsujte prílohy z UBL.
  • Ak nechcete polling dokumentov, webhook nechajte iba ako signál a dokument stále čítajte cez inbound API.

Importovať prijatý UBL

Tento endpoint používajte, keď máte prijatý UBL mimo Peppol siete — napríklad z emailu, SFTP, manuálnej migrácie alebo z predchádzajúceho access pointu — a chcete ho dostať do rovnakého inboxu ako sieťové prijatia.

Postup

  1. 01Pošlite raw XML alebo JSON s xml.
  2. 02Skontrolujeme receiver identity proti firme.
  3. 03Dostanete rovnaké links ako pri Peppol inbound dokumente.

Endpoint

POST/api/v1/inbound/import
Vyskúšať

Payload example

json
1{
2  "source": "email",
3  "messageId": "mail-2026-07-01-001",
4  "xml": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>"
5}

Response

json
1{
2	  "documentId": "inb_import_01JZ8...",
3	  "submissionId": "inb_import_01JZ8...",
4	  "status": "RECEIVED",
5	  "kind": "invoice",
6	  "source": "api_import",
7	  "links": {
8	    "document": "/api/v1/inbound/documents/inb_import_01JZ8...",
9	    "ubl": "/api/v1/inbound/documents/inb_import_01JZ8.../ubl",
10    "ack": "/api/v1/inbound/documents/inb_import_01JZ8.../ack"
11  }
12}

Povinné polia

NázovTypPovinnéPopis
xmlstringánoUBL XML payload, raw body alebo JSON pole xml.
sourcestringniePôvod importu, napr. email, sftp alebo migration.
messageIdstringnieExterný audit identifikátor z pôvodného kanála. Dedup/retry kontrakt používa Idempotency-Key.

Práca so stavmi

RECEIVED
UBL bol uložený do inbound schránky a správa sa ako sieťovo prijatý dokument.
duplicate: true
Rovnaký Idempotency-Key s rovnakým XML a metadátami vráti pôvodný dokument bez nového uploadu.

Chyby

422 RECEIVER_MISMATCH
Receiver party nepatrí firme, v mene ktorej importujete: pri štandardnej faktúre AccountingCustomerParty, pri self-billing AccountingSupplierParty.
422 INVALID_UBL
XML nie je čitateľný UBL doklad.

Ďalšie kroky

  • Po importe spracujte dokument rovnakým kódom ako sieťové inbound dokumenty.
  • Ak chcete len parsovať UBL bez uloženia, použite parse endpoint, nie import.

Webhook fallback alebo Events pull

Webhooky používajte ako real-time signál. Ak klient nemá stabilný verejný HTTPS receiver, vytvorte pull subscription a čítajte eventy cez GET /api/v1/events/pull. Pre samotné dokumenty je stále najspoľahlivejšie čítať inbound/outbound pull API.

Postup

  1. 01Pre push nastavte URL a overujte HMAC podpis.
  2. 02Pre pull fallback vytvorte subscription bez URL a čítajte Events pull.
  3. 03Po evente čítajte dokument cez document links alebo pull API.

Endpoint

POST/api/v1/webhooks
Vyskúšať

Payload example

json
1{
2  "url": null,
3  "events": [
4    "document.sent",
5    "document.received",
6    "document.delivered",
7    "document.delivery_failed",
8    "document.response_received"
9  ]
10}

Response

json
1{
2  "id": "whk_01JZ8...",
3  "mode": "pull",
4  "events": [
5    "document.received",
6    "document.response_received"
7  ],
8  "secretPreview": "whsec_...last4",
9  "status": "active"
10}

Povinné polia

NázovTypPovinnéPopis
urlstring | nullnieVerejný HTTPS receiver pre push; null pre Events pull.
events[]string[]ánoTypy udalostí, napr. document.received alebo document.response_received.
X-Webhook-SignatureheaderánoHMAC podpis prijatého push webhooku.

Práca so stavmi

active
Subscription prijíma alebo frontuje udalosti.
failedAttempts
Po terminálnych zlyhaniach sa counter zvyšuje; úspech ho znižuje.
auto-disabled
Po opakovaných terminálnych chybách sa push subscription vypne.

Chyby

400 INVALID_URL
URL nie je verejný HTTPS endpoint alebo narazila na SSRF guard.
410 GONE
Receiver signalizuje trvalé vypnutie; retry sa nerobí.

Ďalšie kroky

  • Webhook receiver musí byť idempotentný podľa webhook_event_id.
  • Pri push používajte 503 pre transient chyby; 500 považujeme za terminálny stav.
  • Ak potrebujete dokument, použite event iba ako signál a následne čítajte pull API.

Bezpečnosť, identita a úložisko

Tento postup vysvetľuje hranice Enterprise API: ktoré hodnoty môže poslať vaša integrácia, ktoré hodnoty ePošťák odvodzuje z autentifikácie a ktoré citlivé objekty chránime šifrovaným uložením alebo jednosmerným hashom.

Postup

  1. 01Pre Enterprise vymeňte firemný sk_live_* alebo integrátorský sk_int_* za JWT cez /auth/token; API secret neposielajte ako Bearer token.
  2. 02Pri sk_int_* Enterprise volaniach pošlite X-Firm-Id schválenej spravovanej firmy; server vždy znovu overí väzbu, consent scopes a plan eligibility. Pri sk_live_* JWT X-Firm-Id neposielajte. Connector používa customerRef namiesto X-Firm-Id.
  3. 03Pri JSON invoice mode sa odosielateľské údaje nesmú brať z request body; UBL sa skladá s firmou z autentifikácie.
  4. 04Pri raw UBL mode kontrolujeme party role: štandardná faktúra vyžaduje authenticated supplier, self-billing vyžaduje authenticated customer.
  5. 05Box ukladá dokumentový payload šifrovane a v zoznamoch/detailoch vystavuje iba operačné metadata ako status, payloadSha256, veľkosť, retenciu a odkazy na akcie.

Endpoint

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

Identity boundary example

Toto nie je API požiadavka. Ukazuje, čo môže poslať ERP a čo ePošťák berie zo server-side identity.

json
1{
2  "requestBodyMaySet": [
3    "receiverPeppolId",
4    "receiverName",
5    "invoiceNumber",
6    "items",
7    "attachments"
8  ],
9  "derivedFromAuthContext": {
10    "firmId": "firm-scoped JWT subject",
11    "senderPeppolId": "registered firm Peppol participant",
12    "senderName": "firm legal name",
13    "senderTaxIds": "firm registry data"
14  },
15  "rawUblPartyGuard": {
16    "standardInvoice": "AccountingSupplierParty must match authenticated firm",
17    "selfBillingInvoiceTypeCode389": "AccountingCustomerParty must match authenticated firm"
18  }
19}

Protected storage surfaces

Box detail a webhook správa zámerne vracajú bezpečné metadata namiesto plaintextu.

json
1{
2  "boxPayload": {
3    "stored": "encrypted at rest",
4    "publicDetail": [
5      "status",
6      "storageBytes",
7      "payloadSha256",
8      "retention",
9      "action links"
10    ],
11    "notReturnedInListOrDetail": [
12      "raw UBL body",
13      "attachments",
14      "plain storage location"
15    ]
16  },
17  "webhookSigningSecret": {
18    "returned": "once on create or rotate",
19    "stored": "encrypted at rest",
20    "verification": "HMAC-SHA256 over timestamp + body"
21  }
22}

Bezpečnostné pravidlá

NázovTypPovinnéPopis
AuthorizationheaderánoKrátkodobý Bearer JWT z /api/v1/auth/token.
X-Firm-IdheaderniePovinné pri Enterprise firm-scoped volaniach s integrátorským sk_int_* JWT; pri sk_live_* JWT a Connector endpointoch sa neposiela.
sender identityderivedánoOdvodená z autentifikovanej firmy. JSON payload nemá právo prepísať odosielateľa.
payloadSha256sha256nieHash uloženého UBL/payload objektu pre dedup, support a audit bez odhaľovania obsahu.
webhook secretsecretnieVracia sa iba raz pri vytvorení alebo rotácii webhooku; v ePošťákovi sa ukladá šifrovane.

Práca so stavmi

scoped
Volanie je naviazané na jednu autorizovanú firmu zo sk_live_* tokenu alebo z overeného sk_int_* + X-Firm-Id kontextu.
redacted
Detailné API vracia hash a bezpečné metadata, nie plaintext payload.
returned once
Webhook secret sa po vytvorení nedá spätne prečítať; pri strate ho rotujte.

Chyby

403 SENDER_MISMATCH
UBL party, ktorá má patriť autentifikovanej firme, sa nezhoduje.
403 FORBIDDEN
Token nemá scope alebo firm access pre požadovanú firmu.
422 INVALID_URL
Webhook URL narazila na HTTPS/SSRF pravidlá.

Ďalšie kroky

  • Pri vlastnom ERP UI zobrazujte používateľovi firmu z auth contextu, nie odosielateľa z lokálneho draftu.
  • Do supportu posielajte requestId, documentId, messageId a payloadSha256; neposielajte API secrets ani celý UBL, ak stačí hash.

ePošťák Box workflow

Box používajte, keď ERP nechce riskovať nejasný stav medzi uložením faktúry a odoslaním do Peppolu. Položka vznikne ako durable záznam, má vlastné storage metadata, audit timeline, plán odoslania a retry/cancel/send-now akcie.

Postup

  1. 01POST /api/v1/box/items je Enterprise skratka nad stagingom; Connector /outbox používa rovnakú Box vrstvu pre ERP-first flow.
  2. 02Každá položka dostane boxItemId, status, payloadSha256, retention a links na ďalšie akcie.
  3. 03Detail vracia bezpečný storage summary a timeline, nie raw UBL alebo plaintext object key.
  4. 04Ready/scheduled položku odošlite workerom alebo send-now. Failed alebo needs_repair položku opravte a odošlite znovu; neodoslanú položku môžete zrušiť.

Endpoint

POST/api/v1/box/items
Vyskúšať

Stage payload

Toto je single-item Box staging. Pri Connector batch outboxe použite rovnakú položku vo vnútri items[].

json
1{
2  "externalId": "ERP-FA-2026-001",
3  "scheduledFor": "2026-07-01T08:00:00.000Z",
4  "idempotencyKey": "erp-fa-2026-001:v1",
5  "payload": {
6    "receiverPeppolId": "0245:0000000001",
7    "receiverName": "Zakaznik s.r.o.",
8    "invoiceNumber": "FA-2026-001",
9    "items": [
10      {
11        "description": "Servisna podpora",
12        "quantity": 1,
13        "unitPrice": 240,
14        "vatRate": 23
15      }
16    ]
17  }
18}

Stage response

Box list a detail držia operačné metadata. Plaintext dokument čítajte iba cez autorizované dokumentové endpointy alebo evidence flow.

json
1{
2  "total": 1,
3  "ready": 1,
4  "items": [
5    {
6      "boxItemId": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
7      "status": "scheduled",
8      "source": "connector_outbox",
9      "documentId": null,
10      "payloadSha256": "2f5c1d9a9e...",
11      "storageBytes": 8421,
12      "retention": {
13        "expiresAt": "2036-07-01T00:00:00.000Z",
14        "reason": "billing_evidence"
15      },
16      "links": {
17        "self": "/api/v1/box/items/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
18        "sendNow": "/api/v1/box/items/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/send-now",
19        "retry": "/api/v1/box/items/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/retry",
20        "cancel": "/api/v1/box/items/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/cancel"
21      }
22    }
23  ]
24}

Detail storage summary

Detail potvrdí, že payload existuje, je chránený a má auditovateľný hash. Dokumentový obsah sa z Box detailu nesťahuje.

json
1{
2  "boxItemId": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
3  "storage": {
4    "objects": [
5      {
6        "purpose": "canonical_ubl",
7        "objectKeyHash": "sha256:6c7a...",
8        "contentType": "application/xml",
9        "sizeBytes": 8421,
10        "payloadSha256": "2f5c1d9a9e...",
11        "encryption": {
12          "algorithm": "AES-256-GCM"
13        }
14      }
15    ]
16  },
17  "timeline": [
18    {
19      "type": "audit",
20      "event": "epostak_box.outbound.ready",
21      "actorType": "system",
22      "occurredAt": "2026-07-01T07:55:01.000Z"
23    }
24  ]
25}

Polia Box položky

NázovTypPovinnéPopis
payloadobjectnieRovnaký send payload ako pri /documents/send; ak chýba, použije sa koreňové telo.
externalIdstringnieERP korelačný identifikátor pre dedup a spätné mapovanie.
scheduledFordatetimenieBudúci ISO 8601 čas plánovaného odoslania.
idempotencyKeystringnieIdempotentné zaradenie tej istej položky.
payloadSha256responsenieHash uloženého payload objektu, vhodný pre audit a support.

Práca so stavmi

ready
Položka je pripravená na odoslanie.
scheduled
Worker ju odošle po scheduledFor a podľa tenant/rate limitov.
needs_repair
Preflight alebo mapping našiel blokujúci problém; opravte dáta a skúste odoslanie znovu.
failed
Transport alebo spracovanie zlyhalo; pozrite lastError a timeline.

Chyby

409 DISPATCH_POINTER_UNAVAILABLE
send-now nemá Connector/Enterprise pointer; použite detail a repair flow.
422 INVALID_SCHEDULE
scheduledFor musí byť budúci ISO čas.

Ďalšie kroky

  • Pre veľké ERP importy používajte batch Connector outbox a nechajte worker dávkovať odosielanie.
  • Pre audit ukladajte boxItemId, externalId a payloadSha256 vedľa vášho interného ID faktúry.

Dôkazy a retencia

Dôkazový tok nie je to isté ako obchodný stav faktúry. Transport môže byť doručený, Invoice Response môže prísť neskôr a ZIP evidence bundle môže byť pripravený až po vytvorení technických artefaktov.

Postup

  1. 01Po send-e uložte documentId/submissionId, Peppol messageId a payloadSha256.
  2. 02Pollujte status alebo outbound events, kým transport a evidence state nedávajú očakávaný výsledok.
  3. 03Evidence bundle sťahujte cez autorizovaný endpoint; pri 409/PENDING skúste neskôr.

Endpoint

GET/api/v1/documents/{id}/status
Vyskúšať

Download evidence bundle

curl
1curl -L "https://epostak.sk/api/v1/documents/clx9abc123/support-packet" \
2  -H "Authorization: Bearer eyJhbGc..." \
3  -o evidence-clx9abc123.zip

Evidence state response

json
1{
2  "documentId": "clx9abc123",
3  "status": "DELIVERED",
4  "messageId": "msg_peppol_xyz",
5  "payloadSha256": "b4c5d6...",
6  "evidence": {
7    "bundleReady": true,
8    "transportReceipt": "available",
9    "as4Envelope": "available"
10  },
11  "links": {
12    "ubl": "/api/v1/documents/clx9abc123/ubl",
13    "evidence": "/api/v1/documents/clx9abc123/evidence",
14    "evidenceBundle": "/api/v1/documents/clx9abc123/support-packet"
15  }
16}

Povinné polia

NázovTypPovinnéPopis
documentIdstringánoID z odpovede send/status alebo Connector detailu.
messageIdstringniePeppol korelácia na transportnej vrstve.
payloadSha256stringnieHash payloadu, ktorý v supporte pomáha bez posielania celého XML.

Práca so stavmi

bundleReady
ZIP s dostupnými technickými artefaktmi je pripravený na stiahnutie.
PENDING
Niektoré artefakty sa ešte vytvárajú; skúste požiadavku zopakovať neskôr.

Chyby

404 NOT_FOUND
Doklad nepatrí firme alebo evidence endpoint preň zatiaľ nemá artefakt.
409 PENDING
Dôkazový balík ešte nie je kompletný.

Ďalšie kroky

  • Pre support stačí najprv poslať documentId, messageId, payloadSha256 a čas odoslania.
  • Vo vlastnom archíve ukladajte aj váš externalId, aby ste vedeli spojiť ERP faktúru s Peppol dôkazmi.

Riešiť zlyhané odoslanie

Pri chybe najprv určite, v ktorej vrstve vznikla: vstupný payload, Peppol capability, schematron validácia, transport alebo lokálne uloženie po odoslaní. Každá vrstva má iný režim opakovania.

Postup

  1. 01Pozrite HTTP status a error.code.
  2. 02Pri retry použite rovnaký Idempotency-Key.
  3. 03Ak bol transport úspešný, sledujte status/eventy namiesto opätovného send-u.

Endpoint

POST/api/v1/documents/send
Vyskúšať

Payload example

json
1{
2  "receiverPeppolId": "0245:0000000001",
3  "receiverName": "Zakaznik s.r.o.",
4  "items": []
5}

Response

json
1{
2  "error": {
3    "code": "VALIDATION_ERROR",
4    "message": "items must contain at least one line",
5    "fields": {
6      "items": "Required"
7    }
8  },
9  "requestId": "req_01JZ8..."
10}

Povinné polia

NázovTypPovinnéPopis
error.codestringánoPrimárna vetva pre rozhodnutie, čo opraviť alebo opakovať.
requestIdstringnieKorelačný identifikátor pre support/debug.
Idempotency-KeyheaderniePoužite rovnaký kľúč pri opakovaní toho istého payloadu.

Práca so stavmi

retryable
503 alebo dočasné transportné chyby opakujte s rovnakým idempotency key.
fix payload
422 VALIDATION_ERROR/UBL_VALIDATION_ERROR vyžaduje opravu dát.
track status
SENT_DB_PENDING alebo prijaté send ID sledujte cez status/eventy.

Chyby

422 VALIDATION_ERROR
JSON schema alebo povinné polia zlyhali; opravte vstup.
422 UBL_VALIDATION_ERROR
UBL porušuje Peppol/CEN pravidlá; opravte XML alebo mapping.
409 IDEMPOTENCY_IN_FLIGHT
Rovnaký kľúč už beží; počkajte a skontrolujte stav neskôr.

Ďalšie kroky

  • Do support ticketu pridajte requestId, documentId/submissionId, messageId a payloadSha256.
  • Ak neviete, či príjemca prijíma typ dokladu, začnite guide-om Check receiver.

Enterprise reliability contract

Enterprise API má pôsobiť ľahko, ale integrátor potrebuje presné runtime pravidlá. Používajte jeden flow: capability → preflight → send → events → support. Tento model drží business chyby, retry a support dáta mimo dashboardu a priamo v API kontrakte.

Postup

  1. 01Capability: zavolajte POST /api/v1/peppol/capabilities a branchujte podľa networkReady, matchedDocumentTypes a routing statusu.
  2. 02Preflight: zavolajte POST /api/v1/documents/preflight pre rovnaký documentTypeId/processId a blokované výsledky opravte pred sendom.
  3. 03Send: POST /api/v1/documents/send opakujte iba s rovnakým Idempotency-Key, ak ide o ten istý payload.
  4. 04Events: čítajte GET /api/v1/events/pull a acknowledge after local commit cez /api/v1/events/{eventId}/ack alebo /api/v1/events/batch-ack; neacknuté eventy server vráti znova.
  5. 05Support: pri incidente ukladajte requestId + support-packet, documentId/submissionId, messageId a payloadSha256.

Endpoint

POST/api/v1/peppol/capabilities
Vyskúšať

Runtime state

json
1{
2  "receiver": {
3    "peppolId": "0245:0000000001",
4    "networkReady": true,
5    "matchedDocumentTypes": ["urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."]
6  },
7  "send": {
8    "idempotencyKey": "erp-FAK-2026-001",
9    "documentId": "doc_01JZ8...",
10    "requestId": "req_01JZ8..."
11  },
12  "events": {
13    "lastEventCursor": "evt_cur_01JZ8...",
14    "ackPolicy": "acknowledge after local commit"
15  },
16  "support": {
17    "supportPacket": "/api/v1/documents/doc_01JZ8.../support-packet",
18    "payloadSha256": "7f9c..."
19  }
20}

Čo má ERP ukladať

NázovTypPovinnéPopis
networkReadybooleanánoVýsledok capability checku pre rozhodnutie, či vôbec skladať alebo poslať payload.
matchedDocumentTypesstring[]niePresné Peppol document-type URN-y, ktoré príjemca akceptuje.
Idempotency-KeyheaderánoStabilný kľúč pre retry toho istého send payloadu.
last acknowledged event idstringánoPosledný lokálne commitnutý a acknutý event, aby ERP import vedel po reštarte pokračovať idempotentne.
requestId + support-packetsupport fieldsánoMinimálny support balík spolu s documentId/submissionId, messageId a payloadSha256.

Práca so stavmi

networkReady=true
Príjemca prijíma daný typ dokladu; pokračujte preflightom.
preflight blocked
Payload alebo routing opravte pred sendom; neposielajte naslepo.
event unacked
Event ostáva na opakované načítanie, kým ho ERP po lokálnom commite nepotvrdí.

Chyby

participant_not_found
Biznis chyba z capability/preflight; neopakujte bez opravy identifikátora.
temporary_transport_error
Retryable runtime chyba; opakujte s backoffom a rovnakým Idempotency-Key.
delivery_dead_lettered
Pre support použite events, requestId a support-packet pred manuálnym retry.

Ďalšie kroky

  • Ak chcete menej krokov, použite Connector; tento kontrakt je pre tímy, ktoré chcú plnú Enterprise API kontrolu.
  • Testujte flow v ERP Test Lab alebo sandbox integrátor portáli pred produkčným go-live.

Vybrať Connector alebo Enterprise API

Connector a Enterprise API nie sú dve značky pre to isté. Connector je ERP-facing managed flow nad Enterprise API; Enterprise API je nižšia vrstva pre tímy, ktoré chcú vlastné workflow, webhooky, dôkazy a viacfiriemnú kontrolu. SAPI je štandardizovaný transportný režim.

Postup

  1. 01Vyberte Connector pre rýchly ERP inbox/outbox.
  2. 02Vyberte Enterprise API pre vlastný lifecycle a dôkazy.
  3. 03Vyberte SAPI pre kompatibilitu so SAPI-SK transportným kontraktom.

Endpoint

GET/api/v1/connector/sync
Vyskúšať

Payload example

json
1{
2  "scenario": "ERP wants plug-and-play Peppol mailbox",
3  "recommendedPath": "Connector",
4  "why": [
5    "polling-first sync",
6    "repair report before send",
7    "mapper/template support"
8  ]
9}

Response

json
1{
2  "scenario": "Platform manages many firms and custom evidence",
3  "recommendedPath": "Enterprise API",
4  "firstEndpoints": [
5    "POST /api/v1/auth/token",
6    "POST /api/v1/documents/send",
7    "GET /api/v1/inbound/documents",
8    "POST /api/v1/webhooks"
9  ]
10}

Povinné polia

NázovTypPovinnéPopis
Connectorproduct pathnieManaged ERP tok: mailbox, mapper, outbox, sync a repair report.
Enterprise APIproduct pathnieKontrolovaná API vrstva: send, inbound, webhooky, dôkazy, multi-firm.
SAPIcompatibility pathnieTransport-only kompatibilita so SAPI-SK, nie dashboard ani Connector flow.

Práca so stavmi

Connector
Najlepšie pre ERP tímy, ktoré chcú rýchly managed flow.
Enterprise API
Najlepšie pre platformy a integrátorov so step-level kontrolou.
SAPI
Použite iba keď potrebujete štandardný transportný kontrakt.

Chyby

Wrong abstraction
Ak ERP tím začne Enterprise API bez potreby vlastného lifecycle, integrácia bude zbytočne dlhšia.
Missing firm context
Pri sk_int_* Enterprise volaniach v mene klienta nezabudnite X-Firm-Id a aktívny consent. Connector používa customerRef nastavené v Integrátorskom portáli pre schválenú firmu; X-Firm-Id na jeho endpointoch neposielajte.

Ďalšie kroky

  • Pre Connector začnite mailbox/sync flowom a SDK konfiguráciou.
  • Pre Enterprise API začnite tokenom, recipient capability checkom a prvým send payloadom.
  • Pre SAPI držte payload ako UBL XML a sledujte iba transportný kontrakt.

Demo testovacie účty

Prostredia sú oddelené. DEV/test: použite tieto demo kľúče na https://dev.epostak.sk/api/v1/auth/token alebo SAPI https://dev.epostak.sk/sapi/v1/auth/token. LIVE/produkcia: použite vlastné produkčné credentials na https://epostak.sk/api/v1/auth/token alebo SAPI https://epostak.sk/sapi/v1/auth/token. Demo kľúče na LIVE hoste zámerne vrátia Invalid client credentials. Pri existujúcich Enterprise volaniach cez integrátorský kľúč (sk_int_*) priložte X-Firm-Id cieľovej spravovanej firmy. Na Connector endpointoch namiesto toho použite customerRef nastavené pre schválenú firmu a X-Firm-Id neposielajte.

Test Odosielateľ (Participant 1)

0245:0000000001
client_id
487d008a-b3a5-49d0-be3e-ba45cc9c4ffe
client_secret
sk_live_••••••••••••••••1eac
X-Firm-Id
f2cea3cf-f29e-4ea2-9e76-b06a312ec9ab

Test Prijímateľ (Participant 2)

0245:0000000002
client_id
b6649c59-2f9d-4ae2-a750-af257c455478
client_secret
sk_live_••••••••••••••••6733
X-Firm-Id
b1022d80-5016-4dad-a8d2-53685cab1701

Demo Integrátor (ERP)

integrátor
client_id
8924a11d-a93c-4d5a-b54b-1f1ff246152c
client_secret
sk_int_t••••••••••••••••c282

Integrátorský kľúč je naviazaný na obe demo participantské firmy vyššie. Na existujúcich Enterprise endpointoch určíte cieľovú firmu cez X-Firm-Id — f2cea3cf-f29e-4ea2-9e76-b06a312ec9ab (Test Odosielateľ) alebo b1022d80-5016-4dad-a8d2-53685cab1701 (Test Prijímateľ). Na nových Connector endpointoch použite customerRef nastavené v Integrátorskom portáli pre danú schválenú firmu a X-Firm-Id vynechajte.

Enterprise Core

Odporúčaný stabilný kontrakt pre nový Enterprise kód: 12 operácií, jeden golden path a uzavretý OpenAPI profil.

Firm context — jedno pravidlo

sk_live_* token je viazaný na firmu. Pri sk_int_* pridajte X-Firm-Id na každý firm-scoped Enterprise request. Connector vyberá firmu cez customerRef a SAPI cez participant scope; tieto tri mechanizmy nemiešajte.

Retry bez duplicity

Pre jeden business send držte rovnaký Idempotency-Key a rovnaký payload. Event batch acknowledge patrí až za durable lokálny commit.

Onboarding klienta

Pre koho je Enterprise API a ako napojíte prvého klienta — cez účet a súhlas vlastníka, alebo cez samostatný White Label provider webhook a zápis participanta do SMP bez účtu ePošťák. Detailné endpointy, oprávnenia a podpisovanie webhookov sú nižšie v sekciách Authentication, Endpoints a Webhooks.

Časový rámec. Klient si ePošťáka volí cez portál Finančnej správy SR; sandbox slúži na technické overenie napojenia a nespúšťa produkčnú viazanosť. Produkčný partner si zvolí technický alebo spravovaný režim, podpíše príslušnú zmluvu a produkčné oprávnenie vznikne až po go-live kontrole a spolupodpise Kaja Solutions. Pri technickom režime navyše každá firma prijme vlastnú API objednávku a účtovanie.
Krok 1: Klient si zvolí ePoštá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štá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 sme to opísali v článku Ako si zvoliť digitálneho poštára.
Krok 2: Partner s aktívnou zmluvou technického partnera vytvorí v partnerskom konte chránený jednorazový odkaz viazaný na IČO alebo DIČ, primárne plánované rozhranie a presné oprávnenia. Primárne rozhranie zostáva evidenčným údajom a neobmedzuje partnera iba na jedno API. Odkaz odošle firme vlastným bezpečným kanálom; systém firmu nevyhľadáva ani jej automaticky neposiela e-mail. Vlastník alebo správca správnej firmy prijme vlastný zmluvný balík API a účtovanie a udelí odvolateľný súhlas. Partner naďalej používa svoj sk_int_*; pri Enterprise API vyberá firmu cez X-Firm-Id a pri Connectori cez customerRef. Firemný sk_live_* tajný kľúč nedostane.
Krok 3: Technická delegácia aj spravovaný režim môžu cez jeden centrálny sk_int_* používať SAPI, Connector s customerRef aj Enterprise API iba v rozsahu súhlasu firmy. Pri technickej delegácii platí firma vlastnú spotrebu; v spravovanom režime platí integrátor súhrnne. Samostatný firemný sk_live_* zostáva priamou alternatívou. Voľba rozhrania sama neurčuje zmluvnú stranu ani platiteľa.
Pred produkciou napíšte z pracovného e-mailu na info@epostak.sk a uveďte názov firmy a účel integrácie. Operátor manuálne vytvorí integrátorský sandbox a testovacie firmy. Produkcia je oddelená: technický partner podpisuje zmluvu technického partnera a firmy podpisujú vlastné API objednávky; spravovaný integrátor podpisuje integrátorskú zmluvu a platí súhrnne. Produkčné kľúče vzniknú až po príslušnom spolupodpise Kaja Solutions a splnení go-live podmienok.

Mapa API referencie

Prehľad zvyšku dokumentácie: prostredia, hlavné API oblasti, request/response pravidlá a odporúčaný spôsob čítania endpointov.

SDK-first quickstart

Odporúčaná cesta je oficiálne SDK: token cacheuje, drží customerRef pri každom volaní a sprístupňuje documents, events aj acknowledge v jednom customer-scoped klientovi. TypeScript je publikovaný na npm; Python, PHP, .NET, Java a Ruby sú dostupné ako zdrojový kód na GitHube.

  • customer = client.connector.customers.for(customerRef)
  • customer.documents.send(...) → customer.events.list(...) → customer.documents.acknowledge(...)
  • Raw HTTP používa rovnaký tok token → documents → events → acknowledge a na Connector endpointoch neposiela X-Firm-Id.
SDK v 6 jazykochConnector quickstart

Prostredia

Produkcia a dev sandbox sú oddelené hosty s oddelenými kľúčmi, dátami a Peppol/SMP nastaveniami.

  • Produkcia: https://epostak.sk/api/v1
  • Sandbox: https://dev.epostak.sk/api/v1
  • Demo kľúče používajte iba na dev hoste.
Demo účtyAuth token

Core documents

Základný send flow: validovať payload, overiť príjemcu, spustiť preflight, odoslať a sledovať lifecycle.

  • JSON faktúra alebo hotový UBL XML.
  • Idempotency-Key je povinný pre bezpečný retry.
  • Support packet je preferovaný podklad pre support.
SendPreflightSupport packet

Alternative formats

PDF/sken, UBL parse, konverzia a validácia patria do Payload Assistant flow pred odoslaním.

  • OCR extract necháva integrátorovi review checklist.
  • Legacy /extract a /documents/* helpery ostávajú podporované.
Payload AssistantExtractValidate

Integration

Webhook push, Events pull a Connector sú samostatné integračné režimy. Vyberte podľa toho, či ERP hostuje receiver, potrebuje iba eventy alebo chce managed mailbox.

  • Events pull je preferovaná pull alternatíva k webhookom.
  • Connector je ERP-facing managed flow nad Enterprise API.
Events pullWebhooksConnector

Partner/admin

Integrátorské firmy, licencie, klientské consent-y a usage/reporting sú oddelené od bežného document flow.

  • sk_int_* tokeny naďalej podporujú existujúce Enterprise firm-scoped volania cez X-Firm-Id aj cross-firm partner endpointy; nový Connector používa customerRef bez X-Firm-Id.
  • Usage/reporting používajte na billing a prevádzkové kontroly.
FirmyReporty
Request format. Všetky JSON endpointy používajú Content-Type: application/json. UBL/XML endpointy akceptujú buď raw XML, multipart file alebo JSON wrapper podľa konkrétneho endpointu; presný tvar je vždy v sekcii endpointu.
Response format. Úspešné odpovede vracajú stabilné IDs ako documentId, submissionId, peppolMessageId alebo cursor. Chyby branchujte podľa error.code a ukladajte requestId.
Ako čítať reference. Každá sekcia nižšie začína prehľadom podobným API reference mapám: kedy ju použiť, ktoré endpointy sú hlavné a čo je legacy/compatibility. Detail endpointov je potom presný kontrakt pre implementáciu.

Autentifikácia

OAuth 2.0 client_credentials — vymeňte API kľúč za krátkodobý JWT. Priamy klient prijme vlastný zmluvný balík API a po spolupodpise Kaja Solutions spravuje sk_live_* vo firemnom konte. Technický partner prijme zmluvu technického partnera a používa centrálny sk_int_* iba pre firmy, ktoré prijali vlastnú API objednávku, platia vlastnú spotrebu a udelili mu odvolateľný súhlas. Spravovaný integrátor používa centrálny sk_int_* a platí súhrnne podľa integrátorskej zmluvy. Firemný tajný kľúč sa partnerovi nikdy neposiela. V oboch partnerských režimoch sú dostupné SAPI, Connector s customerRef aj Enterprise API; zvolený režim naďalej určuje platiteľa. Ceny sú na https://epostak.sk/cennik.

Token lifecycle

API kľúč je secret na mintovanie tokenu, nie bearer pre bežné requesty.

  • POST /api/v1/auth/token vráti access_token a refresh_token.
  • Access token cacheujte; nevolajte token endpoint pred každým requestom.
  • Rotácia secretu invaliduje aktívne tokeny.
TokenRefreshStatus
Životnosť tokenov. POST /api/v1/auth/token vráti dva tokeny: access_token (JWT, RS256) s platnosťou 15 minút (expires_in: 900) a refresh_token (rt_…) s platnosťou 30 dní. Refresh token rotujete cez POST /api/v1/auth/renew — server vám vráti novú dvojicu, starý refresh sa okamžite invaliduje (one-shot, replay → 401).
Cachovanie tokenu. Nikdy nevolajte /auth/token pred každým API requestom — minete rate-limit (200/min) a zaťažíte si latenciu o ~100 ms na každú operáciu. Cachujte access_token v pamäti (alebo v zdieľanom Redis-e pri viacerých workeroch) a používajte ho do expirácie. Refreshujte buď proaktívne ~1 minútu pred uplynutím expires_in, alebo reaktívne pri prvej 401 odpovedi (skúste raz získať nový token a request zopakovať). Pri rotácii sa SDK štandardne stará o cache automaticky; pri vlastnej implementácii pamätajte, že refresh_token je one-shot.
Zneplatnenie. Token môžete kedykoľvek zneplatniť cez POST /api/v1/auth/revoke — pri access tokene sa jeho jti pridá do Redis blocklistu na zvyšok jeho TTL, pri refresh tokene sa zmaže server-side stav. Endpoint je idempotentný (vždy 200). Pri rotácii kľúča (POST /auth/rotate-secret) sa všetky aktívne tokeny okamžite zneplatnia.
GET/api/v1/auth/status

Introspekcia kľúča

Vráti informácie o aktuálnom API kľúči, firme, pláne a efektívnom default rate-limite bez odhalenia plaintext kľúča. Užitočné pre zdravotnú kontrolu a debugging. Niektoré endpointy majú prísnejšie limity (pozri sekciu Rate limity vyššie).

Príklady volania

cURL
curl https://epostak.sk/api/v1/auth/status \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "key": {
    "id": "b1c2d3e4-...",
    "name": "Production key",
    "prefix": "sk_live_abc...xxxx",
    "permissions": "*",
    "active": true,
    "createdAt": "2025-04-01T08:00:00.000Z",
    "lastUsedAt": "2026-04-22T10:30:00.000Z"
  },
  "firm": {"id":"b1022d80-5016-4dad-a8d2-53685cab1701","peppolStatus":"active"},
  "plan": {"name":"api-enterprise","expiresAt":null,"active":true},
  "rateLimit": {"perMinute":1000,"window":"60s","source":"plan-default","note":"effective default — see Rate limits section for endpoint-specific caps"},
  "integrator": null
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden / insufficient scope
  • 404Not Found
POST/api/v1/auth/rotate-secret

Rotovať API kľúč

Deaktivuje aktuálny kľúč a vygeneruje nový sk_live_* kľúč. Plaintext hodnota sa vráti iba raz v odpovedi — uložte si ju okamžite. Integrátorské kľúče (sk_int_*) sa rotujú manuálne cez podporu — tento endpoint pri nich vráti 403.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/auth/rotate-secret \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "sk_live_xxx...xxxx",
  "message": "Key rotated. Save it — it will not be shown again. The previous key is now inactive."
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
GET/api/v1/account

Info o konte

Vrati informácie o firme, Peppol ID, plane a pocte dokumentov.

Príklady volania

cURL
curl https://epostak.sk/api/v1/account -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "firm": {"name":"Moja Firma s.r.o.","ico":"12345678","dic":"2020123456","icDph":"SK2020123456","peppolId":"0245:2020123456","peppolStatus":"active"},
  "plan": {"name":"api-enterprise","status":"active"},
  "usage": {"outbound":47,"inbound":12,"ocrExtractions":5},
  "limits": {"documentsPerMonth":-1}
}

Odpovede

  • 200OK
  • 400Bad Request
  • 401Unauthorized
  • 404Not Found
GET/api/v1/audit

Audit log firmy

Vracia bezpečnostný / autorizačný audit feed pre vašu firmu. Tenant-izolovaný: každý záznam je filtrovaný `firmId`-om, ktorý `withApiKey` zistí z JWT (sk_live_*) alebo z `X-Firm-Id` hlavičky (sk_int_* integrátorské kľúče). Integrátor s jednou Enterprise firmou nemôže vidieť eventy inej firmy. Kurzorová paginácia nad `(occurred_at DESC, id DESC)`. Kurzor je opaque base64url-JSON — nikdy ho neparsujte.

Parametre

NázovTypPovinnéPopis
limitintegeroptional1–100, default 20.
eventstringoptionalPresná zhoda názvu eventu (napr. `jwt.issued`, `webhook.created`).
actor_typestringoptionalJeden z: `user`, `apiKey`, `integratorKey`, `system`.
sincestringoptionalISO 8601 timestamp dolnej hranice (inkluzívne).
untilstringoptionalISO 8601 timestamp hornej hranice (exkluzívne).
cursorstringoptionalOpaque cursor z predošlej odpovede (`next_cursor`).

Príklady volania

cURL
curl "https://epostak.sk/api/v1/audit?limit=20&event=jwt.issued" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "items": [
    {
      "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
      "occurred_at": "2026-05-10T15:00:00.000Z",
      "actor_type": "apiKey",
      "actor_id": "ak_22222222...",
      "event": "jwt.issued",
      "target_type": "firm",
      "target_id": "11111111-...",
      "ip": "1.2.3.4",
      "user_agent": "epostak-sdk/3.2.0",
      "metadata": {"scope": "documents:send"}
    }
  ],
  "next_cursor": "eyJvY2N1cnJlZEF0Ijoi...",
  "has_more": true
}

Odpovede

  • 200OK
  • 401Neplatný alebo chýbajúci token.
  • 403Prístup nepovoľuje tento endpoint. Vyžaduje rozsah `audit:read`, aktívne firemné API oprávnenie a pri partnerskom volaní aj aktívny súhlas firmy.
POST/api/internal/integrator/oauth/clients

Registrovať OAuth klienta

Registrácia nového OAuth klienta pre integrátora. Vráti client_id a client_secret. Auth: integrátorský JWT (sk_int_* kľúč).

Parametre

NázovTypPovinnéPopis
namestringREQNázov OAuth klienta
redirect_urisstring[]REQPovolené redirect URI (HTTPS alebo localhost)
logo_urlstringoptionalURL loga zobrazené na consent obrazovke

Príklady odpovedí

201 Created (client_secret sa zobrazí len raz — uložte si ho okamžite.)
{
  "client_id": "oc_abc123def456",
  "client_secret": "ocsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "My ERP Integration",
  "redirect_uris": ["https://app.tokinu.sk/api/efaktura/oauth/callback"]
}

Odpovede

  • 201Created (client_secret sa zobrazí len raz — uložte si ho okamžite.)
  • 401Unauthorized
  • 409Conflict
GET/oauth/authorize

Autorizačná URL

Presmerujte klienta na túto URL. Po schválení bude presmerovaný späť na redirect_uri s kódom. V dev sandboxe reálne kliknutie ownera/admina na Povoliť vytvorí izolovaný sandboxový consent dôkaz pre certifikačný test; nevytvára produkčný právny súhlas.

Parametre

NázovTypPovinnéPopis
client_idstringREQID vášho OAuth klienta
redirect_uristringREQRegistrovaná callback URL
response_typestringREQcode (povolené: code)
scopestringoptionalfirms:manage documents:send documents:read — ak je prázdne, použije sa celý rozsah klienta
statestringoptionalodporúčané pre CSRF ochranu — náhodný reťazec
code_challengestringREQPKCE code challenge (SHA-256) (43–128 znakov)
code_challenge_methodstringREQS256 (povolené: S256)

Príklady volania

cURL
https://epostak.sk/oauth/authorize
  ?client_id=oc_abc123def456
  &redirect_uri=https://myerp.sk/oauth/callback
  &response_type=code
  &scope=firms:manage%20documents:send%20documents:read
  &state=random_csrf_token
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

Odpovede

  • 302Redirect
  • 400Bad Request
POST/api/oauth/token

Výmena kódu za kľúč

Vymení autorizačný kód za výsledok autorizácie. Pri aktuálnych partnerských pozvánkach partner naďalej používa svoj centrálny sk_int_* a cieľovú firmu určuje cez schválený firemný kontext; firemný sk_live_* tajný kľúč sa partnerovi nikdy nevydáva. Produkčná firma musí mať aktívny neodvolaný súhlas, nemenný KYC dôkaz, vlastné API oprávnenie alebo spravované účtovanie a partner musí mať aktívnu zmluvu zodpovedajúcu technickému alebo spravovanému režimu. Staršia výmena OAuth kľúča zostáva iba kompatibilitnou cestou pre predmigračné súhlasy. OAuth nikdy nevytvára ani neobnovuje samotné partnerské prepojenie. Content-Type: application/x-www-form-urlencoded alebo application/json.

Parametre

NázovTypPovinnéPopis
grant_typestringREQauthorization_code (povolené: authorization_code)
codestringREQAutorizačný kód z redirect_uri
client_idstringREQOAuth client ID
client_secretstringREQOAuth client secret
redirect_uristringREQRovnaká URL ako pri autorizácii
code_verifierstringREQPKCE code verifier

Príklady odpovedí

200 OK
{
  "client_id": "sk_live_xxxxx...abcd",
  "client_secret": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "secret_type": "sk_live",
  "token_type": "client_secret",
  "scope": "firms:manage documents:send documents:read",
  "firm_id": "b1022d80-5016-4dad-a8d2-53685cab1701",
  "firm_name": "Kaja Solutions s.r.o.",
  "firm_ico": "12345678"
}

Odpovede

  • 200OK
  • 400Bad Request — invalid_grant (Neplatný alebo expirovaný autorizačný kód) | invalid_client (Nesprávny client_id alebo client_secret) | invalid_scope (Admin zuzil povolene scopy OAuth klienta medzi /authorize a /token — pozadovane scopy uz nie su povolene)
  • 401Unauthorized

Payload Assistant

Najľahšia cesta od PDF, skenu, UBL alebo JSON vstupu k validnému payloadu pre odoslanie cez Peppol.

Create payload

Použite OCR/PDF alebo UBL helpery, keď ERP ešte nemá čistý send JSON.

  • Extract vráti checklist missing_fields, field_sources a next_action.
  • Parse/convert pomáha pri migrácii z hotového UBL alebo interného formátu.
Extract PDF/skenParse UBL

Validate before send

Vývojový cyklus má najprv validovať payload, až potom vytvárať dokument alebo send.

  • Validation nič neodosiela a nevytvára produkčný doklad.
  • Preflight pridáva Peppol routing a receiver capability kontrolu.
ValidatePreflight
Od vstupu k send payloadu. PDF pošlite na OCR iba raz. Ak odpoveď vyžaduje kontrolu, pošlite jej extraction a všetky opravy naraz na POST /api/v1/payloads/review; tento krok už OCR nespúšťa. Hotový payload potom odošlite cez POST /api/v1/documents/preflight a POST /api/v1/documents/send.
POST/api/v1/payloads/extract

Extrahovať jeden súbor

Extrahuje dáta faktúry z PDF alebo obrázku pomocou AI. Pri prijatej/inbound faktúre vráti Peppol BIS 3.0 UBL XML s validáciou. Pri vystavenej/outbound štandardnej faktúre neodosiela priamo z OCR, ale vráti direction=outbound a send_payload — návrh JSON tela pre POST /api/v1/documents/send, ktorý musí integrátor skontrolovať, doplniť chýbajúce polia (najmä receiverPeppolId, ak sa nedá vyriešiť) a poslať ako samostatnú požiadavku s Idempotency-Key. Outbound OCR je guardrailovaný na štandardné faktúry; nepodporované outbound typy (napr. dobropis) vrátia OUTBOUND_OCR_UNSUPPORTED_DOCUMENT_TYPE. Samofakturácia je podporovaná ako typ dokladu: OCR ju rozpozná z povinnej slovnej informácie (napr. vyhotovenie faktúry odberateľom / self-billing) a pri chybnej klasifikácii ju môžete opraviť. Max 20 MB. Polia missing_fields, field_sources a next_action tvoria checklist pre integrátora. Odporúčaný opravný tok je POST /api/v1/payloads/review: pošlite objekt extraction z tejto odpovede a všetky ľudské opravy naraz v JSON poli fields; PDF sa znova nenahráva a OCR sa znova nespúšťa. Pôvodný kompatibilný resend rovnakého súboru s multipart fields zostáva podporovaný. Rate limit: 10 extrakcií / minúta na firmu.

Parametre

NázovTypPovinnéPopis
fileFileREQPDF, JPEG, PNG, WebP (max 20 MB)
fieldsJSON stringoptionalOptional OCR overrides. Examples: vendor_ico, vendor_dic, vendor_ic_dph, iban, payment_means_code, invoice_number, due_date, document_type=self_billing.

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/payloads/extract \
  -H "Authorization: Bearer eyJhbGc..." \
  -F "file=@invoice.pdf"

Príklady odpovedí

200 OK
{
  "extraction":{"invoice_number":"FAK-001","total":1230.00},
  "ubl_xml":"<?xml...>",
  "confidence":"high",
  "confidence_scores":{"vendor_name":0.95,"invoice_number":0.95,"total":0.95},
  "validation":{"valid":true,"errorCount":0,"warningCount":0,"errors":[],"warnings":[],"deferred":false},
  "vendor_verification":{
    "found_in_peppol_directory":true,
    "canonical_peppol_id":"9950:sk2020019716",
    "canonical_name":"ACME, s.r.o.",
    "canonical_country":"SK",
    "name_match_score":0.95,
    "risk_level":"low",
    "warnings":[]
  },
  "needs_review":false,
  "missing_fields":[],
  "field_sources":{
    "invoice_number":{"source":"ocr","value":"FAK-001","confidence":0.95},
    "sender_peppol_id":{"source":"peppol_directory","value":"9950:sk2020019716"},
    "receiver_peppol_id":{"source":"firm_profile","value":"0245:2020987654"}
  },
  "next_action":{
    "type":"send_document",
    "label":"Pripravené na odoslanie",
    "endpoint":"/api/v1/documents/send",
    "method":"POST"
  },
  "file_name":"invoice.pdf"
}

Odpovede

  • 200OK
  • 400Bad Request
  • 401Unauthorized
  • 403API plan required
  • 422Extraction failed, generated inbound UBL failed validation, or outbound OCR guardrail rejected the document type. Issued/outbound standard invoices return 200 with direction=outbound and send_payload for review.
  • 429Rate Limited
  • 503Service Unavailable
POST/api/v1/payloads/review

Opraviť OCR výsledok bez nového OCR

Vezme objekt extraction vrátený endpointom /api/v1/payloads/extract a všetky ľudské opravy naraz v JSON objekte fields. Opravy aplikuje pred kontrolou vlastníctva a smeru dokladu, znovu vytvorí send_payload alebo UBL a spustí validáciu, ale PDF už neprenáša a OCR už nevolá. Voliteľné review_decision=approve potvrdí ľudskú kontrolu; nikdy neobíde chýbajúce blokujúce polia, neplatný UBL, odloženú validáciu, tenant mismatch ani vysoké riziko dodávateľa. Endpoint dokument neodošle. Rate limit: 60 požiadaviek / minúta na firmu, telo max 2 MB.

Parametre

NázovTypPovinnéPopis
extractionobjectREQExact extraction object returned by POST /api/v1/payloads/extract or by a previous review response.
fieldsobjectoptionalAll corrected values in one object, for example buyer_dic, due_date, iban, items or document_type.
review_decisionstringoptionalSet to "approve" after a person checked the corrected result. Approval cannot clear technical or tenant blockers.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/payloads/review \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "extraction": {"...":"object from /payloads/extract"},
    "fields": {
      "buyer_dic":"2020987654",
      "due_date":"2026-08-26",
      "iban":"SK6807200002891987426353"
    },
    "review_decision":"approve"
  }'

Príklady odpovedí

200 Corrected payload rebuilt without another OCR call
{
  "direction":"inbound",
  "extraction":{"invoice_number":"FA-001","due_date":"2026-08-26"},
  "ubl_xml":"<?xml...>",
  "validation":{"valid":true,"deferred":false,"errors":[],"warnings":[]},
  "needs_review":false,
  "review_approved":true,
  "missing_fields":[],
  "applied_overrides":["due_date","iban"],
  "ocr_reused":true,
  "next_action":{"type":"send_document","endpoint":"/api/v1/documents/send","method":"POST"}
}

Odpovede

  • 200Corrected payload rebuilt without another OCR call
  • 400Invalid extraction or correction object
  • 401Unauthorized
  • 403API plan required or ownership mismatch
  • 413Payload Too Large
  • 422Corrected payload cannot produce valid UBL
  • 429Rate Limited
POST/api/v1/payloads/extract/batch

Batch extrakcia max 50

Spracuje až 50 súborov naraz. Chyba jedného neblokuje ostatné. Každý úspešný riadok vracia extraction a review checklist. Riadky s chýbajúcimi údajmi opravte jednotlivo cez POST /api/v1/payloads/review; pošlete extraction a všetky fields naraz bez nového PDF alebo OCR. Outbound štandardné faktúry vrátia direction=outbound a send_payload. Rate limit: 3 požiadavky / minúta na firmu. Celková veľkosť max 200 MB.

Parametre

NázovTypPovinnéPopis
filesFile[]REQPole suborov max 50 x 20 MB

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/payloads/extract/batch \
  -H "Authorization: Bearer eyJhbGc..." \
  -F "files=@invoice1.pdf" -F "files=@invoice2.pdf"

Príklady odpovedí

200 OK
{
  "results":[
    {"file_name":"invoice1.pdf","extraction":{"invoiceNumber":"FAK-001"},"ubl_xml":"...","confidence":"high","needs_review":false,"missing_fields":[],"field_sources":{"invoice_number":{"source":"ocr","value":"FAK-001","confidence":0.95}},"next_action":{"type":"send_document","label":"Pripravené na odoslanie","message":"Dokument má všetky blokujúce polia a prešiel preflight validáciou.","endpoint":"/api/v1/documents/send","method":"POST"}},
    {"file_name":"invoice2.pdf","error":"Unsupported type: text/plain"}
  ]
}

Odpovede

  • 200OK
  • 400Bad Request
  • 401Unauthorized
  • 403API plan required
  • 413Payload Too Large
  • 429Rate Limited
  • 503Service Unavailable
POST/api/v1/payloads/parse

Rozobrať UBL XML na JSON

Rozoberie UBL XML na normalizovaný JSON bez odoslania. Užitočné pri migrácii z iného AP alebo pre príchodzie doklady z mimo-Peppol kanála (email, SFTP). Prijíma Content-Type: application/xml (raw telo) alebo application/json s poľom xml. Maximum 10 MB.

Parametre

NázovTypPovinnéPopis
xmlstringREQUBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/payloads/parse \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/xml" \
  --data-binary "@invoice.xml"

Príklady odpovedí

200 OK
{
  "invoice": {
    "invoiceNumber": "FAK-2025-001",
    "issueDate": "2025-04-01",
    "dueDate": "2025-04-15",
    "currency": "EUR",
    "invoiceTypeCode": "380",
    "profileId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",
    "supplier": {"name":"Dodávateľ s.r.o.","peppolId":"0245:2020298610","ico":"20202986","icDph":"SK2020298610","street":"Hlavná 1","city":"Bratislava","zip":"81101","country":"SK"},
    "customer": {"name":"Odberateľ a.s.","peppolId":"0245:0000000001","ico":"00000000","icDph":"SK0000000001","street":"Mestská 2","city":"Košice","zip":"04001","country":"SK"},
    "lines": [{"description":"Konzultácia","quantity":1,"unit":"HUR","unitPrice":500,"vatRate":23}],
    "taxSubtotals": [{"vatRate":23,"taxableAmount":500,"taxAmount":115}],
    "totalWithoutVat": 500.00,
    "totalVat": 115.00,
    "totalWithVat": 615.00,
    "amountDue": 615.00
  },
  "extras": {"orderReference":null,"paymentTerms":null},
  "allowances": []
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 413Payload Too Large
  • 422Validation Error
  • 500Parse Error
POST/api/v1/payloads/convert

Konverzia formátov

Konvertuje dokument medzi JSON a UBL XML formátmi bez odoslania cez Peppol. Podporovaná konverzia: json→ubl a ubl→json. Maximum tela požiadavky 6 MB. Pri output_format: ubl je document reťazec s XML dokumentom (nie objekt). JSON→UBL používa rovnaký billing kontrakt a automatické overenie VAT statusu dodávateľa ako /documents/send; zachová items[].vatCategoryCode, iban, receiverPeppolId a rozdelenú adresu. Rozpor s potvrdeným statusom neplatcu vráti 422 namiesto tichého prepisu na 0 %. Syntetické DEV identity 0245:00000000xx môžu explicitnou kombináciou vatCategoryCode/vatRate simulovať platcu aj neplatcu bez záznamu vo FS registri.

Parametre

NázovTypPovinnéPopis
input_formatstringREQ"json" | "ubl" (povolené: json, ubl)
output_formatstringREQ"ubl" | "json" (povolené: ubl, json)
documentobject|stringREQDokument na konverziu

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/payloads/convert \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "input_format": "json",
    "output_format": "ubl",
    "document": {
      "invoiceNumber": "FAK-2026-002",
      "issueDate": "2026-06-11",
      "items": [
        {"description": "Sluzba s prenesenim DPH", "quantity": 1, "unitPrice": 200, "vatRate": 0, "vatCategoryCode": "AE"}
      ]
    }
  }'

Príklady odpovedí

200 OK
{"output_format":"json","document":{"invoice_number":"FAK-001","issue_date":"2025-04-01"},"warnings":[]}

Odpovede

  • 200OK
  • 400Bad Request
  • 401Unauthorized
  • 403API plan required
  • 413Payload Too Large
  • 422Conversion failed
POST/api/v1/payloads/validate

Validovať dokument

Validuje dokument podľa pravidiel Peppol BIS 3.0. Podporuje JSON aj UBL XML vstup. Maximum tela požiadavky je 6 MB. Vyžaduje aktívne firemné API oprávnenie a pri partnerskom volaní aj aktívny súhlas firmy.

Parametre

NázovTypPovinnéPopis
formatstringREQ"json" | "ubl" (povolené: json, ubl)
documentobject|stringREQJSON objekt alebo UBL XML string

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/payloads/validate \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"format":"ubl","document":"<?xml version=\"1.0\"?><Invoice>...</Invoice>"}'

Príklady odpovedí

200 Valid
{
  "valid": true,
  "errorCount": 0,
  "warningCount": 1,
  "errors": [],
  "warnings": [{"id":"PEPPOL-EN16931-R001","message":"..."}]
}

Odpovede

  • 200Valid
  • 400Bad Request
  • 401Unauthorized
  • 403API plan required
  • 413Payload Too Large
  • 422Invalid document — on schematron failure the error code is UBL_VALIDATION_ERROR with a rule field identifying the failing rule ID
  • 503Validation service unavailable

Dokumenty

Odosielanie a príjem faktúr, sledovanie stavu, Lifecycle & proof a sťahovanie evidencie/PDF/UBL.

Outbound lifecycle

Odoslanie je workflow: preflight, send, status/events, protistrana a support packet.

  • POST /documents/send je jediný ostrý send krok.
  • GET /documents/{id}/status je lacný polling status.
  • Support packet nahrádza ručné zbieranie dôkazov.
SendStatusEvents

Inbound and archive

Prijaté dokumenty môžete čítať cez billing inbox alebo full-scope inbound API podľa potreby ERP.

  • Full-scope inbound/outbound API je pre non-billing Peppol typy.
  • PDF, UBL, AS4 envelope a MDN sú auditné artefakty.
Inbound listInboxUBL
Lifecycle & proof. Po odoslaní sledujte jeden dokument cez /documents/{id}/status, /documents/{id}/events, /documents/{id}/responses a /documents/{id}/support-packet. Tieto endpointy tvoria jeden supportovateľný flow: aktuálny stav, časová os, odpovede protistrany a dôkazný balík.
Tri integračné cesty — vyberte podľa potrieb. ePošťák ponúka tri rovnocenné spôsoby, ako konzumovať udalosti a dokumenty. Nemusíte si vybrať jeden — väčšina integrátorov používa kombináciu.
1. Webhooky (POST /api/v1/webhooks + push doručenia) — najnižšia latencia, server-to-server push. Vyžaduje, aby ste mali verejný HTTPS endpoint s HMAC verifikáciou. Vhodné, ak máte ops/IT schopnosť hostovať webhook receiver. HMAC-SHA256 podpis, SSRF guard, encrypted secret-at-rest, auto-disable po 20 terminálnych zlyhaniach, status-code-aware retry (~44h okno pre retryable kódy). Zachované ako mature feature pre súčasných klientov.
2. Events pull facade (GET /api/v1/events/pull + /events/{eventId}/ack) — pull alternatíva k webhookom pre klientov, ktorí nemôžu hostovať receiver. Server nesie stav cez acknowledged=false/true; cross-firm variant /api/v1/webhook-queue/all ostáva pre integrátorov.
3. Inbound / Outbound pull API (GET /api/v1/inbound/documents, GET /api/v1/outbound/documents) — plný dokumentačný prístup. Cursor-based stránkovanie s replay-safe semantikou, list + detail + surový UBL XML, polymorphic naprieč celým Peppol scope-om (Invoice, CreditNote, Order, DespatchAdvice, Catalogue, …). Vhodné, ak potrebujete dokumenty (nie len signály), kompletné historické čítanie, alebo pokrytie non-billing doctypes mimo billing endpointov /documents/inbox a /documents/outbox.
Plus: lifecycle eventy (GET /api/v1/outbound/events) — cursor-based stream interných document_events. Granulárnejší pohľad ako Events pull (per-attempt resolution, transport vs application layer rozlíšenie). Aktuálne pokrýva billing-backed outbound; non-billing je v roadmape.
Rozhodovací prehľad:
  • Mám HTTPS endpoint a chcem push → Webhooky
  • Nemám HTTPS endpoint a chcem len udalosti → Events pull
  • Chcem dokumenty, nie iba signály → Inbound/Outbound pull API
  • Robím audit alebo dashboard a chcem podrobný životný cyklus → Outbound events
Technický partner aj spravovaný integrátor môžu cez centrálny sk_int_* používať SAPI, Enterprise API aj Connector. Každá požiadavka naďalej vyžaduje aktívnu zmluvu zodpovedajúcu režimu vzťahu, neodvolaný súhlas konkrétnej firmy a správny rozsah. Platiteľa určuje režim vzťahu, nie zvolené API rozhranie.
POST/api/v1/documents/send

Odoslať dokument

Odošle dokument cez sieť Peppol. JSON režim podporuje štyri core Peppol billing typy: invoice, credit_note, self_billing a self_billing_credit_note; ePošťák z payloadu vytvorí UBL 2.1 / Peppol BIS 3.0 XML. Hotový UBL XML dokument môžete poslať v JSON poli xml ako expert fallback. Odosielateľ sa vždy berie z autentifikovanej firmy, nie z tela požiadavky. Pred odoslaním overíme v SMP, či je príjemca dostupný v Peppol sieti. Ak nie je, vrátime 422 a nič sa nefakturuje. Hlavička Idempotency-Key (alebo X-Idempotency-Key) je voliteľná: prvé úspešné volanie vráti 201, opakovanie s rovnakým telom vráti 200, aktuálny stav a duplicate: true bez nového odoslania; súbežné spracovanie vráti 409. Ak sa SHA-256 hash tela líši od uloženého, odpoveď je 422 IDEMPOTENCY_KEY_MISMATCH.

Parametre

NázovTypPovinnéPopis
documentTypestringoptionalBusiness typ JSON dokladu. Povolené: invoice, credit_note, self_billing, self_billing_credit_note. Ak chýba, použije sa invoice. (povolené: invoice, credit_note, self_billing, self_billing_credit_note)
document_typestringoptionalSnake_case alias pre documentType. (povolené: invoice, credit_note, self_billing, self_billing_credit_note)
docTypestringoptionalKompatibilný alias pre documentType. Neposielajte naraz rozdielne hodnoty aliasov. (povolené: invoice, credit_note, self_billing, self_billing_credit_note)
receiverPeppolIdstringoptionalPeppol participant ID príjemcu vo formáte scheme:identifier, napr. 0245:2123456789. Pri invoice/credit_note je to kupujúci. Pri self-billing môžete namiesto neho poslať supplierPeppolId.
supplierPeppolIdstringoptionalSelf-billing alias pre dodávateľa/príjemcu Peppol dokumentu. Povolené iba pri self_billing a self_billing_credit_note.
itemsarrayREQPoložky faktúry. Povinné v JSON mode, 1 až 999 riadkov.
items[].descriptionstringREQNázov alebo popis položky. Nesmie byť prázdny.
items[].quantitynumberREQMnožstvo. Musí byť kladné číslo. Záporné množstvo je povolené iba pri items[].lineType=advance_deduction pre odpočet zálohy.
items[].unitPricenumberREQCena za jednotku bez DPH. Nesmie byť záporná.
items[].vatRatenumberREQSadzba DPH v %. Povolené: 0, 5, 10, 19, 20, 23; historická 20 % sadzba je podporovaná pre staršie doklady/opravné doklady. (povolené: 0, 5, 10, 19, 20, 23)
items[].vatCategoryCodestringoptionalDPH kategória BT-151 podľa UNCL5305. Ak chýba, odvodíme ju zo sadzby: vatRate > 0 = S, vatRate 0 = Z. Pre prenesenie daňovej povinnosti pošlite AE. Najčastejšie: S = štandardná sadzba, Z = nulová sadzba, AE = prenesenie daňovej povinnosti. (povolené: S, Z, AE, E, K, G, O, L, M)
items[].vatCategorystringoptionalAlias pre items[].vatCategoryCode. (povolené: S, Z, AE, E, K, G, O, L, M)
items[].vat_categorystringoptionalSnake_case alias pre items[].vatCategoryCode. (povolené: S, Z, AE, E, K, G, O, L, M)
items[].taxTreatmentstringoptionalVyšší ePošťák typ daňového režimu ako alternatíva k priamemu UBL kódu vatCategoryCode. Mapovanie: standard → S, zero_rate → Z, reverse_charge_domestic → AE, exempt → E, intra_community_supply → K, export → G, outside_scope → O. Ak pošlete aj vatCategoryCode, explicitný UBL kód má prednosť. (povolené: standard, zero_rate, reverse_charge_domestic, exempt, intra_community_supply, export, outside_scope)
items[].tax_treatmentstringoptionalSnake_case alias pre items[].taxTreatment. (povolené: standard, zero_rate, reverse_charge_domestic, exempt, intra_community_supply, export, outside_scope)
items[].discountnumberoptionalZľava v percentách, 0 až 100.
items[].unitstringoptionalUN/ECE Rec 20 kód jednotky. Pre kus použite H87; C62 znamená všeobecnú jednotku (one/unit). Ak kód chýba, použije sa C62. Runtime normalizuje aj aliasy: ks→H87, hod→HUR, den→DAY, mes→MON, kg→KGM, m→MTR, l→LTR, km→KTM. (default: C62)
items[].deliveryDatestringoptionalDátum dodania položky pre BT-134. Ak pošlete ISO timestamp, do UBL sa zapíše dátumová časť. Ak položkové dátumy použijete ako súhrnnú faktúru, musia byť v jednom kalendárnom mesiaci a issueDate musí byť najneskôr 15. deň po skončení tohto mesiaca.
items[].lineTypestringoptionalTyp riadku. Použite advance_deduction pre záporný odpočet zálohy na finálnej faktúre. (povolené: standard, advance_deduction)
items[].advanceInvoiceReferencestringoptionalČíslo zálohovej faktúry. Povinné pri lineType=advance_deduction; do UBL sa zapíše ako AdditionalItemProperty s názvom AdvanceInvoiceNumber.
items[].customsTariffCodestringoptionalColný sadzobník / kombinovaná nomenklatúra pri prenesení daňovej povinnosti: 4 až 10 číslic. Do UBL sa zapisuje ako CommodityClassification/ItemClassificationCode listID="HS"; KV DPH A2 používa prvé 4 číslice ako TK.
items[].commodityClassificationCodestringoptionalVšeobecný klasifikačný kód položky, ak nepoužívate customsTariffCode. Pri inom zozname než HS pošlite aj commodityClassificationListId.
items[].commodityClassificationListIdstringoptionalIdentifikátor klasifikačného zoznamu podľa UNTDID 7143. Pri customsTariffCode sa použije HS.
items[].reverseChargeParagraphLetterstringoptionalPísmeno §69 ods. 12 pre domácu evidenciu, napr. f alebo g. Do UBL sa zapisuje ako AdditionalItemProperty.
items[].controlStatementTypestringoptionalTyp pre KV DPH A2 TD. Povolené: IO, MT. (povolené: IO, MT)
items[].controlStatementQuantitynumberoptionalKladné množstvo pre KV DPH A2 Mn. Ak chýba a jednotka je známa, použije sa absolútna hodnota quantity.
items[].controlStatementUnitstringoptionalJednotka pre KV DPH A2 MJ. Povolené: kg, t, m, ks. (povolené: kg, t, m, ks)
invoiceNumberstringoptionalČíslo faktúry. Ak chýba alebo je prázdne, vygeneruje sa z číselného radu firmy.
precedingInvoiceRefstringoptionalExterné číslo pôvodnej faktúry, ktorú dobropis opravuje. Povinné pri credit_note a self_billing_credit_note; do UBL sa zapíše ako BillingReference.
issueDatestringoptionalDátum vystavenia. Ak chýba, použije sa aktuálny deň v časovej zóne Europe/Bratislava. Zadaný dátum sa zachová a vstup sa neodmietne iba preto, že deň odovzdania je odlišný.
dueDatestringoptionalDátum splatnosti.
taxPointDatestringoptionalDátum vzniku daňovej povinnosti (BT-7) vo formáte YYYY-MM-DD.
deliveryDatestringoptionalSkutočný dátum dodania celého dokladu (BT-72) vo formáte YYYY-MM-DD.
documentDiscountPercentnumberoptionalCelková zľava dokladu v percentách od 0 do 100. Zapíše sa ako dokumentová zľava BG-20 a kombinuje sa s riadkovými zľavami.
currencystringoptionalISO 4217 mena. Ak chýba, použije sa default firmy alebo EUR. (default: EUR)
prepaidAmountnumberoptionalSuma zaplatená vopred (BT-113). Do UBL sa zapíše ako LegalMonetaryTotal/PrepaidAmount a zníži PayableAmount. Nekombinujte s riadkom advance_deduction.
prepaymentsarrayoptionalŠtruktúrované zúčtované zálohy na finálnej faktúre. ePošťák spočíta prepayments[].amountWithVat do prepaidAmount, zníži PayableAmount a referencie záloh/daňových dokladov zachová v UBL poznámke. Nevytvára samostatný UBL daňový rozpad zálohy; daňové medzisúčty sa stále skladajú z položiek. Nekombinujte s riadkom advance_deduction.
prepayments[].advanceInvoiceRefstringoptionalČíslo zálohy alebo zálohovej faktúry z IS.
prepayments[].taxDocumentRefstringoptionalČíslo daňového dokladu k prijatej platbe.
prepayments[].settlementDatestringoptionalZúčtovací dátum vo formáte YYYY-MM-DD.
prepayments[].amountWithoutVatnumberoptionalZúčtovaná suma bez DPH.
prepayments[].vatAmountnumberoptionalDPH zo zúčtovanej zálohy.
prepayments[].amountWithVatnumberREQZúčtovaná suma vrátane DPH. Povinná; používa sa na výpočet BT-113 PrepaidAmount.
prepayments[].vatRatenumberoptionalSadzba DPH zálohy, ak ju ERP vie poslať.
prepayments[].vatCategoryCodestringoptionalVoliteľná DPH kategória zálohy, napr. S alebo AE. (povolené: S, Z, AE, E, K, G, O, L, M)
paymentMethodstringoptionalSpôsob platby. Podporované sú ePošťák aliasy bank_transfer, credit_transfer, sepa, card, cash, direct_debit, alebo priamo UNCL4461 kód, napr. 30.
variableSymbolstringoptionalVariabilný symbol / payment reference.
buyerReferencestringoptionalReferencia kupujúceho, napr. číslo objednávky alebo interný nákupný odkaz.
notestringoptionalVoľný text poznámky na faktúre. Pri nulovej DPH alebo špecifickom daňovom režime uveďte dôvod/oslobodenie, ktoré má vidieť príjemca.
ibanstringoptionalIBAN pre platbu. Ak chýba, použije sa IBAN uložený pri firme, ak existuje.
receiverNamestringoptionalObchodné meno príjemcu. Pri invoice/credit_note je to kupujúci; pri self-billing môžete použiť alias supplierName.
receiverIcostringoptionalIČO príjemcu.
receiverDicstringoptionalDIČ príjemcu.
receiverIcDphstringoptionalIČ DPH príjemcu.
receiverStreetstringoptionalUlica a číslo príjemcu. Preferované pred parsovaním jedného poľa receiverAddress.
receiverCitystringoptionalMesto príjemcu.
receiverPostalCodestringoptionalPSČ príjemcu.
receiverAddressstringoptionalJednoriadková adresa príjemcu. Použite ju, ak neviete poslať split polia receiverStreet, receiverCity, receiverPostalCode.
receiverCountrystringoptionalISO 3166-1 alpha-2 krajina príjemcu. (default: SK)
supplierNamestringoptionalSelf-billing alias pre receiverName (dodávateľ).
supplierIcostringoptionalSelf-billing alias pre IČO dodávateľa.
supplierDicstringoptionalSelf-billing alias pre DIČ dodávateľa.
supplierIcDphstringoptionalSelf-billing alias pre IČ DPH dodávateľa. Používa sa aj pri výpočte DPH, lebo dodávateľ je pri self-billing protistrana.
supplierStreetstringoptionalSelf-billing alias pre ulicu dodávateľa.
supplierCitystringoptionalSelf-billing alias pre mesto dodávateľa.
supplierPostalCodestringoptionalSelf-billing alias pre PSČ dodávateľa.
supplierAddressstringoptionalSelf-billing alias pre jednoriadkovú adresu dodávateľa.
supplierCountrystringoptionalSelf-billing alias pre krajinu dodávateľa. (default: SK)
attachmentsarrayoptionalPrílohy faktúry (Peppol BG-24) vložené ako base64 do UBL XML. Max 20 súborov, 10 MB na súbor a 15 MB spolu po base64 dekódovaní.
attachments[].fileNamestringREQNázov súboru prílohy. Nesmie byť prázdny.
attachments[].mimeTypestringREQPovolené MIME typy: application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.oasis.opendocument.spreadsheet. Obsah sa overuje magic-byte kontrolou.
attachments[].contentstringREQBase64-encoded obsah súboru bez data: prefixu.
attachments[].descriptionstringoptionalVoliteľný krátky popis prílohy.
xmlstringoptionalUBL XML mode — hotový UBL XML string ako alternatíva k JSON poliam vyššie. Posiela sa v JSON tele spolu s receiverPeppolId. Max 5 MB pre XML string. Použite ho pre typy dokladov alebo špecifiká, ktoré JSON mode nepokrýva.

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/documents/send \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "receiverPeppolId": "0245:0000000001",
    "receiverName": "Zakaznik s.r.o.",
    "invoiceNumber": "FAK-2025-001",
    "issueDate": "2025-04-01",
    "dueDate": "2025-04-15",
    "items": [{"description": "Vyvoj softveru","quantity": 8,"unitPrice": 125,"vatRate": 23}]
  }'

Príklady odpovedí

201 Sent
{ "documentId": "clx9abc123", "submissionId": "clx9abc123", "messageId": "msg_peppol_xyz", "status": "SENT", "links": { "document": "/api/v1/documents/clx9abc123", "status": "/api/v1/documents/clx9abc123/status", "events": "/api/v1/documents/clx9abc123/events", "ubl": "/api/v1/documents/clx9abc123/ubl", "evidence": "/api/v1/documents/clx9abc123/evidence", "supportPacket": "/api/v1/documents/clx9abc123/support-packet" }, "payloadSha256": "a1b2c3d4e5f6..." }
409 Duplicate Invoice / Idempotency Conflict
{ "error": { "code": "DUPLICATE_INVOICE_NUMBER", "message": "Invoice number 2026001 already exists for your firm. Choose a different number or update the existing document.", "conflictKey": ["firmId", "invoiceNumber"], "existingDocument": { "id": "clx9abc123", "invoiceNumber": "2026001", "status": "sent", "sentAt": "2026-04-15T10:23:11.000Z", "updatedAt": "2026-04-15T10:23:12.000Z", "editable": false, "recipient": { "peppolId": "0245:12345678", "ico": "12345678", "name": "Test s.r.o." } } } }

Odpovede

  • 200Cached/Duplicate
  • 201Sent
  • 202Accepted (async dispatch — status SENT_DB_PENDING; poll /status for delivery confirmation)
  • 401Unauthorized
  • 403API plan required
  • 409Duplicate Invoice / Idempotency Conflict
  • 422Three distinct error codes share 422 — branch on `error.code` to handle correctly: `VALIDATION_ERROR` = input schema rejection (your JSON / XML failed Zod or XSD; fix the payload and retry). `VALIDATION_FAILED` / `UBL_VALIDATION_ERROR` = Peppol schematron rejection (UBL is well-formed but breaks a BIS3/CEN business rule; the `details[]` array carries `rule` IDs like `BR-CO-26` to identify the failure). `IDEMPOTENCY_KEY_MISMATCH` = the same `Idempotency-Key` was reused with a different request body. Generic `VALIDATION_ERROR` retry will silently swallow schematron failures, so always branch on the code.
  • 502Peppol send failed (retryable)
  • 503VALIDATION_UNAVAILABLE — validation service temporarily unreachable, retry with backoff
POST/api/v1/documents/send/batch

Hromadné odoslanie max 50

Odošle až 50 faktúr v jednom volaní. Každá položka má vlastný voliteľný idempotencyKey. Endpoint vždy vráti 200 — chyby sú per-item v poli results. Maximálna veľkosť tela 20 MB.

Parametre

NázovTypPovinnéPopis
itemsarrayREQPole max 50 položiek — rovnaká schéma ako POST /documents/send
items[].idempotencyKeystringoptionalVoliteľný kľúč pre idempotentné opakovanie položky

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/documents/send/batch \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"receiverPeppolId":"0245:0000000001","receiverName":"Zakaznik Demo s.r.o.","items":[{"description":"A","quantity":1,"unitPrice":100,"vatRate":23}],"idempotencyKey":"inv-001"},
    {"receiverPeppolId":"0245:0000000002","receiverName":"Zakaznik B s.r.o.","items":[{"description":"B","quantity":2,"unitPrice":50,"vatRate":23}],"idempotencyKey":"inv-002"}
  ]}'

Príklady odpovedí

200 OK
{
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    {"index":0,"status":201,"result":{"documentId":"clx9abc123","messageId":"msg_peppol_xyz","status":"SENT"}},
    {"index":1,"status":422,"result":{"error":{"code":"UBL_VALIDATION_ERROR","rule":"BR-CL-22","message":"BR-CL-22: invalid MIME type"}}}
  ]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 413Payload too large
  • 422Validation Error
POST/api/v1/box/items

ePošťák Box: zaradiť dokument

Zaradí dokument do ePošťák Boxu. Box je durable execution layer nad existujúcim Enterprise API: payload sa najprv uloží a až potom ho worker odošle cez Peppol podľa plánu, limitov a retry politiky. Nie je to public RabbitMQ/Kafka rozhranie.

Parametre

NázovTypPovinnéPopis
payloadobjectoptionalRovnaký send payload ako POST /api/v1/documents/send; ak payload chýba, použije sa koreňové telo.
scheduledForstringoptionalISO 8601 čas plánovaného odoslania.
externalIdstringoptionalERP/external correlation ID.
idempotencyKeystringoptionalIdempotentné zaradenie dokumentu.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/box/items \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"externalId":"ERP-1001","scheduledFor":"2026-07-01T08:00:00.000Z","payload":{"receiverPeppolId":"0245:0000000001","receiverName":"Zakaznik s.r.o.","items":[{"description":"Sluzba","quantity":1,"unitPrice":100,"vatRate":23}]}}'

Príklady odpovedí

201 Box item created
{"total":1,"ready":1,"items":[{"outboxId":"...","status":"ready","managedOutbox":{"state":"ready_to_send"}}]}

Odpovede

  • 201Box item created
  • 401Unauthorized
  • 403API plan required
  • 422Validation Error
GET/api/v1/box/items

ePošťák Box: zoznam

Vráti Box položky pre firmu z dedicated durable modelu. ePošťák Box nie je alias nad Connector outboxom: Connector, REST aj dashboard cesty sa naň napájajú ako na spoločnú spoľahlivú vrstvu.

Parametre

NázovTypPovinnéPopis
statusstringoptionalFilter stavu
limitintegeroptionalMax 100 (default: 20)
offsetintegeroptionalOffset (default: 0)

Príklady volania

cURL
curl https://epostak.sk/api/v1/box/items?status=scheduled \
  -H "Authorization: Bearer eyJhbGc..."

Odpovede

  • 200OK
GET/api/v1/box/items/{itemId}

ePošťák Box: detail položky

Vráti stav, bezpečný storage summary, dispatch attempty a audit timeline bez plaintext faktúry alebo príloh.

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

  • 200OK
  • 404Not found
POST/api/v1/box/items/{itemId}/schedule

ePošťák Box: naplánovať

Nastaví čas odoslania Box položky. Worker ju odošle až keď je due a keď to umožní rate-limit/tenant quota.

Parametre

NázovTypPovinnéPopis
scheduledForstringREQISO 8601 čas odoslania

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/box/items/{itemId}/schedule \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"scheduledFor":"2026-07-01T08:00:00.000Z"}'

Odpovede

  • 200OK
POST/api/v1/box/items/{itemId}/send-now

ePošťák Box: odoslať teraz

Spustí odoslanie konkrétnej outbound položky, ak má pripravený Connector/Enterprise dispatch pointer. Ak pointer chýba, API vráti 409 namiesto nejasného side effectu.

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

  • 200Dispatch attempted
  • 409Dispatch pointer unavailable
POST/api/v1/box/items/{itemId}/retry

ePošťák Box: retry

Presunie failed alebo needs_repair outbound položku späť do retry/ready stavu a zapíše audit event.

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

  • 200OK
POST/api/v1/box/items/{itemId}/cancel

ePošťák Box: zrušiť

Zruší ešte neodoslanú outbound položku. Sent/received archívne položky sa nemažú týmto endpointom.

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

  • 200OK
GET/api/v1/inbound/documents

Pull: zoznam prijatych dokumentov

Pull-based zoznam prijatych Peppol dokumentov pre vasu firmu. Odporucany primarny sposob integracie pred Peppol mandatom Jan 2027 — namiesto webhook setup-u (2-6 tyzdnov pri SMB) staci poll loop (par hodin prace). Vracia plny rozsah PeppolDocument: invoice, credit_note, order, despatch_advice, catalogue a dalsie. Webhook ostava ako pokrocila alternativa. Kurzor je opaque base64url retazec — neparsujte ho.

Parametre

NázovTypPovinnéPopis
sincestringoptionalOpaque kurzor z `next_cursor` predchádzajúcej odpovede. Vynechajte na prvej požiadavke (začne od najstaršieho dokumentu).
limitintegeroptional1-500. Hodnoty nad 500 sa potichu orezú na 500 (bez 400). (default: 100)
kindstringoptionalFilter podľa typu dokumentu. Neplatná hodnota → 400 so zoznamom platných. (povolené: invoice, credit_note, self_billing_invoice, self_billing_credit_note, mlr, invoice_response, order, order_response, despatch_advice, catalogue, catalogue_response, order_agreement, order_change, order_cancellation, order_response_advanced, punch_out)
senderstringoptionalFilter podľa Peppol participant ID odosielateľa, napr. `0245:2012345678`.

Príklady volania

cURL
# Prvy request — bez kurzora, najstarsie dokumenty:
curl https://epostak.sk/api/v1/inbound/documents \
  -H "Authorization: Bearer eyJhbGc..."

# Pokracovanie z ulozeneho kurzora:
curl "https://epostak.sk/api/v1/inbound/documents?since=eyJ2IjoxLCJyIjoi...&limit=100" \
  -H "Authorization: Bearer eyJhbGc..."

# Filter na faktury od konkretneho odosielatela:
curl "https://epostak.sk/api/v1/inbound/documents?kind=invoice&sender=0245:2012345678" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "documents": [{
    "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
    "received_at": "2026-05-10T14:23:45.512Z",
    "kind": "invoice",
    "peppol_message_id": "uuid-from-peppol-network",
    "sender": {
      "peppol_id": "0245:2012345678",
      "name": "ACME s.r.o.",
      "country": "SK"
    },
    "recipient": {
      "peppol_id": "0245:9988776655",
      "name": "Customer s.r.o.",
      "country": "SK"
    },
    "document_type": "BIS Billing 3.0 Invoice",
    "document_type_id": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::Invoice##urn:cen.eu:en16931:2017",
    "ubl_url": "https://epostak.sk/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ubl",
    "metadata": {
      "invoice_number": "FA-2026-001",
      "total_amount": "1234.56",
      "currency": "EUR",
      "issue_date": "2026-05-09"
    },
    "ack": {"acked_at": null, "client_reference": null}
  }],
  "next_cursor": "eyJ2IjoxLCJyIjoiMjAyNi0wNS0xMFQxNDoyMzo0NS41MTJaIiwiaSI6IjhlNGI4ZjBlLTIxZDMtNGQyYS05YzJiLTI0YTNmOGEwYzExMSJ9",
  "has_more": true
}

Odpovede

  • 200OK
  • 400INVALID_CURSOR (kurzor je poškodený alebo nepodporovaná verzia), alebo BAD_REQUEST pre neplatný `limit`/`kind`.
  • 401Unauthorized
  • 403FORBIDDEN — vyžaduje aktívne firemné API oprávnenie a pri partnerskom volaní aj aktívny súhlas firmy.
  • 429RATE_LIMIT_EXCEEDED
GET/api/v1/inbound/documents/{id}

Pull: detail dokumentu

Vráti ten istý tvar ako jedna položka zo zoznamu. 404 keď dokument neexistuje ALEBO patrí inej firme — ten istý response v oboch prípadoch (tenant izolácia, neúnik existencie).

Príklady volania

cURL
curl https://epostak.sk/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
  "received_at": "2026-05-10T14:23:45.512Z",
  "kind": "invoice",
  "peppol_message_id": "uuid-from-peppol-network",
  "sender": {"peppol_id": "0245:2012345678", "name": "ACME s.r.o.", "country": "SK"},
  "recipient": {"peppol_id": "0245:9988776655", "name": "Customer s.r.o.", "country": "SK"},
  "document_type": "BIS Billing 3.0 Invoice",
  "document_type_id": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::Invoice##urn:cen.eu:en16931:2017",
  "ubl_url": "https://epostak.sk/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ubl",
  "metadata": {"invoice_number": "FA-2026-001", "total_amount": "1234.56", "currency": "EUR", "issue_date": "2026-05-09"},
  "ack": {"acked_at": null, "client_reference": null}
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403FORBIDDEN
  • 404Dokument neexistuje alebo patrí inej firme (rovnaký response).
GET/api/v1/inbound/documents/{id}/ubl

Pull: surový UBL XML

Vráti UBL XML payload v presne takej podobe, v akej sme ho prijali z Peppol siete — bez transformácie, bez kanonikalizácie. Prílohy sú v UBL ako `<cbc:EmbeddedDocumentBinaryObject>` (base64) podľa BIS Billing 3.0; parsujte ich klientsky.

Príklady volania

cURL
curl https://epostak.sk/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ubl \
  -H "Authorization: Bearer eyJhbGc..." \
  -o invoice.xml

Príklady odpovedí

200 OK, Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  <cbc:ID>FA-2026-001</cbc:ID>
  <!-- ... -->
</Invoice>

Odpovede

  • 200OK, Content-Type: application/xml; charset=utf-8
  • 401Unauthorized
  • 403FORBIDDEN
  • 404Dokument nenájdený, patrí inej firme, alebo nemá uložený raw XML (napr. dashboard-importovaný riadok).
POST/api/v1/inbound/documents/{id}/ack

Pull: explicitné potvrdenie spracovania

VOLITEĽNÉ. Väčšina klientov toto nepotrebuje — vlastný postup synchronizácie si drží cez kurzor z `GET /inbound/documents`. Explicitný ack existuje pre klientov, ktorí chcú na serveri zaznamenať „úspešne spracované u nás" oddelene od „úspešne stiahnuté". Je to jeden spoločný stav firmy, nie samostatný stav pre každý API kľúč alebo konzumný systém. Vyžaduje scope `documents:write`, nie iba `documents:read`, pretože mení stav dokumentu. Opakované volanie prepíše timestamp a `client_reference` podľa pravidla latest-ack-wins; každý konzument si preto musí viesť vlastnú evidenciu spracovania.

Parametre

NázovTypPovinnéPopis
client_referencestringoptionalVoliteľný klientsky identifikátor (napr. interné číslo faktúry), max 256 znakov. V tele požiadavky ako JSON `{"client_reference": "..."}`. Prázdne telo je tiež platné.

Príklady volania

cURL
# Bez tela:
curl -X POST https://epostak.sk/api/v1/inbound/documents/8e4b8f0e-.../ack \
  -H "Authorization: Bearer eyJhbGc..."

# S klientskym referencom:
curl -X POST https://epostak.sk/api/v1/inbound/documents/8e4b8f0e-.../ack \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"client_reference": "INT-2026-417"}'

Príklady odpovedí

200 OK — vracia dokument v rovnakom tvare ako detail endpoint, s `ack.acked_at` nastaveným.
{
  "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
  "received_at": "2026-05-10T14:23:45.512Z",
  "kind": "invoice",
  "ack": {"acked_at": "2026-05-10T15:00:00.000Z", "client_reference": "INT-2026-417"}
}

Odpovede

  • 200OK — vracia dokument v rovnakom tvare ako detail endpoint, s `ack.acked_at` nastaveným.
  • 400BAD_REQUEST — telo nie je platné JSON, alebo `client_reference` je dlhšie ako 256 znakov.
  • 401Unauthorized
  • 403FORBIDDEN
  • 404Document not found
GET/api/v1/outbound/documents

Pull: zoznam odoslaných dokumentov

Pull-based zoznam Peppol dokumentov ktoré vaša firma odosiela alebo už odoslala. Spája tabuľky Invoice (fakturácia) a PeppolDocument (objednávky, despatch advices, katalógy…). `transport_status` je uniformný 6-hodnotový enum naprieč oboma tabuľkami; `business_status` (lifecycle z Invoice) sa zobrazí len pri fakturačných dokumentoch. Kurzor je opaque — neparsujte ho.

Parametre

NázovTypPovinnéPopis
sincestringoptionalOpaque kurzor z `next_cursor` predchádzajúcej odpovede.
limitintegeroptional1-500. Hodnoty nad 500 sa potichu orezú na 500. (default: 100)
kindstringoptionalFilter podľa typu dokumentu. Billing kindy (invoice, credit_note, self_billing*) idú do tabuľky Invoice; ostatné do tabuľky PeppolDocument. (povolené: invoice, credit_note, self_billing, self_billing_invoice, self_billing_credit_note, mlr, invoice_response, order, order_response, despatch_advice, catalogue, catalogue_response, order_agreement, order_change, order_cancellation, order_response_advanced, punch_out)
statusstringoptionalFilter podľa `transport_status` (uniformné cez všetky dokumenty). (povolené: queued, sending, sent, delivered, failed, dead)
business_statusstringoptionalFilter podľa Invoice.status (lifecycle, lowercase). Funguje len keď `kind` je billing — kombinácia s non-billing kindom vráti 400. (povolené: sent, delivered, failed, rejected, acknowledged, sending, send_failed, validation_failed, paid, draft, overdue, accepted)
recipientstringoptionalFilter podľa Peppol participant ID príjemcu, napr. `0245:2012345678`.

Príklady volania

cURL
# Najnovsie odoslane dokumenty:
curl https://epostak.sk/api/v1/outbound/documents \
  -H "Authorization: Bearer eyJhbGc..."

# Filter na neuspesne doruceniach (treba zasiahnut):
curl "https://epostak.sk/api/v1/outbound/documents?status=failed" \
  -H "Authorization: Bearer eyJhbGc..."

# Iba fakturacia konkretnemu odberatelovi v stave paid:
curl "https://epostak.sk/api/v1/outbound/documents?kind=invoice&business_status=paid&recipient=0245:2012345678" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "documents": [{
    "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
    "kind": "invoice",
    "document_type": "BIS Billing 3.0 Invoice",
    "document_type_id": null,
    "sender": {"peppol_id": "0245:1111111111", "name": "ACME s.r.o.", "country": "SK"},
    "recipient": {"peppol_id": "0245:2222222222", "name": "Customer s.r.o.", "country": "SK"},
    "created_at": "2026-05-10T10:00:00.000Z",
    "transport_status": "delivered",
    "business_status": "sent",
    "attempt_count": 1,
    "last_attempt_at": "2026-05-10T12:00:00.000Z",
    "error": {"message": null},
    "peppol_message_id": "peppol-msg-...",
    "sent_at": "2026-05-10T12:00:00.000Z",
    "delivered_at": "2026-05-10T12:01:00.000Z",
    "ubl_url": "https://epostak.sk/api/v1/outbound/documents/8e4b8f0e-.../ubl",
    "attempt_history": [],
    "metadata": {
      "invoice_number": "FA-2026-001",
      "total_amount": "1234.56",
      "currency": "EUR",
      "issue_date": "2026-05-09",
      "due_date": "2026-05-23"
    }
  }],
  "next_cursor": "eyJ2IjoxLCJyIjoi...",
  "has_more": true
}

Odpovede

  • 200OK
  • 400INVALID_CURSOR alebo BAD_REQUEST (neplatný `limit`, `kind`, `status` alebo `business_status` skombinovaný s non-billing kind).
  • 401Unauthorized
  • 403FORBIDDEN — vyžaduje aktívne firemné API oprávnenie a pri partnerskom volaní aj aktívny súhlas firmy.
  • 429RATE_LIMIT_EXCEEDED
GET/api/v1/outbound/documents/{id}

Pull: detail odoslaného dokumentu

Detail odoslaného dokumentu vrátane histórie pokusov (`attempt_history`). 404 keď dokument neexistuje ALEBO patrí inej firme ALEBO ide o smerom inbound — rovnaký response v každom prípade (tenant izolácia).

Príklady volania

cURL
curl https://epostak.sk/api/v1/outbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
  "kind": "invoice",
  "transport_status": "delivered",
  "business_status": "paid",
  "attempt_count": 1,
  "attempt_history": [{
    "attempt": 1,
    "status": "success",
    "http_status": 200,
    "error_message": null,
    "attempted_at": "2026-05-10T12:00:00.000Z"
  }],
  "sent_at": "2026-05-10T12:00:00.000Z",
  "delivered_at": "2026-05-10T12:01:00.000Z"
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403FORBIDDEN
  • 404Dokument neexistuje, patrí inej firme, alebo nie je outbound (rovnaký response).
GET/api/v1/outbound/documents/{id}/ubl

Pull: surový UBL XML odoslaného dokumentu

Vráti UBL XML presne v takej podobe, v akej sme ho odoslali na Peppol sieť. Bez transformácie. Billing dokumenty: `invoices.ubl_xml_path`; non-billing: `peppol_documents.raw_xml_path`. 404 keď neexistuje, patrí inej firme, alebo nemá uložený payload.

Príklady volania

cURL
curl https://epostak.sk/api/v1/outbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ubl \
  -H "Authorization: Bearer eyJhbGc..." \
  -o sent-invoice.xml

Odpovede

  • 200OK, Content-Type: application/xml; charset=utf-8
  • 401Unauthorized
  • 403FORBIDDEN
  • 404Not found / no stored payload
GET/api/v1/outbound/documents/{id}/mdn

Surová AS4 MDN doručenka

Vráti surovú AS4 signal-message doručenku (MDN/receipt) pre odoslaný dokument, ak bola forward-retained v archíve. Endpoint je určený pre audit/dispute scenáre; bežný stav doručenia sledujte cez `transport_status`, `delivered_at` alebo webhook/eventy. 404 keď dokument neexistuje, patrí inej firme, nie je outbound, alebo preň ešte nemáme zachovanú MDN doručenku.

Príklady volania

cURL
curl https://epostak.sk/api/v1/outbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/mdn \
  -H "Authorization: Bearer eyJhbGc..." \
  -o delivery-mdn.as4

Odpovede

  • 200OK, raw AS4 receipt bytes. Headers obsahujú `X-MDN-Message-Id`, `X-MDN-Ref-To-Message-Id`, `X-MDN-SHA256` a `X-MDN-Received-At`.
  • 401Unauthorized
  • 403FORBIDDEN — vyžaduje aktívne firemné API oprávnenie a pri partnerskom volaní aj aktívny súhlas firmy.
  • 404Document not found / no retained MDN receipt.
  • 500MDN evidence integrity check failed — hash v DB nesedí s bytes v archíve.
GET/api/v1/outbound/events

Pull: stream udalostí (lifecycle)

Cursor-based stream udalostí zo `document_events` tabuľky. Vracia status-transitions oldest-first (postupuje časom dopredu). LIMITÁCIA: aktuálne pokrýva LEN fakturačné outbound dokumenty (invoice, credit_note, self_billing*); non-billing (Order, DespatchAdvice…) sa zatiaľ trackuje pollovaním `GET /api/v1/outbound/documents`. Polymorphic event log je na roadmape — viď `docs/operations/known-inconsistencies.md`.

Parametre

NázovTypPovinnéPopis
sincestringoptionalOpaque kurzor z `next_cursor` predchádzajúcej odpovede.
limitintegeroptional1-500. Hodnoty nad 500 sa orezú na 500. (default: 100)
document_idstringoptionalFilter len na udalosti jedného dokumentu (UUID).

Príklady volania

cURL
# Vsetky udalosti od posledneho pollu:
curl "https://epostak.sk/api/v1/outbound/events?since=eyJ2IjoxLCJyIjoi..." \
  -H "Authorization: Bearer eyJhbGc..."

# Iba udalosti jednej faktury:
curl "https://epostak.sk/api/v1/outbound/events?document_id=8e4b8f0e-..." \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "events": [{
    "id": "dddddddd-dddd-dddd-dddd-dddddddddd01",
    "document_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaa01",
    "type": "document.sent",
    "actor": "system",
    "detail": null,
    "meta": {},
    "occurred_at": "2026-05-10T10:00:00.000Z"
  }, {
    "id": "dddddddd-dddd-dddd-dddd-dddddddddd02",
    "document_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaa01",
    "type": "document.as4_delivered",
    "actor": "system",
    "detail": null,
    "meta": {"http_status": 200},
    "occurred_at": "2026-05-10T10:01:00.000Z"
  }],
  "next_cursor": "eyJ2IjoxLCJyIjoi...",
  "has_more": false
}

Odpovede

  • 200OK
  • 400INVALID_CURSOR or BAD_REQUEST
  • 401Unauthorized
  • 403FORBIDDEN
GET/api/v1/documents/inbox

Zoznam prijatých fakturačných dokumentov

Vráti stránkovaný zoznam prijatých fakturačných dokumentov. Pre plný Peppol rozsah vrátane nefakturačných typov používajte GET /api/v1/inbound/documents. Oba endpointy fungujú s priamym firemným oprávnením alebo cez sk_int_* technického partnera či spravovaného integrátora, vždy s aktívnym súhlasom a X-Firm-Id. Pole docType môže mať hodnoty invoice, credit_note, self_billing alebo self_billing_credit_note.

Parametre

NázovTypPovinnéPopis
limitintegeroptionalMax 100 (default: 20)
offsetintegeroptionalOffset pre stránkovanie. Pre stabilné stránkovanie vo veľkom objeme použite cursor namiesto offset. (default: 0)
cursorstringoptionalOpaque kurzor zo `nextCursor` predchádzajúcej odpovede. Stabilné stránkovanie aj keď sa medzitým pridajú nové dokumenty.
statusstringoptionalFilter podľa stavu. ACKNOWLEDGED znamená lokálne potvrdenie spracovania klientom cez /acknowledge; nejde o Peppol Invoice Response. (povolené: RECEIVED, ACKNOWLEDGED, ACCEPTED, REJECTED, PAID, VALIDATION_FAILED, FAILED)
peppolMessageIdstringoptionalVyhľadanie dokumentu podľa Peppol message ID (max 100 znakov)
sincestringoptionalISO 8601 dátum — filtruje createdAt >= since pre inkrementálnu synchronizáciu

Príklady volania

cURL 1
curl "https://epostak.sk/api/v1/documents/inbox?limit=10&status=RECEIVED" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{ "documents": [{
  "id": "clx9abc123",
  "number": "FAK-2025-001",
  "status": "received",
  "direction": "inbound",
  "docType": "invoice",
  "issueDate": "2025-04-01",
  "currency": "EUR",
  "supplier": {"name":"Dodávateľ s.r.o.","peppolId":"0245:9876543210"},
  "customer": {"name":"Odberateľ a.s.","peppolId":"0245:0000000001"},
  "totals": {"withoutVat":1000.00,"vat":230.00,"withVat":1230.00},
  "createdAt": "2025-04-01T10:00:00.000Z"
}], "total":42,"limit":10,"offset":0,"nextCursor":"eyJpZCI6ImNseDlhYmMxMjMifQ==" }

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 422Validation Error
GET/api/v1/documents/inbox/{id}

Detail dokumentu

Vrati detail prijateho dokumentu vratane UBL XML payloadu.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/inbox/clx9abc123 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "document": {
    "id": "clx9abc123",
    "number": "FAK-2025-001",
    "status": "received",
    "direction": "inbound",
    "docType": "invoice",
    "issueDate": "2025-04-01",
    "currency": "EUR",
    "supplier": {"name":"Dodávateľ s.r.o.","peppolId":"0245:9876543210"},
    "customer": {"name":"Odberateľ a.s.","peppolId":"0245:0000000001"},
    "totals": {"withoutVat":1000,"vat":230,"withVat":1230},
    "peppolMessageId": "msg_peppol_xyz",
    "createdAt": "2025-04-01T10:00:00.000Z"
  },
  "payload": "<?xml ... UBL invoice XML ...?>"
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
POST/api/v1/documents/inbox/{id}/acknowledge

Potvrdiť spracovanie klientom

Idempotentne zapíše lokálny klientsky ack po spracovaní v ERP. Ide o jeden spoločný stav firmy, nie o samostatné potvrdenie pre každý API kľúč alebo systém. Opakované volanie vráti pôvodný čas prvého potvrdenia s idempotent=true. Potvrdenie dokument nezmaže ani nezablokuje jeho opätovné stiahnutie. Telo požiadavky nie je potrebné. Neodosiela MLS/MLR ani Invoice Response a nemení Peppol/business stav dokumentu.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/documents/inbox/clx9abc123/acknowledge \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{ "documentId":"clx9abc123", "status":"ACKNOWLEDGED", "clientAckedAt":"2025-04-01T11:00:00.000Z", "acknowledgedAt":"2025-04-01T11:00:00.000Z", "idempotent":false }

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
  • 422Invalid state transition
GET/api/v1/documents/{id}/status

Stav dokumentu

Vráti úplný životný stav dokumentu vrátane histórie stavov a výsledku validácie. Limit 400 req/min na API kľúč. Pri pravidelnom kontrolovaní viacerých dokumentov použite hromadný endpoint POST /api/v1/documents/status/batch — jedným volaním získate stav až 100 dokumentov.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/status \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "id": "clx9abc123",
  "status": "sent",
  "documentType": "invoice",
  "senderPeppolId": "0245:9876543210",
  "receiverPeppolId": "0245:0000000001",
  "statusHistory": [{"status":"queued","timestamp":"2025-04-01T10:00:00.000Z"},{"status":"sent","timestamp":"2025-04-01T10:01:00.000Z"}],
  "validationResult": null,
  "deliveredAt": "2025-04-01T10:01:00.000Z",
  "invoiceResponseStatus": null,
  "as4MessageId": "msg_peppol_xyz",
  "createdAt": "2025-04-01T10:00:00.000Z",
  "updatedAt": "2025-04-01T10:01:00.000Z"
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
POST/api/v1/documents/status/batch

Hromadný stav až 100 dokumentov

Vráti stav až 100 dokumentov v jednom volaní. Výsledky sú v rovnakom poradí ako vstupné ids. Dokumenty, ktoré nepatria volajúcej firme alebo neexistujú, sú v odpovedi označené { "error": "not_found" } — endpoint nikdy nevráti 404 pre celé volanie ani neprezradí existenciu dokumentov inej firmy. Limit 300 req/min na API kľúč (až 30 000 stavov za minútu). Pre jednotlivé dokumenty použite GET /api/v1/documents/{id}/status (limit 400 req/min).

Parametre

NázovTypPovinnéPopis
idsstring[]REQ1 až 100 ID dokumentov. Duplicitné ID sa zlúčia, poradie odpovede zachová poradie vstupu.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/documents/status/batch \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["clx9abc123","clx9def456","clx9ghi789"]}'

Príklady odpovedí

200 OK
{
  "total": 3,
  "found": 2,
  "notFound": 1,
  "results": [
    { "id": "clx9abc123", "status": "delivered", "documentType": "invoice", "senderPeppolId": "0245:9876543210", "receiverPeppolId": "0245:0000000001", "statusHistory": [...], "validationResult": null, "deliveredAt": "2025-04-01T10:02:30.000Z", "acknowledgedAt": null, "invoiceResponseStatus": null, "as4MessageId": "msg_peppol_xyz", "createdAt": "2025-04-01T10:00:00.000Z", "updatedAt": "2025-04-01T10:02:30.000Z" },
    { "id": "clx9def456", "status": "sent" },
    { "id": "clx9ghi789", "error": "not_found" }
  ]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 413Payload too large (> 64 KB)
  • 422Validation Error (ids[] missing, prázdne, viac ako 100, alebo non-string)
  • 429Too Many Requests
GET/api/v1/documents/{id}/evidence

AS4 potvrdenie a MLR

Vráti AS4 potvrdenie o doručení, MLR dokument a odpoveď na faktúru (invoice response), ak sú dostupné.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/evidence \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "documentId": "clx9abc123",
  "as4Receipt": "<?xml ...AS4 receipt...>",
  "mlrDocument": "<?xml ...MLR...>",
  "invoiceResponse": {"status":"AP","document":"<?xml...>"},
  "tdd": {"reportedAt":"2025-04-01T10:05:00.000Z","reported":true},
  "deliveredAt": "2025-04-01T10:01:00.000Z",
  "sentAt": "2025-04-01T10:00:00.000Z"
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
GET/api/v1/documents/{id}/support-packet

Support packet dokumentu

Vráti jeden ZIP balík pre audit, reklamáciu alebo support: manifest.json, evidence.json, UBL XML, PDF, prílohy faktúry a dostupné AS4/MDN artefakty. Manifest verzie 2 pri prílohách uvádza purpose, origin, transported, sha256 a lockedAt. Pri ručne alebo OCR importovanej prijatej faktúre označí transport ako manual_import/not_applicable; taký balík obsahuje presný zdrojový dokument, ale nepreukazuje Peppol doručenie. Pri nesúlade uloženého SHA-256 s obsahom sa balík nevydá.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/support-packet \
  -H "Authorization: Bearer eyJhbGc..." \
  --output evidence.zip

Odpovede

  • 200application/zip — manifest.json, evidence.json and available document/evidence artifacts
  • 401Unauthorized
  • 403API plan required
  • 404Not Found — document missing or not yours
  • 500MDN evidence integrity check failed
GET/api/v1/documents/{id}/envelope

AS4 envelope (WORM archív)

Vráti podpísaný AS4 multipart payload dokumentu z dôkazného archívu Enterprise API. Archív je dostupný počas aktívneho kontraktu a 30 dní po jeho ukončení na export; nejde o samostatnú účtovnú archiváciu mimo kontraktu. Payload je identický s tým, čo prešlo cez Peppol sieť — podpísaný, časovo razítkovaný, tamper-evident. Odpoveď má hlavičky X-Envelope-Archived-At (ISO 8601) a X-Envelope-Direction (inbound/outbound). 404 sa vracia, ak dokument neexistuje, nepatrí vám, alebo jeho envelope ešte nebol archivovaný (nové dokumenty sa archivujú za niekoľko minút).

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/envelope \
  -H "Authorization: Bearer eyJhbGc..." \
  --output envelope.as4

Odpovede

  • 200application/octet-stream — raw AS4 envelope bytes
  • 401Unauthorized
  • 403API plan required
  • 404Not Found — document missing, not yours, or envelope not yet archived
GET/api/v1/documents/{id}/events

Udalosti životného cyklu dokumentu

Vráti chronologický zoznam udalostí pre daný dokument. Kombinuje reálne záznamy DocumentEvent s udalosťami odvodenými z historických stavov faktúry (created, status_changed, sent, delivered, mlr_received, response_sent/received, paid, fs_reported). Stránkovanie je kurzorové, predvolene 20 položiek, najviac 100.

Parametre

NázovTypPovinnéPopis
limitintegeroptionalMax 100 (default: 20)
cursorstringoptionalOpaque cursor from pagination.nextCursor

Príklady volania

cURL
curl "https://epostak.sk/api/v1/documents/clx9abc123/events?limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "documentId": "clx9abc123",
  "events": [
    {"id":"syn-clx9abc123-1","eventType":"document.created","actor":"system","detail":"Document FAK-2025-001 created","meta":{"createdVia":"api","direction":"outbound","docType":"invoice"},"occurredAt":"2025-04-01T10:00:00.000Z"},
    {"id":"syn-clx9abc123-2","eventType":"document.status_changed","actor":"system","detail":null,"meta":{"toStatus":"sent"},"occurredAt":"2025-04-01T10:01:00.000Z"},
    {"id":"evt_real_abc","eventType":"document.response_received","actor":"system","detail":null,"meta":{"invoiceResponseStatus":"AP"},"occurredAt":"2025-04-01T11:30:00.000Z"}
  ],
  "pagination": {"limit":20,"nextCursor":null,"hasMore":false}
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
GET/api/v1/documents/{id}/responses

Invoice response história

Vráti zoznam invoice response udalostí pre daný dokument (document.response_sent / document.response_received). Ak pre dokument neexistujú reálne DocumentEvent záznamy ale invoiceResponseStatus je nastavené, vráti syntetizovaný záznam z posledného updatedAt.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/responses \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "documentId": "clx9abc123",
  "responses": [
    {"id":"evt_resp_abc","responseCode":"AP","note":null,"senderPeppolId":"0245:9876543210","createdAt":"2025-04-01T11:30:00.000Z"}
  ]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
GET/api/v1/documents/{id}/pdf

Stiahnuť PDF

Stiahne PDF verziu dokumentu. Vráti binárny obsah s Content-Type: application/pdf.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/pdf \
  -H "Authorization: Bearer eyJhbGc..." \
  --output invoice.pdf

Odpovede

  • 200application/pdf
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
GET/api/v1/documents/{id}/ubl

Stiahnuť UBL XML

Stiahne UBL XML súbor dokumentu. Vráti XML string s Content-Type: application/xml. 404 sa vracia ak dokument neexistuje, nepatri vám, alebo ešte nemá pripojené UBL XML.

Príklady volania

cURL
curl https://epostak.sk/api/v1/documents/clx9abc123/ubl \
  -H "Authorization: Bearer eyJhbGc..." \
  --output invoice.xml

Odpovede

  • 200application/xml
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
POST/api/v1/documents/{id}/respond

Odoslať odpoved na fakturu

Odošle odpoveď na prijatú faktúru (invoice response). Funguje iba pre inbound dokumenty. Iba jedna finálna odpoveď. Po odoslaní UQ je povolená ešte jedna zmena; po AP/RE/PD ďalšie volanie vráti 422.

Parametre

NázovTypPovinnéPopis
statusstringREQAB (accepted billing), IP (in process), UQ (under query), CA (conditionally accepted), RE (rejected), AP (accepted), PD (paid) (povolené: AB, IP, UQ, CA, RE, AP, PD)
notestringoptionalVoliteľná poznámka — max 500 znakov, dlhší text sa skráti

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/documents/clx9abc123/respond \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"status":"AP","note":"Faktura akceptovana"}'

Príklady odpovedí

200 Úspech
{"documentId":"clx9abc123","responseStatus":"AP","respondedAt":"2025-04-01T11:00:00.000Z","peppolMessageId":"msg_peppol_resp_xyz","dispatchStatus":"sent"}

Odpovede

  • 200Úspech
  • 202Accepted-queued
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Validation Error
POST/api/v1/documents/{id}/mark

Označiť stav dokumentu

Granulárne stavové prechody pre dokumenty spracované vlastnou pipeline integrátora (napr. SFTP doručenie, lokálne spracovanie, čítanie vo front-ende). Doplnok k /acknowledge, ktorý pokrýva len Peppol príjem. Endpoint neoveruje zdrojový stav — opakované volanie alebo mimo-poradie volanie prepíše timestamps/status. Integrátor je zodpovedný za poradie. mark processed nastaví acknowledgedAt, ale nemení status. mark failed nastaví status=failed. mark delivered / mark read nastavia iba príslušný timestamp.

Parametre

NázovTypPovinnéPopis
statestringREQdelivered | processed | failed | read (povolené: delivered, processed, failed, read)
notestringoptionalVoliteľná poznámka

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/documents/clx9abc123/mark \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"state":"processed","note":"Zaúčtované v ERP"}'

Príklady odpovedí

200 OK
{
  "id": "clx9abc123",
  "state": "processed",
  "status": "received",
  "deliveredAt": "2025-04-01T10:01:00.000Z",
  "acknowledgedAt": "2025-04-01T10:15:00.000Z",
  "readAt": null
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
  • 422Invalid state
POST/api/v1/documents/preflight

Kontrola pred odoslaním

Dry-run odoslania bez vytvorenia dokladu a bez účtovania spotreby. Enterprise reliability contract ho používa po capability checku a pred sendom v toku capability → preflight → send → events → support. Overí UBL validáciu, Peppol účastníka, presný SMP routing pre `documentTypeId + processId`, endpoint URL a certifikačné metadata. Endpoint vracia 200 aj pri blokovanom výsledku — rozhodnutie čítajte z `decision`, `canSend`, `errors[]` a `checks[]`; rovnaký payload pri retry posielajte s rovnakým Idempotency-Key až pri následnom send-e. Integrátorský vstup používa `senderParticipantId`, `receiverParticipantId`, `documentTypeId`, `processId`, `ublDocument`; podporované sú aj aliasy `receiverPeppolId`, `xml` a `invoice`. Pri UBL XML vstupe sa kontroluje, či sa Peppol ID dodávateľa v XML zhoduje s autentifikovanou firmou — nesúlad vráti 422.

Parametre

NázovTypPovinnéPopis
receiverParticipantIdstringoptionalPeppol ID príjemcu, napr. `0245:2020123456` alebo `iso6523-actorid-upis::0245:2020123456`. Odporúčaný nový názov.
receiverPeppolIdstringoptionalAlias pre `receiverParticipantId`.
senderParticipantIdstringoptionalVoliteľné Peppol ID odosielateľa. Ak je uvedené, musí sedieť s autentifikovanou firmou.
documentTypeIdstringoptionalPeppol document-type URN. Default je BIS Billing 3.0 Invoice.
processIdstringoptionalPeppol process ID. Default je `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`.
ublDocumentstringoptionalRaw UBL XML dokument na validáciu. Alias `xml` je podporovaný.
documentTypestringoptionalSkratka pre invoice profil. Pre non-invoice profily používajte `documentTypeId`. (povolené: invoice)
invoiceobjectoptionalJSON faktúra na validáciu
xmlstringoptionalAlias pre `ublDocument`

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/documents/preflight \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "senderParticipantId":"0245:2020123456",
    "receiverParticipantId":"0245:2020298610",
    "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",
    "ublDocument":"<Invoice>...</Invoice>"
  }'

Príklady odpovedí

200 OK — sendable, blocked, or retryable decision is encoded in the JSON body
{
  "decision": "sendable_with_warnings",
  "networkReady": true,
  "valid": true,
  "canSend": true,
  "participantExists": true,
  "errors": [],
  "warnings": [{
    "category": "VALIDATION",
    "code": "BR-DEMO",
    "severity": "warning",
    "message": "Buyer reference is recommended",
    "location": "/Invoice/cbc:BuyerReference"
  }],
  "checks": [
    {"name":"validation","status":"warning","durationMs":180},
    {"name":"participant","status":"passed","durationMs":420},
    {"name":"routing","status":"passed","durationMs":420}
  ],
  "recipient": {
    "peppolId": "0245:2020298610",
    "scheme": "0245",
    "identifier": "2020298610",
    "source": "sml",
    "accessPoint": {"url":"https://ap.receiver.example/as4","transportProfile":"peppol-transport-as4-v2_0"},
    "certificate": {"present":true,"serviceExpirationDate":"2099-01-01T00:00:00Z"},
    "supportedDocumentTypes": ["urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."]
  },
  "documentProfile": {
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##...",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "ruleset": "Peppol BIS Billing 3.0",
    "rulesetVersion": "current",
    "inputMode": "ubl"
  },
  "trace": {"traceId":"...","checkedAt":"2026-05-17T12:00:00.000Z","durationMs":620,"validationMs":180,"participantLookupMs":420},
  "recipientFound": true,
  "recipientAcceptsDocumentType": true,
  "validationPassed": true,
  "validationErrors": []
}

Odpovede

  • 200OK — sendable, blocked, or retryable decision is encoded in the JSON body
  • 401Unauthorized
  • 403API plan required
  • 413Payload Too Large
  • 422Validation Error — includes UBL_VALIDATION_ERROR with rule field on schematron failure; 422 SENDER_MISMATCH when XML supplier Peppol ID differs from authenticated firm
POST/api/v1/inbound/import

Importovať prijatý UBL dokument

Uloží UBL fakturačný dokument prijatý mimo Peppol siete (email, SFTP, migrácia z iného access pointu) do rovnakého inbound úložiska ako sieťové Peppol doručenia. Podporuje raw Content-Type: application/xml alebo application/json s poľom xml. Overíme receiver identitu proti autentifikovanej firme: pri štandardnej faktúre musí AccountingCustomerParty/EndpointID zodpovedať firme, pri self-billing dokumente musí firme zodpovedať AccountingSupplierParty/EndpointID. Inak vrátime 422 a nič neuložíme. Po úspešnom importe je dokument dostupný cez GET /api/v1/inbound/documents/{id}, raw UBL cez /ubl a odošle sa event document.received.

Parametre

NázovTypPovinnéPopis
xmlstringREQRaw UBL XML body, or the xml field when Content-Type is application/json. Max 20 MB.
sourcestringoptionalOptional JSON-only source label such as email, sftp, manual or migration. Stored as import_source metadata.
messageIdstringoptionalOptional JSON-only external message ID. If omitted, the API stores import:{documentId}.
documentTypeIdstringoptionalOptional JSON-only Peppol document-type URN override. Defaults from the parsed invoice type.
processIdstringoptionalOptional JSON-only Peppol process URN override. Defaults from the parsed invoice type.
Idempotency-KeyheaderoptionalOptional key stored on the imported PeppolDocument row for retry-safe replay. Reusing the same key with the same normalized request returns the original document with duplicate=true; reusing it with different metadata or XML returns 422.

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/inbound/import \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: email-2026-06-30-001" \
  --data-binary "@received-invoice.xml"

Príklady odpovedí

201 Imported
{
  "documentId": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
  "submissionId": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
  "status": "RECEIVED",
  "kind": "invoice",
  "source": "api_import",
  "links": {
    "document": "/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
    "ubl": "/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ubl",
    "ack": "/api/v1/inbound/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ack"
  }
}

Odpovede

  • 201Imported
  • 401Unauthorized
  • 403API plan required
  • 413Payload Too Large
  • 422Invalid XML, unsupported document type, or receiver Peppol ID does not match this firm
GET/api/v1/documents/inbox/all

Cross-firm inbox

Vráti dokumenty zo všetkých firiem, ktoré partnerovi udelili aktívny súhlas v požadovanom rozsahu. Vyžaduje JWT zo sk_int_* kľúča. Výsledky sú obmedzené na dokumenty doručené po vzniku konkrétneho partnerského prepojenia. Pri technickej delegácii platí každá firma vlastnú API spotrebu; pri spravovanom režime platí integrátor súhrnne. Connector documents/events vyberá schválenú firmu cez customerRef v oboch partnerských režimoch.

Parametre

NázovTypPovinnéPopis
sincestringoptionalISO 8601 — dokumenty od dátumu
statusstringoptionalFilter podľa stavu — predvolene všetky (parameter vynechajte). Hodnoty sa porovnávajú case-insensitive. ACKNOWLEDGED znamená lokálne potvrdenie spracovania klientom cez /acknowledge; nejde o Peppol Invoice Response. (povolené: RECEIVED, ACKNOWLEDGED, ACCEPTED, REJECTED, PAID, VALIDATION_FAILED, FAILED)
firm_idstringoptionalFiltrovať podľa firmy
offsetnumberoptionalPosunutie pre stránkovanie
limitnumberoptionalMax výsledkov (default 50, max 200) (default: 50)

Príklady odpovedí

200 OK
{
  "documents": [{
    "firm_id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "firm_name": "Kaja Solutions s.r.o.",
    "id": "clx9abc123",
    "number": "FAK-2025-001",
    "status": "received",
    "direction": "inbound",
    "doc_type": "invoice",
    "issue_date": "2025-04-01",
    "due_date": "2025-04-15",
    "currency": "EUR",
    "supplier": {"name":"...","ico":"...","peppol_id":"0245:9876543210"},
    "customer": {"name":"...","ico":"...","peppol_id":"0245:0000000001"},
    "totals": {"without_vat":1000.00,"vat":230.00,"with_vat":1230.00},
    "peppol_message_id": "msg_peppol_xyz",
    "created_at": "2025-04-01T10:00:00.000Z"
  }],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden

Webhooky a udalosti

Notifikácie v reálnom čase. Vyžadujú aktívne firemné API oprávnenie; partnerské volanie navyše aktívny súhlas firmy, správny rozsah a X-Firm-Id. Podpis HMAC-SHA256. Udalosti: document.sent, document.received, document.delivered, document.delivery_failed, document.rejected, document.response_received. Retry policy (od 2026-05-12, Retry-After rešpektovaný od 2026-05-14) rozlišuje stavové kódy: 408, 425, 429, 502, 503, 504 a sieťové chyby opakujeme najviac desaťkrát s ohraničeným rozstupom 30 s → 30 s → 2 min → 10 min → 30 min → 2 h → 6 h → 12 h → 24 h. Retry-After rešpektujeme najviac do 24 hodín na pokus. Terminálne kódy 400/401/403/404/405/410/413/415/422/500/501 končia bez opakovania. Časový limit požiadavky je 10 sekúnd a odber sa vypne po 20 po sebe idúcich terminálnych zlyhaniach bez úspechu.

Choose push or pull

Webhooky sú push kanál; Events pull je preferovaný pull kanál pre tímy bez verejného receivera.

  • Push delivery vyžaduje HMAC verifikáciu a verejný HTTPS endpoint.
  • Pull ack robte až po lokálnom commite v ERP.
  • Cross-firm webhook-queue/all ostáva dostupný pre integrátorov.
Events pullCreate webhookBatch ack

Operate failures

História doručení a dead letters patria do prevádzky webhookov, nie do business payload validácie.

  • Retry-After sa rešpektuje pri retryable odpovediach.
  • Terminálne chyby zastavia delivery bez ďalšieho retry.
DeliveriesDead letters
Push vs pull — Každá subscription je buď push (POST na vašu URL) alebo pull (event v queue, ktorú periodicky čítate cez GET /api/v1/events/pull). Subscription s url je push-only; subscription bez url (null) je pull-only. Jedna subscription = jeden kanál; ak chcete oba, vytvorte dve subscriptiony. Push deliveries sa nezapisujú do pull queue a naopak — kanály sú navzájom oddelené.
Integrátori — Pre spravovanú firmu vytvorte pull subscription cez POST /api/v1/webhooks so svojím sk_int_* JWT, hlavičkou X-Firm-Id danej firmy a telom { url: null, events: [...] }. Až nové udalosti po tomto nastavení sa objavia v /api/v1/webhook-queue/all. Staršie odoslania sa do queue spätne nedopĺňajú.
Tvar payloadu (v1) — Telo POSTu / položka v pull queue obsahuje obálku { event, event_version: "1", webhook_id, webhook_event_id, timestamp, data }. webhook_event_id je stabilný UUID dedup key a pre pull subscription zároveň eventId pre POST /api/v1/events/{eventId}/ack. data závisí od typu udalosti.
Hlavičky a overenie podpisu — Každý webhook obsahuje HMAC-SHA256 podpis (kontrakt sa nemenil). Z hlavičiek si vezmite X-Webhook-Timestamp a X-Webhook-Signature, spojte timestamp + "." + raw body, vypočítajte HMAC-SHA256 so svojím webhook secretom a porovnajte s hodnotou z hlavičky. Odmietnite požiadavku, ak je timestamp starší ako 5 minút (ochrana proti replay útokom). Ďalšie hlavičky (od 2026-05-12): X-Webhook-Event-Id (UUID, dedup key, identická cez všetky retry — odporúčaný primárny dedup), X-Webhook-Id (per-delivery, identifikuje konkrétny webhook_deliveries riadok), X-Webhook-Event (typ event-u), X-Webhook-Attempt (1-based číslo pokusu, mení sa medzi retry-mi), X-Webhook-Max-Attempts (celkový počet pokusov v retry okne).
GET/api/v1/webhooks

Zoznam webhookov

Vrati vsetky webhooky pre vashu firmu.

Príklady volania

cURL
curl https://epostak.sk/api/v1/webhooks -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{"data":[{"id":"wh_abc123","url":"https://your-app.com/webhook","events":["document.received"],"isActive":true,"failedAttempts":0,"createdAt":"2025-04-01T10:00:00.000Z"}]}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
POST/api/v1/webhooks

Vytvoriť webhook

Vytvorí nový webhook alebo pull-only event subscription. URL je voliteľná: ak ju vynecháte alebo dáte null, eventy čítate cez GET /api/v1/events/pull. Subscription je forward-only: zaradia sa iba udalosti vytvorené po jej aktivácii, historické document.sent/delivered/received sa spätne nedopĺňajú. Integrátor vytvára subscription pre spravovanú firmu cez svoj sk_int_* JWT a hlavičku X-Firm-Id. Samotné webhooks:read oprávnenie queue iba číta; ak pre firmu neexistuje pull subscription pre daný event, /webhook-queue/all ostane prázdne aj po úspešnom odoslaní dokumentu. Ak URL zadáte, musí mať HTTPS. Secret pre overenie podpisu je zobrazený iba raz.

Parametre

NázovTypPovinnéPopis
urlstring | nulloptionalHTTPS URL pre push, alebo null/omit pre pull-only
eventsstring[]optionalPredvolene vsetky udalosti

Príklady volania

cURL
# Push subscription
curl -X POST https://epostak.sk/api/v1/webhooks \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhook","events":["document.received"]}'

# Pull-only subscription
curl -X POST https://epostak.sk/api/v1/webhooks \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"url":null,"events":["document.received","document.sent"]}'

# Integrator-managed firm pull subscription
curl -X POST https://epostak.sk/api/v1/webhooks \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "X-Firm-Id: 03023594-57ff-451f-a743-b9fe139dd58b" \
  -H "Content-Type: application/json" \
  -d '{"url":null,"events":["document.sent","document.received","document.delivered","document.delivery_failed","document.rejected","document.response_received"]}'

Príklady odpovedí

201 Created
{"id":"wh_abc123","url":"https://your-app.com/webhook","events":["document.received"],"secret":"whsec_a1b2c3...","isActive":true,"createdAt":"2025-04-01T10:00:00.000Z"}

Odpovede

  • 201Created
  • 401Unauthorized
  • 403API plan required
  • 413Payload too large
  • 422Validation Error
GET/api/v1/webhooks/{id}

Detail + doručenia

Vrati detail webhooku a poslednych 20 pokusov o dorucenie.

Príklady volania

cURL
curl https://epostak.sk/api/v1/webhooks/wh_abc123 -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "id":"wh_abc123",
  "url":"https://your-app.com/webhook",
  "events":["document.received"],
  "isActive":true,
  "failedAttempts":0,
  "createdAt":"2025-04-01T10:00:00.000Z",
  "deliveries":[{
    "id":"d1f2e3",
    "webhookId":"whk_5f6a7b",
    "event":"document.received",
    "status":"SUCCESS",
    "attempts":1,
    "responseStatus":200,
    "createdAt":"2025-04-01T10:00:00.000Z"
  }]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
PATCH/api/v1/webhooks/{id}

Upraviť webhook

Aktualizuje URL, udalosti alebo aktívny stav. Push URL musí byť HTTPS bez userinfo, query parametrov a fragmentu; autentizáciu zabezpečuje HMAC podpis v hlavičke. Všetky polia sú nepovinné.

Parametre

NázovTypPovinnéPopis
urlstringoptionalHTTPS URL
eventsstring[]optionalNove udalosti
isActivebooleanoptionalAktivovat/deaktivovat

Príklady volania

cURL
curl -X PATCH https://epostak.sk/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" -d '{"isActive":false}'

Príklady odpovedí

200 OK
{"id":"wh_abc123","url":"https://your-app.com/webhook","events":["document.received"],"isActive":false,"failedAttempts":0,"createdAt":"2025-04-01T10:00:00.000Z"}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
  • 422Validation Error
DELETE/api/v1/webhooks/{id}

Zmazať webhook

Trvalo zmaze webhook a vsetky zaznamy o doruceni.

Príklady volania

cURL
curl -X DELETE https://epostak.sk/api/v1/webhooks/wh_abc123 -H "Authorization: Bearer eyJhbGc..."

Odpovede

  • 204No Content — webhook bol zmazaný
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
POST/api/v1/webhooks/{id}/test

Poslať testovaciu udalosť

Pošle testovaciu udalosť na URL webhooku s platným HMAC podpisom. Predvolený mode=direct odošle najviac 10 syntetických POSTov okamžite. mode=queued zaradí najviac 100 doručení do oddelenej diagnostickej fronty s najviac 3 pokusmi; odpoveď 202 obsahuje testRunId. Diagnostické požiadavky majú firm-wide kvótu a limit 20 čakajúcich doručení. URL sa pred testom znovu validuje. Platné typy: document.sent, document.received, document.delivered, document.delivery_failed, document.rejected, document.response_received.

Parametre

NázovTypPovinnéPopis
eventstringoptionalQuery param (preferred) or body field. Valid values: document.sent | document.received | document.delivered | document.delivery_failed | document.rejected | document.response_received. Default: document.sent. (default: document.sent) (povolené: document.sent, document.received, document.delivered, document.delivery_failed, document.rejected, document.response_received)
countintegeroptionalQuery param or body field. Number of synthetic webhook POSTs. Valid range: 1..10 for direct mode and 1..100 for queued mode. Default: 1. (default: 1)
modestringoptionaldirect sends immediately and waits for aggregate results. queued creates delivery rows for the isolated diagnostic worker with at most 3 attempts. Valid: direct | queued. Default: direct. (default: direct) (povolené: direct, queued)

Príklady volania

cURL 1
# Preferred: pass event as query parameter (PR #114)
curl -X POST "https://epostak.sk/api/v1/webhooks/wh_abc123/test?event=document.received" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK (200 sa vráti aj keď testovacie doručenie zlyhá — skontrolujte pole success a error)
{"success":true,"statusCode":200,"responseTime":142,"webhookId":"whk_test_5f6a","event":"document.sent","requested":1,"sent":1,"succeeded":1,"failed":0}
202 Queued test accepted. Poll deliveriesUrl or GET /webhooks/{id}/deliveries?testRunId=... for worker results.
{"success":true,"mode":"queued","testRunId":"wht_5f6a7b","event":"document.received","requested":20,"queued":20,"deliveryIdsTruncated":false,"deliveriesUrl":"/api/v1/webhooks/wh_abc123/deliveries?testRunId=wht_5f6a7b"}

Odpovede

  • 200OK (200 sa vráti aj keď testovacie doručenie zlyhá — skontrolujte pole success a error)
  • 202Queued test accepted. Poll deliveriesUrl or GET /webhooks/{id}/deliveries?testRunId=... for worker results.
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
  • 422Validation Error
GET/api/v1/webhooks/{id}/deliveries

História doručení

Stránkovaná história pokusov o doručenie pre jeden webhook — status kódy, odpovede, počet pokusov, čas ďalšieho opakovania. Užitočné pri debuggovaní.

Parametre

NázovTypPovinnéPopis
limitnumberoptional1–100 (default: 20)
offsetnumberoptionalZačiatok od (predvolene 0) (default: 0)
cursorstringoptionalOpaque cursor from nextCursor in the previous response. Use instead of offset for stable pagination over large history.
statusstringoptionalPENDING | SUCCESS | FAILED | RETRYING (povolené: PENDING, SUCCESS, FAILED, RETRYING)
eventstringoptionalFilter podľa typu udalosti
testRunIdstringoptionalFilter deliveries created by POST /webhooks/{id}/test?mode=queued.
includeResponseBodybooleanoptionalWhen true, includes the responseBody field. Requires documents:read in addition to webhooks:read because receivers may reflect document data. Omitted by default. Alias: include=responseBody. (default: false)

Príklady volania

cURL 1
curl "https://epostak.sk/api/v1/webhooks/wh_abc123/deliveries?status=FAILED&limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "deliveries": [{
    "id":"d1f2e3",
    "webhookId":"whk_5f6a7b",
    "event":"document.received",
    "status":"SUCCESS",
    "attempts":1,
    "responseStatus":200,
    "lastAttemptAt":"2025-04-01T10:00:15.000Z",
    "nextRetryAt":null,
    "createdAt":"2025-04-01T10:00:00.000Z"
  }],
  "total":142,
  "limit":20,
  "offset":0,
  "nextCursor": null
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
GET/api/v1/webhook-dead-letter

Webhook dead-letter queue

Vracia nevyriešené terminálne zlyhané push doručenia naprieč webhookmi vašej firmy. Použite na ERP runbooky: čo treba replaynúť alebo manuálne označiť ako vyriešené.

Parametre

NázovTypPovinnéPopis
limitnumberoptional1–100 (default: 20)
offsetnumberoptionalZačiatok od (predvolene 0) (default: 0)
eventstringoptionalFilter podľa typu udalosti
subscriptionIdstringoptionalFilter na konkrétnu webhook subscription
includeResponseBodybooleanoptionalAk true, vráti aj poslednú odpoveď ERP endpointu; vyžaduje aj documents:read. (default: false)

Príklady volania

cURL
curl "https://epostak.sk/api/v1/webhook-dead-letter?includeResponseBody=true&limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "items": [{
    "id": "22222222-2222-2222-2222-222222222222",
    "webhookId": "whk_5f6a7b",
    "webhookEventId": "55555555-5555-5555-5555-555555555555",
    "event": "document.sent",
    "status": "FAILED",
    "attempts": 10,
    "responseStatus": 503,
    "responseBody": "Receiver unavailable",
    "lastAttemptAt": "2026-05-17T10:01:00.000Z",
    "nextRetryAt": null,
    "createdAt": "2026-05-17T10:00:00.000Z"
  }],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
POST/api/v1/webhook-dead-letter/{deliveryId}/replay

Replay zlyhaného webhooku

Vytvorí nové PENDING doručenie z pôvodného FAILED riadku a zaradí ho do webhook queue. Pôvodný riadok ostáva v audite a označí sa ako vyriešený replayom. webhook_event_id ostáva rovnaký, webhook_id je nový per-delivery identifikátor.

Parametre

NázovTypPovinnéPopis
deliveryIdstringREQID z GET /api/v1/webhook-dead-letter

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/webhook-dead-letter/22222222-2222-2222-2222-222222222222/replay \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

202 Accepted
{"replayedFrom":"22222222-2222-2222-2222-222222222222","deliveryId":"77777777-7777-7777-7777-777777777777","webhookId":"whk_9a8b7c","webhookEventId":"55555555-5555-5555-5555-555555555555"}

Odpovede

  • 202Accepted
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
  • 422Validation Error
POST/api/v1/webhook-dead-letter/{deliveryId}/resolve

Označiť webhook zlyhanie ako vyriešené

Skryje zlyhané doručenie z dead-letter queue bez mazania alebo prepisovania auditu. Použite, keď bol stav vyriešený manuálne v ERP alebo už netreba replay.

Parametre

NázovTypPovinnéPopis
deliveryIdstringREQID z GET /api/v1/webhook-dead-letter
reasonstringoptionalKrátka poznámka, max 500 znakov

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/webhook-dead-letter/22222222-2222-2222-2222-222222222222/resolve \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"reason":"Handled in ERP manually"}'

Príklady odpovedí

200 OK
{"resolved":true}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
POST/api/v1/webhooks/{id}/rotate-secret

Rotovať podpisový secret

Vygeneruje nový podpisový secret pre webhook a okamžite zneplatní predchádzajúci. Nový secret sa vráti iba raz — uložte si ho. Existujúce in-flight doručenia podpísané starým secretom prestanú byť overiteľné.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/webhooks/wh_abc123/rotate-secret \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{"id":"wh_abc123","secret":"whsec_new_...","message":"Secret rotated. Save it — it will not be shown again. The previous secret is now invalid."}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
GET/api/v1/events/pull

Stiahnuť udalosti

Vráti nepotvrdené pull udalosti (oldest-first). Fronta je forward-only a obsahuje udalosti vytvorené počas aktívnej pull subscription. Po lokálnom uložení v ERP potvrďte každú udalosť cez POST /api/v1/events/{eventId}/ack alebo ich potvrďte naraz cez POST /api/v1/events/batch-ack.

Parametre

NázovTypPovinnéPopis
limitintegeroptionalMax 100 (default: 20)
event_typestringoptionalFilter podľa typu udalosti

Príklady volania

cURL
curl "https://epostak.sk/api/v1/events/pull?limit=10" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "events": [{
    "event_id": "11111111-1111-1111-1111-111111111111",
    "firm_id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "event": "document.received",
    "created_at": "2026-05-12T10:00:00.000Z",
    "payload": {
      "event": "document.received",
      "event_version": "1",
      "webhook_id": null,
      "webhook_event_id": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-05-12T10:00:00.000Z",
      "data": {
        "document_id": "d8f6dfa3-d76a-4278-8464-936741e1c0e1",
        "document_number": "e-FV-dev-2026-1010",
        "direction": "inbound",
        "doctype_key": "invoice",
        "status": "received",
        "previous_status": null,
        "total_amount": "409.59",
        "currency": "EUR",
        "issue_date": "2026-05-10",
        "due_date": "2026-05-24",
        "sender_peppol_id": "0245:1122334455",
        "receiver_peppol_id": "0245:0000000001",
        "received_at": "2026-05-12T10:00:00.000Z"
      }
    }
  }],
  "has_more": false
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
POST/api/v1/events/{eventId}/ack

Potvrdiť event

Označí jednotlivú pull udalosť ako spracovanú a vráti 200 s telom { acknowledged: true }. Ack vykonajte až po lokálnom commite v ERP.

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/events/11111111-1111-1111-1111-111111111111/ack \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{ "acknowledged": true }

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
POST/api/v1/events/batch-ack

Batch potvrdenie eventov

Hromadne potvrdí najviac 1000 pull udalostí po ich lokálnom spracovaní. Vráti 200 s telom { acknowledged: N }.

Parametre

NázovTypPovinnéPopis
event_idsstring[]REQPole ID udalosti max 1000

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/events/batch-ack \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"event_ids":["11111111-1111-1111-1111-111111111111","22222222-2222-2222-2222-222222222222"]}'

Príklady odpovedí

200 OK
{ "acknowledged": 2 }

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 422Validation Error
GET/api/v1/webhook-queue/all

Cross-firm webhook queue

Vráti webhook udalosti naprieč všetkými spravovanými firmami. Vyžaduje JWT získané zo sk_int_* kľúča. Auth: withIntegratorNoFirm — sk_int_* povinné, X-Firm-Id sa ignoruje. Endpoint číta iba pull queue riadky z aktívnych pull-only subscriptionov (url = null); push webhook subscriptiony ani samotné webhooks:read oprávnenie queue nenapĺňajú. Pre nové ERP integrácie odporúčame Connector events s customerRef; tento Enterprise endpoint zostáva podporovaný.

Parametre

NázovTypPovinnéPopis
limitnumberoptionalMax výsledkov (default 100, max 500) (default: 100)
sincestringoptionalISO 8601 — filter udalostí vytvorených po tomto čase

Príklady odpovedí

200 OK
{
  "items": [{
    "event_id": "11111111-1111-1111-1111-111111111111",
    "firm_id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "event": "document.received",
    "payload": {
      "event": "document.received",
      "event_version": "1",
      "webhook_id": null,
      "webhook_event_id": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-05-12T10:00:00.000Z",
      "data": {
        "document_id": "d8f6dfa3-d76a-4278-8464-936741e1c0e1",
        "document_number": "e-FV-dev-2026-1010",
        "direction": "inbound",
        "doctype_key": "invoice",
        "status": "received",
        "previous_status": null,
        "total_amount": "409.59",
        "currency": "EUR",
        "issue_date": "2026-05-10",
        "due_date": "2026-05-24",
        "sender_peppol_id": "0245:1122334455",
        "receiver_peppol_id": "0245:0000000001",
        "received_at": "2026-05-12T10:00:00.000Z"
      }
    },
    "created_at": "2026-05-12T10:00:00.000Z"
  }],
  "has_more": false
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden — caller is not an sk_int_* integrator
POST/api/v1/webhook-queue/all/batch-ack

Hromadné potvrdenie udalostí

Hromadné potvrdenie webhook udalostí naprieč všetkými firmami.

Parametre

NázovTypPovinnéPopis
event_idsstring[]REQPole ID udalostí na potvrdenie (UUID, max 1000)

Príklady odpovedí

200 OK
{
  "acknowledged": 5
}

Odpovede

  • 200OK
  • 400Bad Request
  • 401Unauthorized

Peppol

Vyhľadávanie v Peppol sieti — SMP lookup, adresár, overenie firmy a jej schopností.

Authoritative checks

Pred sendom overte presného účastníka a document type cez SMP/capability flow.

  • SMP lookup je pre presné Peppol ID.
  • Capabilities vracajú networkReady a matchedDocumentTypes.
CapabilitiesParticipant lookup

Discovery vs routing

Directory search pomáha nájsť firmu; send rozhodnutie robte až po capability/preflight.

  • Adresár môže byť neúplný alebo oneskorený.
  • Preflight je finálna kontrola pred ostrým sendom.
DirectoryPreflight
GET/api/v1/peppol/participants/{scheme}/{identifier}

SMP capability lookup

Overí, či je účastník registrovaný v Peppol sieti a či prijíma predvolenú BIS Billing faktúru. Účastník bez invoice capability sa vráti ako found:true, accepts:false.

Parametre

NázovTypPovinnéPopis
schemestringREQ4-ciferný ISO 6523 kód napr. 0245
identifierstringREQIdentifikátor účastníka

Príklady volania

cURL
curl https://epostak.sk/api/v1/peppol/participants/0245/2020298610 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Found; accepts may be false when the participant is registered but cannot receive the default invoice capability
{
  "found": true,
  "accepts": true,
  "routingStatus": "ready",
  "participantId": "0245:2020298610",
  "scheme": "0245",
  "identifier": "2020298610",
  "accessPoint": {
    "url": "https://ap.provider.com/as4",
    "transportProfile": "peppol-transport-as4-v2_0"
  },
  "certificate": {"present": true, "valid": true},
  "supportedDocumentTypes": ["urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."],
  "source": "sml"
}

Odpovede

  • 200Found; accepts may be false when the participant is registered but cannot receive the default invoice capability
  • 400Invalid params
  • 401Unauthorized
  • 404Participant not found in Peppol
  • 503Temporary SMP/SML lookup failure; retry later
GET/api/v1/peppol/participants/resolve

Resolve firmy na Peppol účastníka

Jednokrokový lookup pre ERP integrácie: prijme práve jeden identifikátor (`ico`, `dic`, `icDph`, `peppolId` alebo `scheme + identifier`), doplní firemné údaje z lokálnych registrov a hneď overí presnú Peppol routing capability pre zvolený `documentTypeId + processId`. Pre slovenské firmy vie z DIČ odvodiť kandidáta `0245:{dic}` aj vtedy, keď ešte nie je v Peppol directory. Použite ho pred preflight/send, ak ERP pozná IČO alebo DIČ, nie Peppol ID.

Parametre

NázovTypPovinnéPopis
icostringoptionalSlovak IČO, 6-8 digits. Mutually exclusive with other identifiers.
dicstringoptionalSlovak DIČ, 10 digits. Mutually exclusive with other identifiers.
icDphstringoptionalVAT ID, e.g. SK2020123456. Mutually exclusive with other identifiers.
peppolIdstringoptionalDirect Peppol participant ID, e.g. 0245:2020123456.
schemestringoptionalISO 6523 scheme when using scheme+identifier instead of peppolId.
identifierstringoptionalParticipant identifier when using scheme+identifier instead of peppolId.
documentTypeIdstringoptionalPeppol document-type URN. Default is BIS Billing 3.0 Invoice.
processIdstringoptionalPeppol process ID. Default is BIS Billing 3.0.

Príklady volania

cURL
curl "https://epostak.sk/api/v1/peppol/participants/resolve?ico=12345678" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "query": {"type":"ico","value":"12345678"},
  "nextAction": "sendable",
  "company": {
    "ico": "12345678",
    "dic": "2020123456",
    "icDph": "SK2020123456",
    "name": "Demo s.r.o.",
    "address": {"street":"Hlavna 1","city":"Bratislava","zip":"81101","country":"SK"},
    "active": true,
    "inPeppol": true,
    "source": "merged"
  },
  "participant": {
    "peppolId": "0245:2020123456",
    "scheme": "0245",
    "identifier": "2020123456",
    "registered": true,
    "source": "sml",
    "accessPoint": {"url":"https://ap.receiver.example/as4","transportProfile":"peppol-transport-as4-v2_0"},
    "certificate": {"present":true,"serviceExpirationDate":"2099-01-01T00:00:00Z"},
    "supportedDocumentTypes": ["urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."]
  },
  "capability": {
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##...",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "accepts": true,
    "routingStatus": "ready",
    "networkReady": true
  }
}

Odpovede

  • 200OK
  • 400Invalid or ambiguous query
  • 401Unauthorized
  • 403API plan required
  • 404Company or participant candidate not found
GET/api/v1/peppol/directory/search

Hľadať v adresári

Prehľadáva lokálnu kópiu Peppol adresára (3.6M+ záznamov). Fulltextové vyhľadávanie podľa názvu firmy alebo Peppol ID.

Parametre

NázovTypPovinnéPopis
qstringREQHľadaný výraz min 2 znaky
countrystringoptionalISO kod krajiny napr. SK
pageintegeroptionalStranka vysledkov
page_sizeintegeroptionalMax 50

Príklady volania

cURL
curl "https://epostak.sk/api/v1/peppol/directory/search?q=Kaja&country=SK" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "items": [{
    "participantId": "0245:2020298610",
    "name": "Kaja Solutions s.r.o.",
    "countryCode": "SK",
    "registrationDate": "2024-01-15"
  }],
  "page": 1,
  "page_size": 20,
  "has_next": false
}

Odpovede

  • 200OK
  • 400Query too short
  • 401Unauthorized
GET/api/v1/company/lookup/{ico}

Info o firme + Peppol status

Vyhľadá firmu podľa IČO v Registri Finančnej správy SR a skontroluje registráciu v Peppol sieti.

Príklady volania

cURL
curl https://epostak.sk/api/v1/company/lookup/52819886 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "ico": "52819886",
  "name": "Kaja Solutions s.r.o.",
  "address": {"street":"Hlavna 1","city":"Bratislava","zip":"811 01","country":"SK"},
  "dic": "2021234567",
  "icDph": "SK2021234567",
  "peppolRegistered": true,
  "peppolId": "0245:2021234567"
}

Odpovede

  • 200OK
  • 400Invalid ICO
  • 401Unauthorized
  • 404Not Found
POST/api/v1/peppol/capabilities

Zistiť podporované dokumenty

Sonduje Peppol SMP účastníka — vráti zoznam akceptovaných typov dokumentov a transportných profilov. Enterprise reliability contract začína tu: pred skladaním payloadu čítajte networkReady a matchedDocumentTypes, potom pokračujte preflightom, sendom, event pull/ack a support-packetom. Ak je zadaný documentType, vráti matchedDocumentType ako URN matchnutého typu (alebo null). Ak pošlete documentTypes[], endpoint spraví viac presných sond v jednom volaní a vráti capabilities[] + matchedDocumentTypes[].

Parametre

NázovTypPovinnéPopis
participantobjectREQObjekt { scheme, identifier }. scheme = 4-ciferný ISO 6523 kód (napr. 0245), identifier = identifikátor účastníka
documentTypestringoptionalKonkrétny Peppol document-type URN pre overenie
documentTypesarrayoptionalPole 1-20 Peppol document-type URN hodnôt pre batch capability probe. Ak je vyplnené, má prednosť pred documentType.
processIdstringoptionalVoliteľný BIS 3 process ID

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/peppol/capabilities \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"participant":{"scheme":"0245","identifier":"2020298610"},"documentType":"urn:cen.eu:en16931:2017"}'

Príklady odpovedí

200 OK
{
  "found": true,
  "accepts": true,
  "participant": {"scheme":"0245","identifier":"2020298610","id":"0245:2020298610"},
  "accessPoint": {"url":"https://ap.epostak.sk/as4","transportProfile":"peppol-transport-as4-v2_0"},
  "internal": true,
  "supportedDocumentTypes": [
    "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",
    "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##..."
  ],
  "matchedDocumentType": "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",
  "matchedDocumentTypes": [
    "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"
  ],
  "capabilities": [
    {
      "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##...",
      "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "found": true,
      "accepts": true,
      "routingStatus": "ready",
      "networkReady": true
    }
  ],
  "source": "smp"
}

Odpovede

  • 200OK
  • 400Invalid params
  • 401Unauthorized
  • 404Not Found (participant not registered in Peppol)
POST/api/v1/peppol/participants/batch

Hromadné overenie max 100

Hromadné overenie až 100 Peppol účastníkov a ich predvolenej BIS Billing invoice capability v jednom volaní. Registered-but-not-routable položky majú found:true, accepts:false. Dočasné lookup výpadky sú v lookupFailed, nie v notFound.

Parametre

NázovTypPovinnéPopis
participantsarrayREQPole max 100 položiek { scheme, identifier }

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/peppol/participants/batch \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"participants":[
    {"scheme":"0245","identifier":"2020298610"},
    {"scheme":"0245","identifier":"0000000001"}
  ]}'

Príklady odpovedí

200 OK
{
  "total": 2,
  "found": 2,
  "notFound": 0,
  "lookupFailed": 0,
  "results": [
    {"index":0,"participant":{"scheme":"0245","identifier":"2020298610","id":"0245:2020298610"},"found":true,"accepts":true,"routingStatus":"ready","accessPoint":{"url":"https://ap.epostak.sk/as4","transportProfile":"peppol-transport-as4-v2_0"},"internal":false,"supportedDocumentTypes":["..."],"source":"sml","temporaryFailure":false,"lookupFailed":false},
    {"index":1,"participant":{"scheme":"0245","identifier":"0000000001","id":"0245:0000000001"},"found":true,"accepts":false,"routingStatus":"document_type_not_supported","accessPoint":null,"internal":false,"supportedDocumentTypes":[],"source":"sml","temporaryFailure":false,"lookupFailed":false}
  ]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 422Validation Error
POST/api/validate

Peppol BIS 3.0 validácia (verejné)

Verejný nástroj — môžu ho volať aj neregistrovaní integrátori pred sign-upom. Bez autentifikácie. Rate-limit 20 požiadaviek za minútu na IP adresu. Maximum 2 MB. Vráti trojvrstvový Peppol BIS 3.0 validation report: (1) UBL 2.1 XSD, (2) EN 16931 sémantické pravidlá, (3) Peppol schematron.

Parametre

NázovTypPovinnéPopis
xmlstringREQUBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Príklady volania

cURL
curl -X POST https://epostak.sk/api/validate \
  -H "Content-Type: application/xml" \
  --data-binary "@invoice.xml"

Príklady odpovedí

200 OK
{
  "valid": false,
  "profile": "peppol-bis-billing-3.0",
  "layers": {
    "xsd": {"valid":true,"errors":[]},
    "en16931": {"valid":true,"errors":[]},
    "peppol": {"valid":false,"errors":[{"rule":"PEPPOL-EN16931-R053","location":"/Invoice/...","message":"Only one tax total..."}]}
  },
  "errorCount": 1,
  "warningCount": 0
}

Odpovede

  • 200OK
  • 400Invalid XML
  • 413Too Large
  • 429Rate Limited

Firmy

Správa firiem priradených k vášmu integrátorskému účtu. Existujúci Enterprise kontrakt používa sk_int_* JWT, aktívny súhlas a X-Firm-Id na firm-scoped volaniach; Connector je additívny customerRef flow.

Managed firms

Toto je partner/admin vrstva pre integrátorov, ktorí spravujú viac klientov.

  • Ak si klient zvolil ePošťák, firma sa priraďuje po súhlase vlastníka. Ak si zvolil schváleného White Label poskytovateľa, participant sa zapisuje cez /white-label/participants/registrations s verification_token z provider webhooku FS SR a bez účtu ePošťák.
  • X-Firm-Id určuje cieľovú firmu pri sk_int_* Enterprise firm-scoped volaniach; Connector používa customerRef.
List firmsWhite Label registráciaVytvoriť súhlasStav súhlasuAssignKeys

Access boundaries

Admin endpointy nikdy nemajú byť skratka na claimnutie cudzej firmy bez jej vedomia.

  • Audit a licenses držia prevádzkovú stopu partnera.
  • Plaintext secret sa nikdy nevracia opakovane.
AuditLicencie
GET/api/v1/firms

Zoznam prístupných firiem

Pre sk_int_* kľúče vráti všetky firmy prepojené cez IntegratorFirm. Pre sk_live_* kľúče vráti iba vlastnú firmu.

Príklady volania

cURL
curl https://epostak.sk/api/v1/firms \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{"firms":[{"id":"firm_abc123","name":"Klient s.r.o.","ico":"12345678","peppolId":"0245:0000000001","peppolStatus":"active"}]}

Odpovede

  • 200OK
  • 401Unauthorized
GET/api/v1/white-label/participants

Zoznam spravovaných participantov

Vráti iba participantov priradených prihlásenému White Label integrátorovi. Vyžaduje scope participants:read. Ide o control-plane volanie bez X-Firm-Id.

Parametre

NázovTypPovinnéPopis
limitnumberoptionalPočet výsledkov, 1 až 100 (predvolene 50)
cursorstringoptionalOpaque kurzor z predchádzajúcej odpovede

Príklady volania

cURL
curl "https://epostak.sk/api/v1/white-label/participants?limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{"participants":[{"id":"56c3f40a-2bd8-44b8-9bbc-3e044cdf4a40","customerRef":"klient-001","firmId":"b1022d80-5016-4dad-a8d2-53685cab1701","operationId":"286f34ec-553b-48ec-bfef-71e6e1222041","legalName":"Klient s.r.o.","ico":"12345678","dic":"2020123456","icDph":"SK2020123456","peppolId":"0245:2020123456","status":"registered","authorizationSource":"fs_verification_token","endpointProfile":"managed_by_epostak","managedSince":"2026-08-17T10:00:00.000Z"}],"nextCursor":null}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403White Label alebo scope nie je aktívny
POST/api/v1/white-label/participants/registrations

Registrovať participanta z webhooku FS SR

Použite verification_token prijatý na vašom podpísanom provider webhooku FS SR. ePošťák ho odošle do SMP ako dic_verification_code a uloží iba jeho hash. Firma a väzba na vás vzniknú až po úspešnej odpovedi SMP. Konflikt 409 vlastníctvo nepotvrdzuje. Neposielajte X-Firm-Id.

Hlavičky

NázovTypPovinnéPopis
Idempotency-KeystringREQRovnaký kľúč a telo používajte pri opakovaní; pri 202 nevytvárajte nový kľúč

Parametre

NázovTypPovinnéPopis
customerRefstringREQStabilná referencia klienta vo vašom systéme
dicstringREQPresne 10 číslic
companyEmailstringREQKontaktný email z provider toku
verificationTokenstringREQTajný token z webhooku FS SR; nikdy ho nelogujte

Príklady volania

cURL
curl -X POST "https://epostak.sk/api/v1/white-label/participants/registrations" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Idempotency-Key: fs-aktivacia-2020123456-1" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"klient-001","dic":"2020123456","companyEmail":"fakturacia@klient.sk","verificationToken":"TOKEN_Z_FS_SR"}'

Príklady odpovedí

201 SMP zápis a lokálna väzba uspeli
{"id":"286f34ec-553b-48ec-bfef-71e6e1222041","operationType":"registration","status":"succeeded","customerRef":"klient-001","dic":"2020123456","peppolId":"0245:2020123456","legalName":"Klient s.r.o.","companyEmail":"fakturacia@klient.sk","firmId":"b1022d80-5016-4dad-a8d2-53685cab1701","participantId":"56c3f40a-2bd8-44b8-9bbc-3e044cdf4a40","reviewRequired":false,"error":null,"createdAt":"2026-08-17T10:00:00.000Z","completedAt":"2026-08-17T10:00:01.000Z"}

Odpovede

  • 201SMP zápis a lokálna väzba uspeli
  • 200Idempotentné opakovanie
  • 202Výsledok sa kontroluje; sledujte Location a nepoužite nový idempotency key
  • 409Participant už existuje alebo patrí inému toku
  • 422SMP odmietlo token alebo register neoveril firmu
POST/api/v1/white-label/participants/migrations

Prevziať participanta migračným kódom

Použije SMP migračný kód od aktuálneho poskytovateľa. Kód sa neukladá v čitateľnej podobe a väzba na integrátora vznikne až po potvrdení SMP. Vyžaduje participants:migrate.

Hlavičky

NázovTypPovinnéPopis
Idempotency-KeystringREQPovinný jedinečný kľúč operácie

Parametre

NázovTypPovinnéPopis
customerRefstringREQReferencia klienta
dicstringREQPresne 10 číslic
companyEmailstringREQKontaktný email
migrationCodestringREQTajný SMP migračný kód

Príklady volania

cURL
curl -X POST "https://epostak.sk/api/v1/white-label/participants/migrations" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Idempotency-Key: migracia-2020123456-1" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"klient-001","dic":"2020123456","companyEmail":"fakturacia@klient.sk","migrationCode":"MIGRACNY_KOD"}'

Odpovede

  • 201Migrácia a lokálna väzba uspeli
  • 202Výsledok vyžaduje kontrolu
  • 409Konflikt vlastníctva alebo idempotencie
  • 422SMP odmietlo migračný kód
POST/api/v1/white-label/participants/{participantId}/migration-code

Vyžiadať kód pre odchod participanta

Kód možno vyžiadať iba pre participanta, ktorého spravuje prihlásený integrátor. ePošťák ho neukladá čitateľne. Vyžiadanie kódu ešte neuvoľní vlastníctvo; to nastane až po potvrdenom prevzatí v SMP.

Hlavičky

NázovTypPovinnéPopis
Idempotency-KeystringREQPovinný jedinečný kľúč operácie

Parametre

NázovTypPovinnéPopis
participantIduuidREQInterné ID z White Label participant listu

Príklady volania

cURL
curl -X POST "https://epostak.sk/api/v1/white-label/participants/56c3f40a-2bd8-44b8-9bbc-3e044cdf4a40/migration-code" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Idempotency-Key: odchod-56c3f40a-1"

Príklady odpovedí

201 Kód bol vydaný
{"operation":{"id":"31f9cf79-cc49-4db7-a356-595d63666bf8","operationType":"migration_out","status":"succeeded"},"migrationCode":"MIGRACNY_KOD"}

Odpovede

  • 201Kód bol vydaný
  • 404Participant nepatrí integrátorovi
  • 409Kód už nie je zo SMP dostupný
GET/api/v1/firms/{id}

Detail firmy

Vráti úplný detail firmy vrátane adresy, DIČ, IČ DPH a Peppol stavu.

Príklady volania

cURL
curl https://epostak.sk/api/v1/firms/firm_abc123 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "id": "firm_abc123",
  "name": "Klient s.r.o.",
  "ico": "12345678",
  "dic": "2021234567",
  "icDph": "SK2021234567",
  "address": {"street":"Hlavna 1","city":"Bratislava","zip":"811 01"},
  "peppolId": "0245:0000000001",
  "peppolStatus": "active",
  "plan": "api-enterprise",
  "createdAt": "2025-01-01T00:00:00.000Z"
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
GET/api/v1/firms/{id}/documents

Dokumenty firmy

Vráti stránkovaný zoznam dokumentov firmy. Partner môže pristupovať iba k dokumentom firmy, ktorá mu udelila aktívny súhlas, a iba od času vzniku prepojenia. Priame firemné prihlásenie bez partnerského kontextu zobrazí všetky dokumenty firmy.

Parametre

NázovTypPovinnéPopis
pageintegeroptionalStranka (default: 1)
page_sizeintegeroptionalMax 100 (default: 20)
directionstringoptionalinbound | outbound (povolené: inbound, outbound)
statusstringoptionalFilter podľa stavu
fromstringoptionalISO 8601 date
tostringoptionalISO 8601 date

Príklady volania

cURL
curl "https://epostak.sk/api/v1/firms/firm_abc123/documents?direction=inbound&page=1" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{"documents":[{"id":"clx9abc123","status":"RECEIVED","direction":"inbound"}],"pagination":{"total":42,"page":1,"pageSize":20,"totalPages":3}}

Odpovede

  • 200OK
  • 400Validation Error
  • 401Unauthorized
  • 403Forbidden
POST/api/v1/firms/{id}/peppol-identifiers

Registrovat Peppol ID

Zaregistruje Peppol ID pre firmu. Registrácia v SMP prebehne do 24 hodín. Pre scheme 0245 (slovensky DIC) musi byt pole identifier zhodne s hodnotou firm.dic. Nesulad vrati 422 VALIDATION_ERROR. Pre ine schemy (0007, 0184 atd.) prebehne len formatova validacia.

Parametre

NázovTypPovinnéPopis
schemestringREQISO 6523 kód napr. 0245
identifierstringREQIdentifikátor firmy. Pre scheme 0245 musí byť rovný firm.dic (slovenské DIČ, NIE IČO).

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/firms/firm_abc123/peppol-identifiers \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"scheme":"0245","identifier":"2020298610"}'

Príklady odpovedí

201 Created
{
  "peppolId": "0245:2020298610",
  "registrationStatus": "pending",
  "message": "Peppol ID registration requested. We will register you in SMP within 24 hours."
}

Odpovede

  • 201Created
  • 400Validation Error
  • 401Unauthorized
  • 403Forbidden
  • 404Firm not found
POST/api/v1/firms/consent-link

Vytvoriť odkaz na súhlas firmy

Vytvorí nový jednorazový odkaz na súhlas pre presne jedno DIČ alebo IČO. Odkaz je určený pre Enterprise API a rozsah preto musí obsahovať firms:manage aj aspoň jedno oprávnenie documents:*. API iba vytvorí pozvánku; súhlas musí po prihlásení udeliť vlastník alebo admin cieľovej firmy. Každé úspešné volanie vytvorí nový odkaz, ktorý sa vráti iba raz. Vyžaduje JWT získané z aktívneho sk_int_* kľúča s oprávnením firms:manage; neposielajte X-Firm-Id.

Parametre

NázovTypPovinnéPopis
dicstringoptionalDIČ firmy (10 číslic); pošlite práve jedno z dic alebo ico
icostringoptionalIČO firmy (8 číslic); pošlite práve jedno z dic alebo ico
customer_referencestringoptionalVaša referencia klienta (max. 120 znakov)
scopesstring[]REQRozsah súhlasu; povinne firms:manage a aspoň jedno documents:*

Príklady volania

cURL
curl -X POST "https://epostak.sk/api/v1/firms/consent-link" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"dic":"2022988022","customer_reference":"BUGLO-001","scopes":["firms:manage","documents:send","documents:read"]}'

Príklady odpovedí

201 Created — nový jednorazový odkaz
{
  "id": "49702ea6-41bf-47ef-9cb6-657450fdb299",
  "consent_url": "https://epostak.sk/auth/integrator-consent?token=...",
  "customer_reference": "BUGLO-001",
  "integration_path": "enterprise_api",
  "requested_interfaces": ["enterprise_api"],
  "scopes": ["documents:read", "documents:send", "firms:manage"],
  "status": "issued",
  "expires_at": "2026-08-18T10:00:00.000Z",
  "created_at": "2026-08-11T10:00:00.000Z"
}

Odpovede

  • 201Created — nový jednorazový odkaz
  • 400Bad Request — neplatné JSON telo
  • 401Unauthorized — chýba alebo je neplatné JWT
  • 403Forbidden — token nemá firms:manage
  • 409Conflict — zmluva, oprávnenie alebo billing nie sú aktívne
  • 422Validation Error — identifikátor alebo scopes sú neplatné
  • 503Service Unavailable
GET/api/v1/firms/consent-status

Stav súhlasu firmy

Read-only kontrola stavu integrátorského súhlasu firmy podľa DIČ alebo IČO. Stav active sa vráti iba vtedy, keď aktívna a neodvolaná väzba oprávňuje aktuálne Enterprise API cez platný typ vzťahu a obsahuje oprávnenie firms:manage. Nezhodná väzba sa pravdivo vráti ako required s next_action=request_integrator_reconsent, dôvodom a požadovaným rozhraním; endpoint väzbu automaticky nemení. Pri required/revoked vytvorte nový odkaz cez POST /api/v1/firms/consent-link a pošlite ho vlastníkovi alebo adminovi klienta. Pri pending čakajte na jeho prijatie. V dev sandboxe odpoveď rozlišuje samotné vytvorenie testovacej firmy od dokončeného OAuth testu vlastníka, ale ani dokončený OAuth test neprekryje nezhodu rozhrania. Vyžaduje sk_int_* JWT s oprávnením firms:manage, bez X-Firm-Id.

Parametre

NázovTypPovinnéPopis
dicstringoptionalDIČ firmy (10 číslic), preferované
icostringoptionalIČO firmy (8 číslic), fallback

Príklady volania

cURL
curl "https://epostak.sk/api/v1/firms/consent-status?dic=2122701339" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK — consent_status: active | pending | revoked | required
{
  "identifier": { "dic": "2122701339" },
  "firm": {
    "id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "name": "Kaja Solutions s.r.o.",
    "ico": "52345678",
    "dic": "2122701339",
    "peppol_id": "0245:2122701339",
    "peppol_status": "active"
  },
  "consent_status": "pending",
  "assign_status": "consent_required",
  "next_action": "await_consent_acceptance",
  "environment": "production",
  "consent_flow": "owner_consent"
}
200 OK — firma existuje, ale súhlas integrátorovi chýba
{
  "identifier": { "ico": "52345678" },
  "firm": {
    "id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "name": "Kaja Solutions s.r.o.",
    "ico": "52345678",
    "dic": "2122701339",
    "peppol_id": "0245:2122701339",
    "peppol_status": "active"
  },
  "consent_status": "required",
  "assign_status": "consent_required",
  "next_action": "request_integrator_consent"
}
200 OK — aktívna väzba neoprávňuje aktuálne Enterprise API; vyžaduje sa nový súhlas
{
  "identifier": { "dic": "2122701339" },
  "firm": { "id": "b1022d80-5016-4dad-a8d2-53685cab1701", "name": "Kaja Solutions s.r.o.", "ico": "52345678", "dic": "2122701339", "peppol_id": "0245:2122701339", "peppol_status": "active" },
  "consent_status": "required",
  "assign_status": "consent_required",
  "next_action": "request_integrator_reconsent",
  "reason": "interface_mismatch",
  "required_interface": "enterprise_api",
  "required_scopes": ["firms:manage"]
}
404 Not Found — firma ešte nie je v ePošťák registri
{
  "error": {
    "code": "FIRM_NOT_REGISTERED",
    "message": "Firm is not registered in ePošťák yet.",
    "docs": "/api/docs/enterprise#ep-firms-consent-status"
  }
}

Odpovede

  • 200OK — consent_status: active | pending | revoked | required
  • 200OK — firma existuje, ale súhlas integrátorovi chýba
  • 200OK — aktívna väzba neoprávňuje aktuálne Enterprise API; vyžaduje sa nový súhlas
  • 400Bad Request — pošlite dic alebo ico v správnom formáte
  • 401Unauthorized
  • 403Forbidden — missing firms:manage scope
  • 404Not Found — firma ešte nie je v ePošťák registri
POST/api/v1/firms/assign

Priradiť firmu podľa DIČ alebo IČO

Aktivuje iba existujúcu väzbu firmy v stave pending podľa DIČ alebo IČO. DIČ je primárny identifikátor pre PFS/SMP a Peppol ID 0245:DIČ; IČO zostáva podporované kvôli lookupu a spätnej kompatibilite. Vyžaduje JWT získané z sk_int_* kľúča. Odpoveď 409 „firma je už priradená“ sa vráti iba pre aktívnu väzbu, ktorá oprávňuje Enterprise API cez platný vzťah a obsahuje firms:manage. Nezhoda rozhrania alebo vzťahu vráti 403 API_INTERFACE_NOT_AUTHORIZED. Stav FIRM_ACTIVATION_PENDING znamená, že oprávnenie alebo zmenu platcu dokončuje osobitný proces. Endpoint existujúcu väzbu, jej integračnú cestu ani riadený aktivačný stav automaticky nemení. DÔLEŽITÉ: Pre novú alebo odvolanú produkčnú firmu vytvorte jednorazový odkaz cez POST /api/v1/firms/consent-link. Vlastník alebo admin firmy v ňom potvrdí presné oprávnenia a systém uloží nemenný KYC dôkaz. Sandboxový OAuth súhlas vzniká iba pre už aktívnu spravovanú testovaciu firmu a samotné prepojenie nevytvára ani neobnovuje. Stav overíte cez GET /api/v1/firms/consent-status; plán firmy sám osebe nie je súhlas konkrétnemu integrátorovi.

Parametre

NázovTypPovinnéPopis
dicstringoptionalDIČ firmy (10 číslic), preferované
icostringoptionalIČO firmy (8 číslic), fallback

Príklady odpovedí

201 Created
{
  "firm": {
    "id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "name": "Kaja Solutions s.r.o.",
    "ico": "52345678",
    "dic": "2122701339",
    "peppol_id": "0245:2122701339",
    "peppol_status": "active"
  },
  "status": "active"
}
403 Forbidden — CONSENT_REQUIRED alebo API_INTERFACE_NOT_AUTHORIZED
{
  "error": {
    "code": "CONSENT_REQUIRED",
    "message": "First-time firm claim requires an accepted owner/admin integrator consent request.",
    "docs": "/api/docs/enterprise#ep-firms-consent-status"
  }
}

Odpovede

  • 201Created
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden — CONSENT_REQUIRED alebo API_INTERFACE_NOT_AUTHORIZED
  • 404Not Found
  • 409Conflict — already assigned, agreement required, or FIRM_ACTIVATION_PENDING
  • 422Validation Error
POST/api/v1/firms/assign/batch

Hromadné priradenie firiem

Hromadne aktivuje až 50 už oprávnených firiem s väzbou v stave pending podľa DIČ alebo IČO. Preferujte `dics`; `icos` držíme kvôli spätnej kompatibilite. Výsledok already_assigned sa vráti iba pre aktívnu väzbu oprávňujúcu Enterprise API cez platný vzťah a s firms:manage. Nezhoda sa vráti pri konkrétnej položke ako API_INTERFACE_NOT_AUTHORIZED s dôvodom a požadovaným rozhraním. FIRM_ACTIVATION_PENDING znamená, že položku dokončuje riadený proces oprávnenia alebo zmeny platcu. Väzba ani jej stav sa automaticky neprepíšu. Pre novú alebo odvolanú firmu vytvorte nový odkaz cez POST /api/v1/firms/consent-link a pošlite ho vlastníkovi alebo adminovi. OAuth tento súhlas nevytvára ani neobnovuje.

Parametre

NázovTypPovinnéPopis
dicsstring[]optionalPole DIČ (max 50), preferované
icosstring[]optionalPole IČO (max 50), fallback

Príklady odpovedí

200 OK
{
  "results": [
    { "identifier":"2122701339", "dic":"2122701339", "firm":{"id":"b1022d80-5016-4dad-a8d2-53685cab1701","name":"Kaja Solutions s.r.o.","ico":"52345678","dic":"2122701339","peppol_id":"0245:2122701339","peppol_status":"active"}, "status":"active" },
    { "ico":"99887766", "error":"NOT_FOUND", "message":"No firm with ICO 99887766" },
    { "ico":"11223344", "error":"API_INTERFACE_NOT_AUTHORIZED", "message":"Firm consent does not authorize Enterprise API through the current partner relationship.", "reason":"interface_mismatch", "required_interface":"enterprise_api", "required_scopes":["firms:manage"] }
  ]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 422Validation Error
GET/api/v1/integrator/keys

Zoznam integrátorských kľúčov

Vráti integrátorské API kľúče pre aktuálny sk_int_* JWT. Bez X-Firm-Id — endpoint je na úrovni integrátora. Firemné sk_live_* kľúče vydané cez /api/oauth/token sa v tomto zozname nezobrazujú.

Príklady volania

cURL
curl https://epostak.sk/api/v1/integrator/keys \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "keys": [{
    "id": "11111111-1111-4111-8111-111111111111",
    "keyPrefix": "sk_int_xxxxx...abcd",
    "name": "OAuth: BNS Sandbox firma 1",
    "scopes": ["firms:manage","documents:send","documents:read"],
    "ipAllowlist": [],
    "isActive": true,
    "lastUsedAt": null,
    "createdAt": "2026-05-22T10:00:00.000Z"
  }]
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden — missing firms:manage scope
DELETE/api/v1/integrator/keys

Zneplatniť integrátorský kľúč

Zneplatní aktívny integrátorský API kľúč podľa keyId z GET /api/v1/integrator/keys. Endpoint nenechá zneplatniť posledný aktívny kľúč integrátora.

Parametre

NázovTypPovinnéPopis
keyIduuidoptionalUUID kľúča z GET /api/v1/integrator/keys
client_idstringoptionalsk_int_* keyPrefix existujúceho integrátorského kľúča

Príklady volania

cURL
curl -X DELETE https://epostak.sk/api/v1/integrator/keys \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"client_id":"sk_int_xxxxx...abcd"}'

Príklady odpovedí

200 OK
{
  "success": true,
  "message": "API key deactivated."
}

Odpovede

  • 200OK
  • 400Bad Request — invalid body, already inactive, or last active key
  • 401Unauthorized
  • 403Forbidden — missing firms:manage scope
  • 404API key not found
GET/api/v1/integrator/licenses/info

Plán a agregovaná spotreba

Vráti plán integrátora, spotrebu za aktuálne fakturačné obdobie naprieč všetkými spravovanými firmami, presnú podpísanú cenovú snímku a odhadovaný náklad. Odoslané a prijaté dokumenty sa pásmujú samostatne; od 20 001 dokumentov v danom smere platí sadzba 0,04 € bez individuálnej objednávky. Vyžaduje sk_int_* kľúč a scope account:read. Bez X-Firm-Id hlavičky — endpoint je integrátorský, nie firemný.

Parametre

NázovTypPovinnéPopis
offsetintegeroptionalPosun pre stránkovanie zoznamu firiem (default: 0)
limitintegeroptionalMax 100 — počet firiem v firms (default: 50)
periodstringoptionalAktuálne fakturačné obdobie vo formáte YYYY-MM (SK časová zóna). [response field]
nextResetAtstringoptionalISO 8601 — kedy sa počítadlá vynulujú (1. deň ďalšieho mesiaca, SK polnoc v UTC). [response field]
billable.outboundChargenumberoptionalTarifný náklad za odoslané dokumenty — sadzby aplikované na outboundCount ako agregát. [response field]
billable.totalChargenumberoptionalSúčet outbound + inbound API. Zaokrúhlené na centy. [response field]
sandbox.totalChargenumberoptionalNeúčtovaný sandbox odhad pri aktuálnej sandbox prevádzke. [response field]
productionEstimate.totalChargenumberoptionalOdhad ceny, ak by sandbox integrator-managed firmy bežali v produkcii. [response field]
exceedsAutoTierbooleanoptionalHistorický príznak z podpísanej cenovej snímky. Pri V1.2 zostáva false, pretože pásmo 20 001+ má verejnú sadzbu. [response field]
contactThresholdintegeroptionalKompatibilný historický prah 20 000. Pri V1.2 neznamená povinnosť kontaktovať podporu; rozhodujúce je contactRequired=false na pásme 20 001+. [response field]
firms[].managedbooleanoptionaltrue = firma je integrator-managed. Kombinujte s firms[].sandbox alebo firms[].billable na odlíšenie účtovaných a testovacích firiem. false = patrí do nonManaged. [response field]
firms[].sandboxbooleanoptionaltrue = firma je sandbox a neúčtuje sa. [response field]
firms[].billablebooleanoptionaltrue = firma je integrator-managed produkcia a počíta sa do aktuálne účtovanej prevádzky. [response field]

Príklady volania

cURL
curl https://epostak.sk/api/v1/integrator/licenses/info \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "integrator": {"id":"int_abc","name":"Demo Integrátor","plan":"integrator","monthlyDocumentLimit":null},
  "period": "2026-04",
  "nextResetAt": "2026-05-01T00:00:00.000Z",
  "billable": {
    "managedFirms":42,"outboundCount":1850,"inboundApiCount":320,
    "outboundCharge":168.00,"inboundApiCharge":25.60,"totalCharge":193.60,"currency":"EUR"
  },
  "sandbox": {
    "firms":2,"outboundCount":120,"inboundApiCount":30,
    "outboundCharge":12.00,"inboundApiCharge":2.40,"totalCharge":14.40,"currency":"EUR"
  },
  "productionEstimate": {
    "managedFirms":44,"outboundCount":1970,"inboundApiCount":350,
    "outboundCharge":177.60,"inboundApiCharge":28.00,"totalCharge":205.60,"currency":"EUR"
  },
  "nonManaged": {"firms":3,"outboundCount":120,"inboundApiCount":15},
  "exceedsAutoTier": false,
  "contactThreshold": 20000,
  "pricing": {
    "scheduleVersion":"pricing-v1.2-2026-07-24","model":"tiered","currency":"EUR","thresholdScope":"per_direction","marginalBandStartsAt":20001,
    "outboundTiers":[
      {"upTo":1000,"rate":0.10},
      {"upTo":2000,"rate":0.08},
      {"upTo":5000,"rate":0.06},
      {"upTo":20000,"rate":0.05},
      {"upTo":null,"rate":0.04,"label":"20 001+","contactRequired":false}
    ],
    "inboundApiTiers":[
      {"upTo":1000,"rate":0.08},
      {"upTo":2000,"rate":0.07},
      {"upTo":5000,"rate":0.06},
      {"upTo":20000,"rate":0.05},
      {"upTo":null,"rate":0.04,"label":"20 001+","contactRequired":false}
    ]
  },
  "firms":[
    {"firmId":"firm_a","name":"Klient A s.r.o.","ico":"12345678","managed":true,"outboundCount":312,"inboundApiCount":41}
  ],
  "pagination":{"limit":50,"offset":0,"total":45}
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden
  • 404Integrator not found

Reporty

Štatistiky a prehľady o odoslaných a prijatých dokumentoch.

Usage statistics

Reporty sú prevádzkový a billing povrch, nie náhrada detailného document lifecycle.

  • Použite ich na kontrolu objemov a fakturácie.
  • Pre konkrétny incident použite document status/events/support-packet.
UsageSubmissions
GET/api/v1/reporting/statistics

Štatistiky dokumentov

Vráti agregované štatistiky dokumentov: počty odoslaných/prijatých podľa typu, miera doručenia, top príjemcovia a odosielatelia.

Parametre

NázovTypPovinnéPopis
periodstringoptionalmonth | quarter | year (default: month) (povolené: month, quarter, year)
fromstringoptionalZačiatok obdobia ISO 8601
tostringoptionalKoniec obdobia ISO 8601

Príklady volania

cURL
curl "https://epostak.sk/api/v1/reporting/statistics?period=month" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "period": {"from":"2025-04-01","to":"2025-04-30"},
  "sent": {"total":47,"by_type":{"invoice":45,"credit_note":2}},
  "received": {"total":12,"by_type":{"invoice":12}},
  "delivery_rate": 0.979,
  "top_recipients": [{"name":"ABC s.r.o.","peppol_id":"0245:SK...","count":10}],
  "top_senders": []
}

Odpovede

  • 200OK
  • 401Unauthorized
GET/api/v1/reporting/submissions

História reportov pre OpenPeppol

Vráti zoznam EUSR/TSR reportov, ktoré sme ako AP operátor odoslali do OpenPeppol. Globálna história operátora — slúži ako dôkaz, že prevádzkujeme regulatorne povinný reporting. Zoznam je read-only, paginated, sortovaný podľa submitted_at DESC.

Parametre

NázovTypPovinnéPopis
limitnumberoptionalMax 100 (default: 20)
offsetnumberoptionalPosun pre stránkovanie (default: 0)
report_typestringoptionalEUSR | TSR (povolené: EUSR, TSR)

Príklady volania

cURL
curl "https://epostak.sk/api/v1/reporting/submissions?limit=20&report_type=EUSR" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{
  "items": [{
    "id": "a1b2c3d4-...",
    "report_type": "EUSR",
    "period": {"from":"2026-03-01","to":"2026-03-31"},
    "status": "sent",
    "message_id": "<peppol-message-id>",
    "submitted_at": "2026-04-01T08:15:00Z",
    "has_error": false
  }],
  "total": 24,
  "limit": 20,
  "offset": 0
}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required

Advanced

Plná expert referencia je jeden klik od Core. Použite ju, keď potrebujete vlastný lifecycle, batch operácie, multi-firma administráciu, push webhooks alebo dôkazové artefakty.

Enterprise Full

Čistý Enterprise kontrakt bez Connector ciest. Compatibility aliasy ostávajú počas riadeného notice window.

Enterprise Full OpenAPI

Outbound JSON alebo UBL

JSON nechá ePošťák vytvoriť UBL; XML mode zachová hotový Peppol BIS dokument. V oboch prípadoch preflight, stabilný idempotency key a status ostávajú rovnaké.

JSON send recipeUBL send recipe

Inbound fetch a lokálny ack

Čítajte cursor-based inbound feed, durable uložte dokument a až potom potvrďte lokálne spracovanie. Ack neposiela obchodnú odpoveď protistrane.

Inbound recipe

Push webhook + pull reconciliation

Push prijmite durable pred 2xx a deduplikujte podľa event ID. Pull používajte ako reconciliation checkpoint; kanály nezdieľajú tú istú subscription.

Webhook + pull recipe

Failed delivery a support

Uložte requestId, documentId a messageId. Pred eskaláciou stiahnite support packet; neposielajte secret ani celý UBL, ak stačí hash.

Troubleshooting recipe

Multi-firma credentials a scopes

sk_int_* mintne integrátorský JWT. Každý firm-scoped Enterprise request nesie X-Firm-Id autorizovanej firmy a kľúč má iba potrebné scopes. Cross-firm operácie ho nepoužívajú podľa Full kontraktu.

Auth a firm context

Compatibility

Iba pre existujúce integrácie a migračné porovnanie. T0 ešte nezačalo, preto dnes neexistuje retirement deadline; najskorší sunset môže byť až po 30 plných dňoch od operátorom aktivovaného notice timestampu.

Legacy Combined — neimportovať do nového kódu

Existujúca URL zostáva stabilná pre súčasné codegen klienty a zahŕňa Enterprise aj historické Connector cesty. Nový Enterprise kód používa Core alebo Full.

Legacy Combined OpenAPI

Deväť pripravovaných mapovaní

POST /extract → /payloads/extract; POST /extract/batch → /payloads/extract/batch; POST /documents/parse → /payloads/parse; POST /documents/convert → /payloads/convert; POST /documents/validate → /payloads/validate; GET /webhook-queue → /events/pull; DELETE /webhook-queue/{eventId} → POST /events/{eventId}/ack; POST /webhook-queue/batch-ack → /events/batch-ack; GET /documents/{id}/evidence-bundle → /documents/{id}/support-packet.

Pagination dialects — nemenia sa v tomto sunset programe

Core events/pull nemá cursor: vracia events + has_more a server drží ack state. Inbound/outbound pull posiela ?since=<opaque next_cursor> a vracia next_cursor + has_more. /documents/inbox preferuje ?cursor a vracia nextCursor, pričom offset/limit zostáva kompatibilný; /documents/outbox a dead-letter používajú offset/limit. Connector, ako samostatný produkt, používa cursor → nextCursor + hasMore. Cursor nikdy neparsujte ani neprekladajte medzi feedmi.

Acknowledge nie je Invoice Response

POST /inbound/documents/{id}/ack iba uloží, že ERP dokument lokálne spracovalo; protistrane nič neposiela. POST /documents/{id}/respond je samostatná pokročilá business operácia, ktorá odošle Invoice Response. V Connectore platí rovnaká hranica medzi acknowledge a respond.

Referencia

Cenník, uchovávanie dát a chybové kódy. Väčšina endpointov vracia chybu vo formáte {"error":{"code":"...","message":"...","requestId":"..."}}.

Error contract

Integrátori majú branchovať podľa error.code a ukladať requestId pre support.

  • 422 nie je jeden typ chyby; rozlišujte validation, UBL a idempotency.
  • Retry pravidlá sú súčasťou API kontraktu.
Error codesRate limits

Commercial and retention

Pricing, archív a cieľ dostupnosti patria do reference časti, aby implementačný flow ostal ľahký.

  • Enterprise API archív je viazaný na aktívny kontrakt.
  • Objemové sadzby sa počítajú naprieč spravovanými firmami.
PricingRetention
Kanonický Enterprise kontrakt. Payloady používajú /api/v1/payloads/*, pull udalosti /api/v1/events/* a dôkazný balík /api/v1/documents/{id}/support-packet. Tieto trasy sú jediným podporovaným povrchom pre nové aj existujúce pre-launch integrácie.
Error handling contract. Integrácie majú branchovať podľa error.code, nie iba podľa HTTP statusu. Každý supportovateľný incident ukladajte s requestId, documentId/submissionId, messageId a payloadSha256; pri reklamácii priložte support-packet namiesto celého XML, ak stačí hash a dôkazový balík.
Pravidlá opakovania. 422 VALIDATION_ERROR, UBL_VALIDATION_ERROR a IDEMPOTENCY_KEY_MISMATCH neopakujte bez opravy dát. Pri 429 rešpektujte Retry-After; 502/503 opakujte s backoffom a rovnakým Idempotency-Key, ak ide o ten istý payload.

Cenník

Transparentné ceny bez skrytých poplatkov.

Sandbox

Testovacie prostredie pre integráciu.

ObjemCena
Neobmedzenezadarmo

Odoslané

Cena za dokument odoslaný cez Peppol.

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é cez API

Cena za dokument prijatý a sprístupnený cez API.

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

Objemové zľavy sa počítajú naprieč všetkými spravovanými firmami, nie per-firma. Ceny sú bez DPH. Platí sa len za dokumenty skutočne doručené cez Peppol.

Rate limity

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

Pravidlá

  • Štandardné endpointy200 požiadaviek / 60 sekúnd
  • POST /documents/send150 požiadaviek / 60 sekúnd
  • POST /documents/send/batch10 požiadaviek / 60 sekúnd (až 50 faktúr na požiadavku)
  • GET /documents/{id}/status400 požiadaviek / 60 sekúnd
  • POST /documents/status/batch300 požiadaviek / 60 sekúnd (až 100 stavov na požiadavku)
  • POST /payloads/extract (alias aj /extract OCR)10 požiadaviek / 60 sekúnd
  • POST /payloads/extract/batch (alias aj /extract/batch)3 požiadavky / 60 sekúnd
  • POST /firms/assign a /firms/assign/batch10 požiadaviek / 60 sekúnd
  • POST /validate (verejné)20 požiadaviek / 60 sekúnd na IP

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 implementovať exponenciálny backoff. Aktuálny limit pre konkrétny endpoint sa zobrazí v X-RateLimit-Limit hlavičke pri 429 odpovedi.

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
400BAD_REQUESTNeplatné JSON telo alebo chýbajúce pole
400INVALID_PARAMNeplatná hodnota query parametra
401UNAUTHORIZEDChýbajúci alebo neplatný API kľúč
403FORBIDDENNedostatočný scope alebo prístup k cudzej firme; alebo firma nemá API-eligible plán
404NOT_FOUNDProstriedok neexistuje alebo nepatrí vašej firme
409CONFLICTDuplikát (OAuth klient, priradenie firmy, idempotency in-flight)
409IDEMPOTENCY_IN_FLIGHTretryableRovnaký Idempotency-Key už spracúva rovnaký payload; počkajte a skontrolujte stav neskôr
409CONNECTOR_LEGACY_IDEMPOTENCY_OWNER_UNPROVENLegacy Connector send nevie bezpečne potvrdiť vlastníka idempotency kľúča spred nasadenia: pri retryable=true počkajte 30 sekúnd a zopakujte presne rovnaký kľúč aj telo; nikdy nevytvárajte nový kľúč. Pri retryable=false doklad znovu neposielajte a kontaktujte podporu na zosúladenie historického stavu.
409AUTOPILOT_REPLAY_MISMATCHAutopilot referencia bola použitá s iným príkazom alebo je rezervovaná v inom/nepreukázanom vlastníckom priestore. Bez Retry-After: konflikt neobchádzajte novým kľúčom; najprv zosúlaďte existujúci run.
422AUTOPILOT_IDEMPOTENCY_REQUIREDAutopilot nemá stabilnú ERP referenciu potrebnú na bezpečný retry: send vyžaduje idempotencyKey v tele alebo hlavičke; stage vyžaduje idempotencyKey alebo externalId. Nič sa neuložilo ani neodoslalo. Historický keyless send neopakujte s novým kľúčom; najprv zosúlaďte /connector/sync alebo kontaktujte podporu.
409CONNECTOR_OUTBOX_REFERENCE_RESERVEDHistorická outbox položka bez preukázaného integrátorského vlastníka už rezervuje ERP referenciu. Nová položka ju neprevezme; najprv zosúlaďte historický stav.
413PAYLOAD_TOO_LARGETelo požiadavky presahuje povolený limit
422VALIDATION_ERROR / UNPROCESSABLE_ENTITYJSON alebo povinné polia neprešli vstupnou validáciou; opravte payload
422UBL_VALIDATION_ERRORUBL je syntakticky spracované, ale porušuje Peppol/CEN pravidlo; pozrite details[].rule
422IDEMPOTENCY_KEY_MISMATCHRovnaký Idempotency-Key bol znovu použitý s iným kanonizovaným telom
422participant_not_foundKatalóg príjemcov: prijímateľ sa nenašiel v Peppol/SMP; retryable=false; fix_hint=zmeňte alebo overte Peppol ID príjemcu
422receiver_unsupported_document_typeKatalóg príjemcov: prijímateľ existuje, ale nepodporuje zvolený document type/profile; retryable=false; fix_hint=zmeňte typ dokladu alebo capability
422validation_failedValidácia payloadu: UBL/JSON sémantická validácia zlyhala; retryable=false; fix_hint=opravte payload podľa details/rule
502temporary_transport_errorretryableTransport: AP alebo sieťová závislosť dočasne zlyhala; retryable=true; fix_hint=opakujte s rovnakým Idempotency-Key
409delivery_dead_letteredDoručenie: všetky pokusy o doručenie sa vyčerpali; retryable=false; fix_hint=pozrite events/support-packet a opakujte manuálne alebo kontaktujte support
422duplicate_idempotency_keyIdempotencia: rovnaký Idempotency-Key bol použitý s iným telom; retryable=false; fix_hint=pošlite pôvodné telo alebo nový kľúč pre zmenený payload
429RATE_LIMITEDretryablePrekročený rate limit
500INTERNAL_ERRORretryableNeočakávaná chyba servera
502SEND_FAILEDretryableOdoslanie cez Peppol AP zlyhalo
503IDEMPOTENCY_STORE_UNAVAILABLEretryableDočasne nedostupný idempotency store; opakujte s rovnakým Idempotency-Key
503VALIDATION_SERVICE_UNAVAILABLEretryableDočasne nedostupný validačný engine; opakujte s backoffom

Uchovávanie dát

Prevádzková dostupnosť počas kontraktu

Enterprise API prevádzkovo sprístupňuje dokumenty počas aktívneho kontraktu — obsah (UBL/XML), štruktúrované dáta faktúr aj transportné metadata (Peppol message ID, časové pečiatky, AS4 potvrdenia, MLR). Read-only exportné endpointy /documents/{id}, /documents/{id}/ubl, /documents/{id}/pdf, /documents/{id}/evidence, /documents/{id}/evidence-bundle a /documents/{id}/envelope ostávajú dostupné počas aktívneho kontraktu a 30 dní po jeho ukončení na export. Opätovné stiahnutie dostupného dokumentu sa osobitne nespoplatňuje. Táto prevádzková dostupnosť nie je dlhodobý zákaznícky archív; ten sa v prípade potreby objednáva ako platený doplnok podľa aktuálneho Cenníka alebo individuálnej objednávky. Poskytovateľ vyvíja primerané úsilie na cieľ dostupnosti 99,5 % podľa VOP bez service creditov alebo automatických náhrad; Peppol sieť, FR SR, SMP/SML, OpenPeppol, cudzie Access Pointy a prijímacie systémy sú externé vrstvy mimo priamej kontroly ePošťáka.

Uchovávanie dát

Prevádzkové dáta API a technické zálohy sú viazané na zmluvný vzťah: počas aktívneho kontraktu a 30 dní po ukončení na export, audit alebo migráciu. Parametre samostatne objednaného zákazníckeho archívu určuje Cenník alebo individuálna objednávka. Signované AS4 obálky a transportné dôkazy uchovávame ako infraštruktúru Access Pointu, no Enterprise API ani platený zákaznícky archív automaticky nepreberajú zákonnú účtovnú archiváciu zákazníka. Po 30-dňovej exportnej lehote sa bežný API prístup k exportom uzatvára, ak samostatná objednávka neurčuje inak.

Zodpovednosť za účtovnú archiváciu

Zákonná povinnosť uchovávať daňové doklady podľa účtovných a daňových predpisov zostáva na vystaviteľovi/príjemcovi faktúry. ePošťák poskytuje exporty a dôkazné podklady počas aktívneho kontraktu a 30 dní po jeho ukončení na export, no formálne nepreberá povinnosť účtovnej archivácie zákazníka.