Čo je SAPI štandard a prečo ho ePošťák podporuje?

SAPI (Štandardné API pre integráciu) je rozhranie definované odborníkmi a Finančnou správou SR pre jednotnú integráciu e-fakturácie na Slovensku. Každý certifikovaný digitálny poštár ho musí implementovať. ePošťák bol prvý certifikovaný digitálny poštár, ktorý SAPI plne implementoval a sprístupnil vývojárom. Dokumentácia je dostupná v slovenčine aj angličtine.

Aký je rozdiel medzi SAPI a Enterprise API?

SAPI je štandardizované rozhranie s OAuth 2.0 autentifikáciou, definované Finančnou správou SR — vhodné pre softvéry, ktoré už implementujú SAPI štandard. Enterprise API je naše vlastné rozhranie s API kľúčom, webhookmi, bulk operáciami, AI extrakciou z PDF, konverziou UBL→PDF a white-label podporou — 40+ endpointov pre custom integrácie.

Koľko stojí API integrácia?

Sandbox na testovanie je zadarmo. Produkčné používanie API a integrátorských rozhraní sa od 1. 6. 2026 fakturuje podľa reálne odoslaných a prijatých dokumentov.

Ako získam prístup do sandbox prostredia?

Otvorte https://dev.epostak.sk/integrator, zadajte pracovný email a po overení mailu počkajte na schválenie sandbox integrátora. V sandbox integrátor paneli si následne vytvoríte testovacie API kľúče a sandbox firmy pre test SMP. Produkčná aktivácia na https://epostak.sk/integrator/aktivacia je až pre schválený go-live a podpísanú zmluvu.

Podporuje ePošťák API Peppol sieť?

Áno. ePošťák je certifikovaný Peppol prístupový bod (Access Point) a člen OpenPeppol od marca 2026. Cez API podporujeme Peppol BIS 3.0, AS4 protokol, SMP lookup a odosielanie e-faktúr do 39 krajín.

Môžem používať API pre viacero firiem (white-label)?

Áno. Enterprise API podporuje multi-firma prístup — z jedného integračného účtu spravujete neobmedzený počet firiem. Vaši klienti neplatia za digitálneho poštára.

V akých programovacích jazykoch sú dostupné SDK?

Oficiálne SDK sú dostupné v 6 jazykoch: TypeScript/JavaScript, Python, PHP, C#/.NET, Java a Ruby. Všetky sú open-source na GitHube.

Prečo je ePošťák prvý certifikovaný digitálny poštár s API?

ePošťák bol prvý digitálny poštár na Slovensku, ktorý sprístupnil kompletné REST API pre integráciu e-fakturácie. Zatiaľ čo ostatní certifikovaní poskytovatelia ponúkajú len webové rozhranie, ePošťák umožňuje plnú automatizáciu cez SAPI aj vlastné Enterprise API s 40+ endpointmi.

Enterprise API - ePošťák

SprievodcoviaSprievodcovia

Sprievodcovia

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

Vyberte si integračný tok

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

ZačaťNajkratšia cesta od sandbox tokenu po prvé bezpečné volanie.2 sprievodcovia OdosielanieAko vytvoriť faktúru, poslať hotový UBL a sledovať výsledok.3 sprievodcovia Príjem a importAko čítať prijaté dokumenty, importovať mimo-Peppol UBL a rozhodnúť sa medzi pull a webhookmi.3 sprievodcovia 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.3 sprievodcovia PrevádzkaAko riešiť retry, chyby a voľbu medzi Connectorom a plnou Enterprise API.3 sprievodcovia

Vytvoriť faktúru

Pošlite údaje faktúry; ePošťák vytvorí dokument.

Overiť príjemcu

Overte, či príjemca vie prijať e-faktúry.

Poslať hotový UBL XML

Pošlite UBL XML súbor, ktorý už máte vygenerovaný.

Prijímať dokumenty

Čítajte prijaté dokumenty a výsledky spracovania.

1. 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.

Postup

1Vezmite client_id a client_secret z API kľúča.
2Zavolajte POST /api/v1/auth/token s grant_type client_credentials.
3Používajte access_token ako Authorization: Bearer.
4Refreshujte 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ázov	Typ	Povinné	Popis
grant_type	string	áno	Použite client_credentials.
client_id	string	áno	Prefix alebo identifikátor API kľúča.
client_secret	string	áno	Plaintext sk_live_* alebo sk_int_* hodnota uložená vo vašom secret manageri.
X-Firm-Id	header	nie	Neposiela sa na token endpoint; používa sa až pri firm-scoped volaniach integrátora.

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_* volaniach za klienta pridajte X-Firm-Id až na následné API requesty.
Po získaní tokenu zavolajte /api/v1/auth/status ako lacný health check.

2. 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

1Rozdeľte Peppol ID na scheme a identifier.
2Pošlite documentType alebo documentTypes[] pre presné typy.
3Odosielajte 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": "2023038963"
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": "2023038963",
7    "id": "0245:2023038963"
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ázov	Typ	Povinné	Popis
participant.scheme	string	áno	Štvormiestny ISO 6523 scheme, pre slovenské DIČ typicky 0245.
participant.identifier	string	áno	Identifikátor bez prefixu scheme, napr. DIČ bez SK prefixu.
documentTypes[]	string[]	nie	Pole 1 až 20 Peppol document-type URN hodnôt; má prednosť pred documentType.
processId	string	nie	Voliteľ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.

3. 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

1Overte príjemcu cez capabilities, hlavne ak ho ešte nemáte v adresári.
2Pre š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.
3Pre self-billing použite UBL XML mode: receiverPeppolId je dodávateľ, AccountingCustomerParty je vaša autentifikovaná firma a InvoiceTypeCode je 389.
4Uložte documentId/submissionId, messageId, status link a payloadSha256.
5Sledujte 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:2023038963",
3  "receiverName": "Zakaznik A s.r.o.",
4  "receiverIco": "50123456",
5  "receiverDic": "2123038963",
6  "receiverIcDph": "SK2123038963",
7  "receiverStreet": "Hlavna 12",
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": "SK3112000000198742637541",
17  "variableSymbol": "2026001",
18  "buyerReference": "PO-2026-4421",
19  "note": "Služby za obdobie jún 2026. Príloha: akceptačný protokol.",
20  "prepaidAmount": 100,
21  "items": [
22    {
23      "description": "Implementačné práce",
24      "quantity": 16,
25      "unit": "HUR",
26      "unitPrice": 75,
27      "vatRate": 23,
28      "vatCategoryCode": "S",
29      "discount": 5,
30      "deliveryDate": "2026-06-30"
31    },
32    {
33      "description": "Servisná podpora",
34      "quantity": 1,
35      "unit": "C62",
36      "unitPrice": 240,
37      "vatRate": 23,
38      "vatCategoryCode": "S"
39    }
40  ],
41  "attachments": [
42    {
43      "fileName": "akceptacny-protokol.pdf",
44      "mimeType": "application/pdf",
45      "content": "JVBERi0xLjQKJc...",
46      "description": "Podpísaný akceptačný protokol"
47    }
48  ]
49}

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">2023038963</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>SK2123038963</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>50123456</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>SK3112000000198742637541</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/evidence-bundle"
12  },
13  "payloadSha256": "a1b2c3d4e5f6..."
14}

Polia požiadavky

Názov	Typ	Povinné	Popis
receiverPeppolId	string	áno	Peppol participant ID príjemcu vo formáte <code>scheme:identifier</code>, napr. <code>0245:2123456789</code>. Overuje sa v SMP pred vytvorením dokladu.
items	array	áno	Položky faktúry. Povinné v JSON mode, 1 až 999 riadkov.
items[].description	string	áno	Názov alebo popis položky. Nesmie byť prázdny.
items[].quantity	number	áno	Množ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[].unitPrice	number	áno	Cena za jednotku bez DPH. Nesmie byť záporná.
items[].vatRate	number	áno	Sadzba DPH v %. Povolené: 0, 5, 10, 19, 20, 23; historická 20 % sadzba je podporovaná pre staršie doklady/opravné doklady.
items[].vatCategoryCode	string	nie	DPH 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[].discount	number	nie	Zľava v percentách, 0 až 100.
items[].unit	string	nie	UN/ECE Rec 20 kód jednotky. Ak chýba, v UBL sa použije <code>C62</code>.
items[].deliveryDate	string	nie	Dá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[].lineType	string	nie	Typ riadku. Použite <code>advance_deduction</code> pre záporný odpočet zálohy na finálnej faktúre.
items[].advanceInvoiceReference	string	nie	Čí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>.
invoiceNumber	string	nie	Číslo faktúry. Ak chýba alebo je prázdne, vygeneruje sa z číselného radu firmy.
issueDate	string	nie	Dátum vystavenia. Ak chýba, použije sa aktuálny deň v časovej zóne Europe/Bratislava.
dueDate	string	nie	Dátum splatnosti.
currency	string	nie	ISO 4217 mena. Ak chýba, použije sa default firmy alebo EUR.
prepaidAmount	number	nie	Suma 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>.
paymentMethod	string	nie	Spô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>.
variableSymbol	string	nie	Variabilný symbol / payment reference.
buyerReference	string	nie	Referencia kupujúceho, napr. číslo objednávky alebo interný nákupný odkaz.
note	string	nie	Voľ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.
iban	string	nie	IBAN pre platbu. Ak chýba, použije sa IBAN uložený pri firme, ak existuje.
receiverName	string	áno	Obchodné meno príjemcu. Povinné pre úspešné vygenerovanie UBL faktúry (BT-44).
receiverIco	string	nie	IČO príjemcu.
receiverDic	string	nie	DIČ príjemcu.
receiverIcDph	string	nie	IČ DPH príjemcu.
receiverStreet	string	nie	Ulica a číslo príjemcu. Preferované pred parsovaním jedného poľa <code>receiverAddress</code>.
receiverCity	string	nie	Mesto príjemcu.
receiverPostalCode	string	nie	PSČ príjemcu.
receiverAddress	string	nie	Jednoriadková adresa príjemcu. Použite ju, ak neviete poslať split polia <code>receiverStreet</code>, <code>receiverCity</code>, <code>receiverPostalCode</code>.
receiverCountry	string	nie	ISO 3166-1 alpha-2 krajina príjemcu.
attachments	array	nie	Prí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[].fileName	string	áno	Názov súboru prílohy. Nesmie byť prázdny.
attachments[].mimeType	string	áno	Povolené 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[].content	string	áno	Base64-encoded obsah súboru bez <code>data:</code> prefixu.
xml	string	nie	UBL 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-Key	header	nie	Odporucane 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.

4. 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

1Vygenerujte UBL Invoice alebo CreditNote v Peppol BIS Billing 3.0.
2Pošlite { receiverPeppolId, xml } na /documents/send s Idempotency-Key.
3Ulož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">2023038963</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    "evidenceBundle": "/api/v1/documents/clx9ubl123/evidence-bundle"
9  },
10  "payloadSha256": "b4c5d6..."
11}

Povinné polia

Názov	Typ	Povinné	Popis
Content-Type	header	áno	application/json. UBL XML posielajte ako string v poli xml.
Invoice/CreditNote	XML	áno	UBL 2.1 doklad kompatibilný s Peppol BIS Billing 3.0.
AccountingSupplierParty	XML node	áno	Pri štandardnej faktúre musí zodpovedať autentifikovanej firme alebo firme z X-Firm-Id. Pri self-billing je to dodávateľ, ktorému dokument posielate.
AccountingCustomerParty/EndpointID	XML node	áno	Pri š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/documents/validate.
Ak migrujete hotové UBL prijaté mimo Peppolu, použite inbound import, nie outbound send.

5. 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

1Pollujte /documents/{id}/status pre aktuálny stav.
2Použite /outbound/events pre cursor stream udalostí.
3Pre 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/evidence-bundle"
11  }
12}

Povinné polia

Názov	Typ	Povinné	Popis
id	string	áno	documentId alebo submissionId zo send odpovede.
cursor	string	nie	Pri 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.

6. 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

1Pollujte /inbound/documents s limitom.
2Spracujte metadata a stiahnite raw UBL podľa links.ubl.
3Ak 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 eyJhbGc..." \
3  -H "X-Firm-Id: 3b7f4a21-8c55-4a5c-9e93-2dd8b5f25d10"

Response

json

1{
2  "items": [
3    {
4      "id": "inb_01JZ8...",
5      "direction": "inbound",
6      "documentType": "invoice",
7      "senderPeppolId": "0208:987654321",
8      "receiverPeppolId": "0245:2023038963",
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ázov	Typ	Povinné	Popis
cursor	string	nie	Cursor z predchádzajúcej odpovede next_cursor.
limit	integer	nie	Max počet dokumentov na stránku; držte stabilnú hodnotu pri pollingu.
X-Firm-Id	header	nie	Povinné pre integrátora, keď číta schránku spravovanej firmy.

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á prístup k firme alebo chýba 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.

7. 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

1Pošlite raw XML alebo JSON s xml.
2Skontrolujeme receiver identity proti firme.
3Dostanete 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ázov	Typ	Povinné	Popis
xml	string	áno	UBL XML payload, raw body alebo JSON pole xml.
source	string	nie	Pôvod importu, napr. email, sftp alebo migration.
messageId	string	nie	Externý 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.

8. 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

1Pre push nastavte URL a overujte HMAC podpis.
2Pre pull fallback vytvorte subscription bez URL a čítajte Events pull.
3Po 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ázov	Typ	Povinné	Popis
url	string \| null	nie	Verejný HTTPS receiver pre push; null pre Events pull.
events[]	string[]	áno	Typy udalostí, napr. document.received alebo document.response_received.
X-Webhook-Signature	header	áno	HMAC 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.

9. 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

1Vymieňajte sk_live_* alebo sk_int_* za JWT cez /auth/token; API secret neposielajte ako Bearer token.
2Pri integrátorovi nastavte X-Firm-Id na firmu, za ktorú konáte. Bez tohto firm contextu API nesmie vybrať cudzie dáta.
3Pri JSON invoice mode sa odosielateľské údaje nesmú brať z request body; UBL sa skladá s firmou z autentifikácie.
4Pri raw UBL mode kontrolujeme party role: štandardná faktúra vyžaduje authenticated supplier, self-billing vyžaduje authenticated customer.
5Box 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": "JWT subject or X-Firm-Id",
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ázov	Typ	Povinné	Popis
Authorization	header	áno	Krátkodobý Bearer JWT z /api/v1/auth/token.
X-Firm-Id	header	nie	Povinné pri integrátorskom volaní za spravovanú firmu; určuje firm scope.
sender identity	derived	áno	Odvodená z autentifikovanej firmy. JSON payload nemá právo prepísať odosielateľa.
payloadSha256	sha256	nie	Hash uloženého UBL/payload objektu pre dedup, support a audit bez odhaľovania obsahu.
webhook secret	secret	nie	Vracia sa iba raz pri vytvorení alebo rotácii webhooku; v ePošťákovi sa ukladá šifrovane.

Práca so stavmi

scoped

Volanie je naviazané na firmu z tokenu alebo X-Firm-Id.

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.

10. 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

1POST /api/v1/box/items je Enterprise skratka nad stagingom; Connector /outbox používa rovnakú Box vrstvu pre ERP-first flow.
2Každá položka dostane boxItemId, status, payloadSha256, retention a links na ďalšie akcie.
3Detail vracia bezpečný storage summary a timeline, nie raw UBL alebo plaintext object key.
4Ready/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:2023038963",
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ázov	Typ	Povinné	Popis
payload	object	nie	Rovnaký send payload ako pri /documents/send; ak chýba, použije sa koreňové telo.
externalId	string	nie	ERP korelačný identifikátor pre dedup a spätné mapovanie.
scheduledFor	datetime	nie	Budúci ISO 8601 čas plánovaného odoslania.
idempotencyKey	string	nie	Idempotentné zaradenie tej istej položky.
payloadSha256	response	nie	Hash 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.

11. 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

1Po send-e uložte documentId/submissionId, Peppol messageId a payloadSha256.
2Pollujte status alebo outbound events, kým transport a evidence state nedávajú očakávaný výsledok.
3Evidence 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/evidence-bundle" \
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/evidence-bundle"
15  }
16}

Povinné polia

Názov	Typ	Povinné	Popis
documentId	string	áno	ID z odpovede send/status alebo Connector detailu.
messageId	string	nie	Peppol korelácia na transportnej vrstve.
payloadSha256	string	nie	Hash 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.

12. 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

1Pozrite HTTP status a error.code.
2Pri retry použite rovnaký Idempotency-Key.
3Ak 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:2023038963",
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ázov	Typ	Povinné	Popis
error.code	string	áno	Primárna vetva pre rozhodnutie, čo opraviť alebo opakovať.
requestId	string	nie	Korelačný identifikátor pre support/debug.
Idempotency-Key	header	nie	Použ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.

13. 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

1Capability: zavolajte POST /api/v1/peppol/capabilities a branchujte podľa networkReady, matchedDocumentTypes a routing statusu.
2Preflight: zavolajte POST /api/v1/documents/preflight pre rovnaký documentTypeId/processId a blokované výsledky opravte pred sendom.
3Send: POST /api/v1/documents/send opakujte iba s rovnakým Idempotency-Key, ak ide o ten istý payload.
4Events: čí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.
5Support: 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:2023038963",
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ázov	Typ	Povinné	Popis
networkReady	boolean	áno	Výsledok capability checku pre rozhodnutie, či vôbec skladať alebo poslať payload.
matchedDocumentTypes	string[]	nie	Presné Peppol document-type URN-y, ktoré príjemca akceptuje.
Idempotency-Key	header	áno	Stabilný kľúč pre retry toho istého send payloadu.
last acknowledged event id	string	áno	Posledný lokálne commitnutý a acknutý event, aby ERP import vedel po reštarte pokračovať idempotentne.
requestId + support-packet	support fields	áno	Minimá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.

14. 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

1Vyberte Connector pre rýchly ERP inbox/outbox.
2Vyberte Enterprise API pre vlastný lifecycle a dôkazy.
3Vyberte 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ázov	Typ	Povinné	Popis
Connector	product path	nie	Managed ERP tok: mailbox, mapper, outbox, sync a repair report.
Enterprise API	product path	nie	Kontrolovaná API vrstva: send, inbound, webhooky, dôkazy, multi-firm.
SAPI	compatibility path	nie	Transport-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 integrátorských volaniach v mene klienta nezabudnite X-Firm-Id.

Ď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é kľúče 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 volaniach cez integrátorský kľúč (sk_int_*) priložte HTTP hlavičku X-Firm-Id, ktorej hodnotou je Firm UUID cieľovej firmy (uvedený v karte Test Odosielateľ alebo Test Prijímateľ nižšie).

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. Cieľovú firmu určujete v každom volaní pomocou HTTP hlavičky X-Firm-Id, kam doplníte Firm UUID — buď f2cea3cf-f29e-4ea2-9e76-b06a312ec9ab (Test Odosielateľ, 0245:0000000001) alebo b1022d80-5016-4dad-a8d2-53685cab1701 (Test Prijímateľ, 0245:0000000002).

Onboarding klienta

Pre koho je Enterprise API a ako napojíte prvého klienta — od jeho registrácie u Finančnej správy, cez OAuth consent, až po prvú faktúru. Detailné endpointy, scopes a webhook signature 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 pred produkčným go-live. Produkčný integrátorský prístup riešime po schválenom go-live a podpísanej zmluve. Od 1. januára 2027 je elektronická fakturácia povinná pre všetkých platiteľov DPH na Slovensku.

Krok 1: Klient si zvolí ePoš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: Klient vám dá consent. Aby ste vy ako integrátor mohli spravovať klientovu firmu, musí vám klient v aplikácii ePošťák explicitne udeliť súhlas (OAuth consent flow). Pošlete ho na /oauth/authorize, on klikne „Súhlasím“ a my vám vrátime authorization code. Ten vymeníte v POST /api/oauth/token za integrátorský API kľúč naviazaný na túto konkrétnu firmu. Bez tohto súhlasu vám POST /api/v1/firms/assign vráti 403 CONSENT_REQUIRED — neexistuje cesta ako claimnúť cudziu firmu cez API bez vedomia jej majiteľa.

Krok 3: A je to. Po consent-e môžete s firmou robiť všetko podľa scope-ov, ktoré vám klient udelil — odosielať faktúry, prijímať dokumenty, registrovať webhooky, sledovať stavy, validovať UBL. Pri každom volaní v mene klienta priložte hlavičku X-Firm-Id s UUID jeho firmy. JWT získavate z integrátorského kľúča cez POST /api/v1/auth/token (platí 15 minút, refresh tokeny tu nie sú).

Pred produkciou si všetko overte cez sandbox integrátor login na dev.epostak.sk/integrator a testovacie firmy vydané v dev portáli (sekcia Demo testovacie účty vyššie). Produkčná aktivácia na epostak.sk/integrator/aktivacia je dostupná po schválení produkčného spustenia a podpísanej zmluve — napíšte na info@epostak.sk. Krok-za-krokom sprievodca aj s code snippetmi je v článku Ako integrovať digitálneho poštára do vášho ERP.

Mapa API referencie

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

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 účty Auth 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.

Send Preflight Support 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 Assistant Extract Validate

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 pull Webhooks Connector

Partner/admin

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

sk_int_* tokeny targetujú firmu cez X-Firm-Id.
Usage/reporting používajte na billing a prevádzkové kontroly.

Firmy Reporty

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. API kľúče (sk_live_* / sk_int_*) nie sú priamo použiteľné ako bearer. Slúžia ako client_secret v POST /api/v1/auth/token, ktorý vráti JWT (eyJ...). JWT používate ako Authorization: Bearer na všetkých Enterprise aj SAPI routách.

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.

Token Refresh Status

Integrator context

Pri sk_int_* tokenoch je identita integrátora oddelená od cieľovej firmy.

Na firm-scoped volania posielajte X-Firm-Id.
Consent a firm assignment patria do partner/admin flow.

OAuth consent Firm assignment

Ž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ázov	Typ	Povinné	Popis
limit	integer	optional	1–100, default 20.
event	string	optional	Presná zhoda názvu eventu (napr. `jwt.issued`, `webhook.created`).
actor_type	string	optional	Jeden z: `user`, `apiKey`, `integratorKey`, `system`.
since	string	optional	ISO 8601 timestamp dolnej hranice (inkluzívne).
until	string	optional	ISO 8601 timestamp hornej hranice (exkluzívne).
cursor	string	optional	Opaque 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.
403Plán nepovoľuje tento endpoint. Vyžaduje `audit:read` scope a API prístup (`api-enterprise` priamo alebo `integrator-managed` cez spravujúceho integrátora).

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ázov	Typ	Povinné	Popis
name	string	REQ	Názov OAuth klienta
redirect_uris	string[]	REQ	Povolené redirect URI (HTTPS alebo localhost)
logo_url	string	optional	URL 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.

Parametre

Názov	Typ	Povinné	Popis
client_id	string	REQ	ID vášho OAuth klienta
redirect_uri	string	REQ	Registrovaná callback URL
response_type	string	REQ	code (povolené: `code`)
scope	string	optional	firms:manage documents:send documents:read — ak je prázdne, použije sa celý rozsah klienta
state	string	optional	odporúčané pre CSRF ochranu — náhodný reťazec
code_challenge	string	REQ	PKCE code challenge (SHA-256) (43–128 znakov)
code_challenge_method	string	REQ	S256 (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 nový sk_int_* client_secret a metadata firmy. Content-Type: application/x-www-form-urlencoded (odporúčané podľa RFC 6749) alebo application/json.

Parametre

Názov	Typ	Povinné	Popis
grant_type	string	REQ	authorization_code (povolené: `authorization_code`)
code	string	REQ	Autorizačný kód z redirect_uri
client_id	string	REQ	OAuth client ID
client_secret	string	REQ	OAuth client secret
redirect_uri	string	REQ	Rovnaká URL ako pri autorizácii
code_verifier	string	REQ	PKCE code verifier

Príklady odpovedí

200 OK

{
  "client_id": "sk_int_xxxxx...abcd",
  "client_secret": "sk_int_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "secret_type": "sk_int",
  "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/sken Parse 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.

Validate Preflight

Od vstupu k send payloadu. Payload Assistant zoskupuje OCR extrakciu, UBL parse, konverziu a validáciu pod jeden mentálny model: vytvorte alebo skontrolujte payload, potom ho pošlite cez POST /api/v1/documents/preflight a POST /api/v1/documents/send.

Legacy endpointy /api/v1/extract, /api/v1/documents/parse, /api/v1/documents/convert a /api/v1/documents/validate zostávajú podporované; nové integrácie majú preferovať /api/v1/payloads/* aliasy.

POST/api/v1/payloads/extract

Payload Assistant: extrahovať jeden súbor

Preferovaný alias pre OCR/extract workflow. Z PDF alebo obrázka vráti extrakciu a pri outbound štandardnej faktúre aj send_payload pripravený na review, preflight a POST /api/v1/documents/send. Pôvodný endpoint /api/v1/extract zostáva podporovaný ako compatibility alias.

Parametre

Názov	Typ	Povinné	Popis
file	File	REQ	PDF, JPEG, PNG, WebP (max 20 MB)
fields	JSON string	optional	Optional 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":{"invoiceNumber":"FAK-001","totalWithVat":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/extract/batch

Payload Assistant: batch extrakcia

Preferovaný alias pre hromadnú OCR extrakciu do review checklistu a send_payload návrhov. Pôvodný endpoint /api/v1/extract/batch zostáva podporovaný ako compatibility alias.

Parametre

Názov	Typ	Povinné	Popis
files	File[]	REQ	Pole 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

Payload Assistant: rozobrať UBL

Preferovaný alias pre rozobratie UBL XML na normalizovaný JSON payload bez odoslania. Pôvodný endpoint /api/v1/documents/parse zostáva podporovaný.

Parametre

Názov	Typ	Povinné	Popis
xml	string	REQ	UBL 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

Payload Assistant: konvertovať

Preferovaný alias pre konverziu medzi JSON payloadom a UBL XML bez odoslania. Pôvodný endpoint /api/v1/documents/convert zostáva podporovaný.

Parametre

Názov	Typ	Povinné	Popis
input_format	string	REQ	"json" \| "ubl" (povolené: `json`, `ubl`)
output_format	string	REQ	"ubl" \| "json" (povolené: `ubl`, `json`)
document	object\|string	REQ	Dokument 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

Payload Assistant: validovať

Preferovaný alias pre validáciu JSON alebo UBL payloadu pred odoslaním. Pôvodný endpoint /api/v1/documents/validate zostáva podporovaný.

Parametre

Názov	Typ	Povinné	Popis
format	string	REQ	"json" \| "ubl" (povolené: `json`, `ubl`)
document	object\|string	REQ	JSON 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

Connector

Rýchle ERP napojenie nad Enterprise API. Najjednoduchší odporúčaný začiatok pre ERP tímy: pravidelné čítanie výsledkov, bez nastavovania webhooku, so správou o opravách pred odoslaním.

Managed ERP flow

Connector je odporúčaný štart, ak ERP nechce skladať celý Enterprise lifecycle po krokoch.

Mailbox/sync/feed drží ERP v jednom pravidelne čítanom modeli.
Outbox umožní nahrať teraz a odoslať neskôr.

Mailbox Sync Outbox

When to drop lower

Prejdite na plnú Enterprise API, keď potrebujete vlastnú queue, webhook policy, evidence alebo multi-firm admin.

Connector neberie legacy endpointy preč.
DocumentId ostáva použiteľné v Enterprise detailoch.

Enterprise send Support packet

Connector je riadený tok nad Enterprise API pre rýchle ERP napojenie do siete Peppol. Po súhlase firmy ePošťák automaticky pripraví Connector Schránku, takže integrátor nemusí ručne skladať pull subscription, Events pull ani X-Firm-Id onboarding. Primárny model je customerRef: ERP môže poslať tolerantnejší JSON cez /connector/zen-input, uložený CSV/XML/PDF-text mapping cez /connector/mapper alebo presný request cez /connector/autopilot, číta jednotný feed cez /connector/sync a lifecycle dokladu cez /connector/documents/{id}. Pre okamžité doručenie ostáva /connector/send; pre frontu faktúr /connector/outbox. Pri potrebe väčšej kontroly môžete prejsť na plné Enterprise API.

Kedy použiť Connector: ak chcete rýchlo napojiť ERP, pravidelne čítať prijaté faktúry a udalosti, pripravené položky vo fronte odosielať neskôr a pri odoslaní dostať jasnú správu o opravách. Kedy prejsť na Enterprise API: keď potrebujete plnú kontrolu nad webhookmi, správou viacerých firiem, balíkom dôkazov, hromadnými operáciami alebo technickými Peppol detailmi. Kedy použiť SAPI: keď cieľom je štandardizované rozhranie SAPI-SK, nie vlastný ePošťák tok.

Plug-and-play model: po OAuth súhlase firmy volajte GET /api/v1/connector/mailbox. Ak schránka nie je pripravená, POST /api/v1/connector/mailbox/repair ju opraví. Potom ERP posiela doklady cez POST /api/v1/connector/mapper s uloženým templateKey, cez tolerantný POST /api/v1/connector/zen-input, alebo cez presnejší POST /api/v1/connector/autopilot s customerRef a číta GET /api/v1/connector/sync. Webhooky a Events pull ostávajú ako pokročilá Enterprise vrstva, nie povinný krok Connector onboardingu.

GET/api/v1/connector/mailbox

Connector Schránka

Vráti pripravenosť Connector Schránky pre všetky spravované firmy integrátora. Schránka je automatický integračný priestor pre customerRef, send policy, pull subscription a štandardné udalosti; v hlavnom Connector toku ju integrátor nemusí skladať ručne.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Príklady volania

cURL

curl https://epostak.sk/api/v1/connector/mailbox -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Zoznam schránok a ich pripravenosť.
401Neautorizované volanie.
403Chýba oprávnenie firms:manage.

POST/api/v1/connector/mailbox/repair

Oprava Connector Schránky

Zapne alebo opraví Connector Schránku. Bez tela opraví všetky spravované firmy; s customerRef opraví jednu firmu. Automaticky vytvorí chýbajúce pull subscription a štandardné Connector eventy.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	optional	Voliteľné ID zákazníka, ak chcete opraviť iba jednu schránku.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/mailbox/repair -H "Authorization: Bearer eyJhbGc..." -H "Content-Type: application/json" -d '{"customerRef":"12345678"}'

Odpovede

200Súhrn opravených alebo vytvorených schránok.
422Neplatný customerRef alebo telo requestu.

PATCH/api/v1/connector/mailbox/{customerRef}/send-policy

Pravidlo odosielania schránky

Nastaví, kedy sa majú doklady danej spravovanej firmy odosielať: iba uložiť na kontrolu, odoslať hneď, naplánovať, denná dávka alebo pozastaviť. ERP tak vie vybrať čas odoslania bez vlastnej Peppol fronty.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	ID zákazníka v ERP.
policy	string	REQ	stage_only, immediate, scheduled_at, daily_batch alebo paused.

Príklady volania

cURL

curl -X PATCH https://epostak.sk/api/v1/connector/mailbox/12345678/send-policy -H "Authorization: Bearer eyJhbGc..." -H "Content-Type: application/json" -d '{"policy":"daily_batch"}'

Odpovede

200Aktualizovaná schránka.
404Schránka sa nenašla alebo firma nedala súhlas.

POST/api/v1/connector/preflight

Connector kontrola pred odoslaním

Kontrola pred odoslaním pre ERP tímy, navrhnutá na pravidelné čítanie výsledkov. Vráti, či je príjemca dostupný v Peppol/SMP, či sú pripravené údaje vhodné na odoslanie, a správu o opravách s poľami, ktoré treba opraviť pred reálnym odoslaním.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
receiverPeppolId	string	REQ	Peppol ID príjemcu, napríklad 0245:2123456789.
document	object	REQ	Údaje ERP faktúry alebo UBL/XML obálka na kontrolu pred odoslaním.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/preflight \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"receiverPeppolId":"0245:2123456789","document":{"invoiceNumber":"FA-2026-001","items":[{"description":"Service","quantity":1,"unitPrice":100,"vatRate":23}]}}'

Odpovede

200Správa o opravách a pripravenosť na odoslanie.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
422Kontrola zlyhala; pozrite správu o opravách.

POST/api/v1/connector/send

Connector odoslanie

Najjednoduchší odporúčaný začiatok pre ERP integráciu: odošle dokument cez riadený tok nad Enterprise API a vráti documentId použiteľný aj v plných Enterprise API volaniach.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
document	object	REQ	Údaje ERP faktúry alebo UBL/XML obálka.
idempotencyKey	string	optional	Kľúč pre bezpečné opakovanie volania na strane klienta. Správa sa rovnako ako Enterprise Idempotency-Key.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/send \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"erp-FA-2026-001","receiverPeppolId":"0245:2123456789","document":{"invoiceNumber":"FA-2026-001","items":[{"description":"Service","quantity":1,"unitPrice":100,"vatRate":23}]}}'

Príklady odpovedí

201 Dokument bol vytvorený a zaradený alebo odoslaný cez Enterprise odosielaciu cestu.

{"documentId":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","status":"sent"}

202 Prijaté na Peppol odoslanie, keď Enterprise odoslanie ešte dokončuje uloženie alebo aktualizáciu.

{"documentId":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","status":"processing"}

Odpovede

201Dokument bol vytvorený a zaradený alebo odoslaný cez Enterprise odosielaciu cestu.
202Prijaté na Peppol odoslanie, keď Enterprise odoslanie ešte dokončuje uloženie alebo aktualizáciu.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
422Kontrola zlyhala; spustite kontrolu pred odoslaním a pozrite detail opráv.

POST/api/v1/connector/zen-input

Connector Zen input

Najjednoduchší vstup pre ERP. Prijme voľnejší JSON s poľami ako invoiceNo, receiver.peppolId alebo lines, normalizuje ho na Autopilot request a bez X-Firm-Id ho spustí cez Connector Schránku. Pri previewOnly=true iba vráti normalizovaný request a odporúčané opravy.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	Vaše ID zákazníka/firmy.
invoiceNo	string	optional	Číslo faktúry; použije sa ako externalId, ak externalId nie je zadané.
receiver.peppolId	string	REQ	Peppol ID prijímateľa.
lines	array	REQ	Položky faktúry s name/qty/price/vat alebo štandardnými fieldmi description/quantity/unitPrice/vatRate.
previewOnly	boolean	optional	Ak true, nič neuloží ani neodošle; vráti iba normalizáciu a repair hints.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/zen-input \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"12345678","invoiceNo":"FA-2026-001","receiver":{"peppolId":"0245:2020123456"},"lines":[{"name":"Service","qty":1,"price":100,"vat":23}],"send":{"policy":"stage_only"}}'

Odpovede

201Input bol normalizovaný a odovzdaný Autopilotu.
200Preview normalizácie bez uloženia.
422Chýbajú povinné údaje; odpoveď obsahuje repair hints.

POST/api/v1/connector/mapper

Connector Mapper

ERP-facing vstup pre uložené mapping template-y. Po úvodnom nastavení v Connector Mapper Studiu môže ERP posielať vlastný CSV/XML/JSON/PDF-text export s templateKey; ePošťák ho prevedie na Connector Autopilot payload, vráti launch checklist a podľa execute režimu ho iba ukáže, stage-ne alebo odošle. UBL/BIS3 stále vyrába ePošťák.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
templateKey	string	optional	Kľúč uloženého mapping template-u z Connector Mapper Studia, napr. pohoda-csv-v1.
sourceType	string	optional	json, csv, xml, text alebo pdf_text. Ak chýba a templateKey existuje, použije sa typ uložený v template.
sourceText	string	optional	Raw CSV/XML/PDF-text export z ERP.
sourceJson	object	optional	JSON export z ERP, ak neposielate sourceText.
customerRef	string	optional	Vaše ID zákazníka/firmy. Môže byť uložené aj v template defaults.
execute	string	optional	preview, stage alebo send. Default je preview.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/mapper \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateKey": "pohoda-csv-v1",
    "execute": "stage",
    "sourceText": "Doklad,PeppolID,Partner,Popis,Pocet,CenaBezDph,Sadzba\nFA-2026-001,0245:2123456789,Odberatel s.r.o.,Servis,1,100,23"
  }'

Odpovede

200Preview mapovania bez uloženia alebo odoslania.
201Mapovanie bolo odovzdané Autopilotu na stage/send.
409Požadovaný send nebol vykonaný, napr. Autopilot vrátil replaynutý staged run.
404Uložený templateKey neexistuje.
422Chýba vstup alebo povinné polia; odpoveď obsahuje repair hints/checklist.

POST/api/v1/connector/autopilot

Connector Autopilot

Primárny Connector V2 vstup pre ERP. Integrátor posiela customerRef svojej spravovanej firmy, externalId dokladu, idempotencyKey a payload. ePošťák podľa customerRef nájde Connector Schránku, overí súhlas firmy, uloží lifecycle a podľa režimu doklad iba skontroluje, uloží do schránky alebo odošle podľa pravidla.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	Vaše ID zákazníka/firmy. Mapuje sa na Connector Schránku vytvorenú po súhlase firmy.
mode	string	REQ	Hodnoty API: shadow = kontrola bez uloženia, stage = uložiť do schránky, send = odoslať podľa pravidla v send.policy.
externalId	string	optional	ERP identifikátor dokumentu pre idempotentné opakovanie a reconciliation.
idempotencyKey	string	optional	Kľúč pre bezpečné opakovanie rovnakého Autopilot volania.
send.policy	string	optional	stage_only, immediate, scheduled_at, daily_batch alebo paused. Používa sa pri stage/send režime.
send.sendAt	string	optional	ISO 8601 čas odoslania pri policy=scheduled_at.
payload	object	REQ	Rovnaký payload ako pri Connector odoslaní.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/autopilot \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"12345678","mode":"stage","externalId":"ERP-FA-2026-001","idempotencyKey":"erp-fa-2026-001","send":{"policy":"stage_only"},"payload":{"receiverPeppolId":"0245:2123456789","items":[{"description":"Service","quantity":1,"unitPrice":100,"vatRate":23}]}}'

Odpovede

201Autopilot run bol uložený; pri kontrole bez uloženia obsahuje validáciu bez odoslania.
200Idempotentné opakovanie rovnakého runu.
409Rovnaký externalId alebo idempotencyKey bol použitý s iným payloadom.
422Dokument potrebuje opravu; odpoveď obsahuje repair report.

GET/api/v1/connector/autopilot/{autopilotId}

Connector Autopilot stav

Vráti uložený Autopilot run, jeho lifecycle status, repair report, documentId/outboxId a odkazy na stav alebo dôkazy.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
autopilotId	uuid	REQ	ID Autopilot runu vrátené pri POST /connector/autopilot.

Príklady volania

cURL

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

Odpovede

200Autopilot run.
404Autopilot run sa nenašiel.

POST/api/v1/connector/autopilot/{autopilotId}/send

Connector Autopilot odoslanie

Odošle Autopilot run z kontroly alebo zo schránky, ak posledná kontrola dovolila odoslanie. Používa existujúci Connector send a zachová idempotenciu runu.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
autopilotId	uuid	REQ	ID Autopilot runu.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/autopilot/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/send -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Run bol odoslaný alebo idempotentne už odoslaný.
422Run potrebuje opravu pred odoslaním.
503Odoslanie zlyhalo v externom Peppol toku; retry cez rovnaký run.

GET/api/v1/connector/reconcile

Connector reconciliation

Reconciliation API pre ERP sync: vráti výnimky od zvoleného času, napríklad Autopilot runy vyžadujúce opravu, staged outbox položky bez odoslania, failed sends a neacknuté inbound dokumenty.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
status	string	optional	exceptions alebo all. (default: `exceptions`)
since	string	optional	ISO 8601 timestamp pre inkrementálnu synchronizáciu.

Príklady volania

cURL

curl "https://epostak.sk/api/v1/connector/reconcile?status=exceptions&since=2026-06-01T00:00:00.000Z" -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Zoznam reconciliation položiek.
422Neplatný filter.

GET/api/v1/connector/sync

Connector jednotný feed

Jeden integračný feed pre ERP. Vracia pripravenosť schránok, outbox, Autopilot runy, odoslané a prijaté dokumenty, MLR/MLS, InvoiceResponse, TDD dôkazy a čakajúce akcie. Cursor je nad všetkými zdrojmi, takže ERP nemusí riešiť Events pull, ručné subscription ani samostatné endpointy pri štarte.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	optional	Voliteľný filter na jednu spravovanú firmu.
cursor	string	optional	Nepriehľadný cursor z predchádzajúcej odpovede.
limit	integer	optional	Počet položiek. Max 500. (default: `100`)

Príklady volania

cURL

curl "https://epostak.sk/api/v1/connector/sync?customerRef=12345678&limit=100" -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Cursor-paged feed položiek.
400Neplatný cursor alebo limit.

GET/api/v1/connector/documents/{documentId}

Connector lifecycle dokumentu

Vráti stav jedného dokumentu v jazyku použiteľnom pre ERP: smer, status, AS4 doručenie, MLR/MLS, InvoiceResponse, TDD, odkazy a ďalšie odporúčané akcie. Dokument je viditeľný iba po dátume súhlasu firmy s integrátorom.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu z Autopilota, outboxu alebo sync feedu.

Príklady volania

cURL

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

Odpovede

200Lifecycle dokumentu.
404Dokument sa nenašiel alebo nie je po súhlase firmy.

GET/api/v1/connector/documents/{documentId}/ubl

Connector UBL dokumentu

Stiahne pôvodné UBL/XML dokumentu pre ERP import alebo archiváciu. Prístup je integrátor-level a rešpektuje consent-time filter.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu.

Príklady volania

cURL

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

Odpovede

200UBL/XML dokument.
404Dokument sa nenašiel.

GET/api/v1/connector/documents/{documentId}/evidence

Connector dôkazy dokumentu

Štruktúrované dôkazy k dokumentu: AS4 receipt, MLR/MLS, InvoiceResponse, TDD a časové pečiatky. Vhodné pre ERP stav, audit a support bez sťahovania celého balíka.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu.

Príklady volania

cURL

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

Odpovede

200Štruktúrované dôkazy.
404Dokument sa nenašiel.

GET/api/v1/connector/documents/{documentId}/support-packet

Connector support packet

Preferovaný Connector alias pre support/evidence manifest dokumentu. Vracia rovnaký manifest ako /api/v1/connector/documents/{documentId}/evidence-bundle, ale v integračnom flow ho používajte ako support packet pre ERP, audit a reklamácie.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu.

Príklady volania

cURL

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

Odpovede

200Manifest dôkazového balíka.
404Dokument sa nenašiel.

GET/api/v1/connector/documents/{documentId}/evidence-bundle

Connector evidence bundle

Vráti manifest dostupnosti dôkazového balíka bez interných storage ciest: UBL link, AS4, MLR/MLS, InvoiceResponse, TDD a timestampy.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu.

Príklady volania

cURL

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

Odpovede

200Manifest dôkazového balíka.
404Dokument sa nenašiel.

POST/api/v1/connector/actions/{actionId}

Connector akcia

Vykoná akciu zo sync feedu cez jej href, napríklad potvrdenie prijatého dokladu, odoslanie z outboxu, preplánovanie odoslania, zrušenie outbox položky alebo odpoveď na faktúru. ERP nemusí riešiť X-Firm-Id ani interné endpointy; použije actionId a href zo sync feedu.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector Schránka a sync endpointy sú na úrovni integrátora; cieľovú firmu určujete cez customerRef.

Parametre

Názov	Typ	Povinné	Popis
actionId	string	REQ	ID akcie zo sync feedu. Môže to byť UUID uloženej akcie alebo stabilné ID typu reschedule:{outboxId}.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/actions/reschedule%3A8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111 \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"sendAt":"2026-06-10T16:00:00+02:00"}'

Odpovede

200Akcia bola dokončená alebo idempotentne už vykonaná.
422Akcia vyžaduje opravu v ERP alebo nie je vykonateľná týmto endpointom.

POST/api/v1/connector/outbox

Connector outbox: nahrať teraz, odoslať neskôr

Nahrá jednu alebo viac ERP faktúr do ePošťák Boxu bez okamžitého odoslania: nahrať teraz a odoslať neskôr. Každá položka prejde Enterprise kontrolou pred odoslaním, uloží repair checklist a dostane outboxId. Pripravené položky môžete odoslať neskôr jednotlivo alebo hromadne; plánovaný worker ich púšťa do Peppolu kontrolovaným tempom, aby veľký import nezaťažil infra naraz.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
items	array	optional	Najviac 50 pripravených faktúr. Každá položka obsahuje externalId, voliteľné scheduledFor, voliteľný idempotencyKey a payload.
payload	object	optional	Skratka pre jednu položku, keď nepoužívate items[]. Rovnaký tvar údajov ako pri Connector odoslaní.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/outbox \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"items":[{"externalId":"ERP-FA-2026-001","scheduledFor":"2026-06-04T08:00:00Z","payload":{"receiverPeppolId":"0245:2123456789","document":{"invoiceNumber":"FA-2026-001","items":[{"description":"Service","quantity":1,"unitPrice":100,"vatRate":23}]}}}]}'

Odpovede

201Položky vo fronte boli uložené so stavom ready/blocked/scheduled a správami o opravách.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
422Neplatná požiadavka na uloženie do fronty.

GET/api/v1/connector/outbox

Connector outbox zoznam

Zoznam pripravených odchádzajúcich faktúr v ePošťák Boxe. ERP vie pravidelne čítať položky v stavoch ready, blocked, scheduled, sent, failed alebo cancelled, použiť technický managedOutbox.state ako produktový stav a premietnuť repair checklist späť do vlastného rozhrania.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
status	string	optional	ready, blocked, scheduled, sending, sent, failed alebo cancelled.
limit	integer	optional	Maximálny počet vrátených položiek. Max 100. (default: `20`)
offset	integer	optional	Posun pre jednoduché zoznamy čítané pravidelne.

Príklady volania

cURL

curl "https://epostak.sk/api/v1/connector/outbox?status=blocked" -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Položky Connector outboxu.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.

GET/api/v1/connector/outbox/{outboxId}

Connector outbox detail

Detail pripravenej odchádzajúcej položky vrátane správy o opravách, documentId po odoslaní a odkazov na odoslanie, stav a dôkazy.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
outboxId	uuid	REQ	ID položky Connector outboxu vrátené pri uložení do fronty.

Príklady volania

cURL

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

Odpovede

200Položka Connector outboxu.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
404Položka vo fronte sa nenašla.

POST/api/v1/connector/outbox/{outboxId}/send

Connector outbox odoslanie

Odošle jednu pripravenú položku v stave ready, scheduled alebo failed cez existujúci Connector tok odoslania. Ak je položka stále blocked, vráti správu o opravách a neodošle ju.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
outboxId	uuid	REQ	ID položky Connector outboxu vrátené pri uložení do fronty.
force	boolean	optional	Nastavte true, ak chcete odoslať pred časom scheduledFor.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/outbox/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/send -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Položka z fronty bola odoslaná alebo už bola bezpečne odoslaná predtým.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
422Položka vo fronte je blokovaná; pozrite správu o opravách.

POST/api/v1/connector/outbox/send

Connector outbox hromadné odoslanie

Hromadne odošle položky vo fronte v stave ready alebo failed. Bez ids odosiela ready, failed a splatné scheduled položky; s ids odosiela konkrétne položky a chyby vracia po položkách. Automatický cron worker používa vlastný minútový odosielací limit.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
ids	array	optional	Voliteľný zoznam najviac 50 outbox ID.
limit	integer	optional	Maximálny počet položiek pri vynechanom ids. Max 50. (default: `50`)

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/outbox/send -H "Authorization: Bearer eyJhbGc..." -H "Content-Type: application/json" -d '{"limit":50}'

Odpovede

200Výsledky odoslania po jednotlivých položkách.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.

DELETE/api/v1/connector/outbox/{outboxId}

Connector outbox zrušenie

Zruší pripravenú položku pred odoslaním. Nevie zrušiť už odoslanú Peppol faktúru; po odoslaní použite stav, dôkazy alebo plné Enterprise API.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
outboxId	uuid	REQ	ID položky Connector outboxu vrátené pri uložení do fronty.

Príklady volania

cURL

curl -X DELETE https://epostak.sk/api/v1/connector/outbox/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111 -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Položka vo fronte bola zrušená.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
422Položku už nie je možné zrušiť.

GET/api/v1/connector/status/{documentId}

Connector stav dokumentu

Stav odoslaného dokumentu čítaný pravidelným dopytom. documentId je rovnaký identifikátor ako v Enterprise API.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu vrátené Connector odoslaním alebo Enterprise odoslaním.

Príklady volania

cURL

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

Odpovede

200Aktuálny stav životného cyklu doručenia.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
404Dokument sa nenašiel.

GET/api/v1/connector/inbox

Connector prijaté faktúry

Zoznam prijatých dokumentov pre ERP import, navrhnutý na pravidelné čítanie. Nepotrebuje prijímač webhookov; klient si uloží cursor a spracované dokumenty potvrdzuje samostatne.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
cursor	string	optional	Nepriehľadný cursor z predchádzajúcej odpovede.
limit	integer	optional	Maximálny počet vrátených dokumentov. Max 100. (default: `20`)

Príklady volania

cURL

curl "https://epostak.sk/api/v1/connector/inbox?limit=20" -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Prijaté dokumenty stránkované cez cursor.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.

GET/api/v1/connector/inbox/{documentId}

Connector detail prijatej faktúry

Detail prijatého dokumentu vrátane údajov pre ERP import a pôvodnej UBL/XML obálky.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID prijatého dokumentu z Connector zoznamu prijatých faktúr.

Príklady volania

cURL

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

Odpovede

200Detail dokumentu.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
404Dokument sa nenašiel.

POST/api/v1/connector/inbox/{documentId}/ack

Connector potvrdenie prijatej faktúry

Potvrdí, že ERP prijatý dokument spracovalo. Potvrdenie je idempotentné a vhodné pre importy založené na pravidelnom čítaní.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID prijatého dokumentu z Connector zoznamu prijatých faktúr.

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/connector/inbox/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/ack \
  -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Potvrdené.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.
404Dokument sa nenašiel.

GET/api/v1/connector/events

Connector udalosti

Zoznam udalostí pre odoslania, prijatia a opravy, navrhnutý na pravidelné čítanie. Je to jednoduchší ERP pohľad nad Enterprise udalosťami, nie náhrada plnej Enterprise kontroly.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-Id	uuid	optional	Povinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

Názov	Typ	Povinné	Popis
cursor	string	optional	Nepriehľadný cursor z predchádzajúcej odpovede `nextCursor`.
limit	integer	optional	Maximálny počet vrátených udalostí. (default: `100`)

Príklady volania

cURL

curl "https://epostak.sk/api/v1/connector/events?limit=100" -H "Authorization: Bearer eyJhbGc..."

Odpovede

200Connector udalosti stránkované cez cursor.
401Neautorizované volanie.
403Vyžaduje sa API plán alebo prístup nebol povolený.

Dokumenty

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

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.

Send Status Events

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 list Inbox UBL

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) — preferovaná pull alternatíva k webhookom pre klientov, ktorí nemôžu hostovať receiver. Server nesie stav cez acknowledged=false/true — pollujete, čo nie je ack-nuté, urobíte ack až po lokálnom commite a event zmizne z fronty. Server-side state management = klient nemusí trackovať cursor. Legacy /api/v1/webhook-queue ostáva podporovaný ako compatibility endpoint; 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.

Decision matrix:

Mám HTTPS endpoint a chcem push → Webhooky
Nemám HTTPS endpoint a chcem len eventy → Events pull
Chcem dokumenty (nie len signály) → Inbound/Outbound pull API
Robím audit/dashboard a chcem detailný lifecycle → Outbound events

Plan-eligibility: všetky firemné API endpointy fungujú pre api-enterprise priamo alebo pre integrator-managed firmu cez spravujúci integrátorský token.

POST/api/v1/documents/send

Odoslať dokument

Odošle dokument cez Peppol sieť. Podporuje JSON mode pre štandardnú faktúru a UBL XML mode cez JSON pole xml pre hotový UBL dokument. V JSON mode posielate nižšie uvedený field contract; UBL 2.1/Peppol BIS 3.0 XML skladá ePošťák. Odosielateľ sa berie z autentifikovanej firmy, nie z payloadu. Pred odoslaním overíme cez SMP, či je príjemca v Peppol sieti. Ak nie, vrátime 422 a nič sa nefakturuje. Voliteľná hlavička Idempotency-Key (alebo X-Idempotency-Key) — prvé volanie sa uloží, opakovanie s rovnakým telom vráti cache (200/201), kolízia v priebehu vráti 409. Ak sa SHA-256 hash tela líši od uloženého, vráti 422 IDEMPOTENCY_KEY_MISMATCH (telo je pred hashovaním kanonizované — kľúče zoradené rekurzívne).

Parametre

Názov	Typ	Povinné	Popis
receiverPeppolId	string	REQ	Peppol participant ID príjemcu vo formáte `scheme:identifier`, napr. `0245:2123456789`. Overuje sa v SMP pred vytvorením dokladu.
items	array	REQ	Položky faktúry. Povinné v JSON mode, 1 až 999 riadkov.
items[].description	string	REQ	Názov alebo popis položky. Nesmie byť prázdny.
items[].quantity	number	REQ	Množstvo. Musí byť kladné číslo. Záporné množstvo je povolené iba pri `items[].lineType=advance_deduction` pre odpočet zálohy.
items[].unitPrice	number	REQ	Cena za jednotku bez DPH. Nesmie byť záporná.
items[].vatRate	number	REQ	Sadzba 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[].vatCategoryCode	string	optional	DPH 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[].vatCategory	string	optional	Alias pre `items[].vatCategoryCode`. (povolené: `S`, `Z`, `AE`, `E`, `K`, `G`, `O`, `L`, `M`)
items[].vat_category	string	optional	Snake_case alias pre `items[].vatCategoryCode`. (povolené: `S`, `Z`, `AE`, `E`, `K`, `G`, `O`, `L`, `M`)
items[].discount	number	optional	Zľava v percentách, 0 až 100.
items[].unit	string	optional	UN/ECE Rec 20 kód jednotky. Ak chýba, v UBL sa použije `C62`. (default: `C62`)
items[].deliveryDate	string	optional	Dá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[].lineType	string	optional	Typ riadku. Použite `advance_deduction` pre záporný odpočet zálohy na finálnej faktúre. (povolené: `standard`, `advance_deduction`)
items[].advanceInvoiceReference	string	optional	Číslo zálohovej faktúry. Povinné pri `lineType=advance_deduction`; do UBL sa zapíše ako `AdditionalItemProperty` s názvom `AdvanceInvoiceNumber`.
items[].customsTariffCode	string	optional	Colný sadzobník / kombinovaná nomenklatúra pri prenesení daňovej povinnosti. Do UBL sa zapisuje ako `CommodityClassification/ItemClassificationCode listID="HS"`; KV DPH A2 používa prvé 4 číslice ako `TK`.
items[].reverseChargeParagraphLetter	string	optional	Písmeno §69 ods. 12 pre domácu evidenciu, napr. `f` alebo `g`. Do UBL sa zapisuje ako `AdditionalItemProperty`.
items[].controlStatementType	string	optional	Typ pre KV DPH A2 `TD`. Povolené: `IO`, `MT`. (povolené: `IO`, `MT`)
items[].controlStatementQuantity	number	optional	Množstvo pre KV DPH A2 `Mn`. Ak chýba a jednotka je známa, použije sa absolútna hodnota `quantity`.
items[].controlStatementUnit	string	optional	Jednotka pre KV DPH A2 `MJ`. Povolené: kg, t, m, ks. (povolené: `kg`, `t`, `m`, `ks`)
invoiceNumber	string	optional	Číslo faktúry. Ak chýba alebo je prázdne, vygeneruje sa z číselného radu firmy.
issueDate	string	optional	Dátum vystavenia. Ak chýba, použije sa aktuálny deň v časovej zóne Europe/Bratislava.
dueDate	string	optional	Dátum splatnosti.
currency	string	optional	ISO 4217 mena. Ak chýba, použije sa default firmy alebo EUR. (default: `EUR`)
prepaidAmount	number	optional	Suma zaplatená vopred (BT-113). Do UBL sa zapíše ako `LegalMonetaryTotal/PrepaidAmount` a zníži `PayableAmount`. Nekombinujte s riadkom `advance_deduction`.
paymentMethod	string	optional	Spôsob platby. Podporované sú ePošťák aliasy `bank_transfer`, `credit_transfer`, `sepa`, `card`, `cash`, `direct_debit`, alebo priamo UNCL4461 kód, napr. `30`.
variableSymbol	string	optional	Variabilný symbol / payment reference.
buyerReference	string	optional	Referencia kupujúceho, napr. číslo objednávky alebo interný nákupný odkaz.
note	string	optional	Voľ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.
iban	string	optional	IBAN pre platbu. Ak chýba, použije sa IBAN uložený pri firme, ak existuje.
receiverName	string	REQ	Obchodné meno príjemcu. Povinné pre úspešné vygenerovanie UBL faktúry (BT-44).
receiverIco	string	optional	IČO príjemcu.
receiverDic	string	optional	DIČ príjemcu.
receiverIcDph	string	optional	IČ DPH príjemcu.
receiverStreet	string	optional	Ulica a číslo príjemcu. Preferované pred parsovaním jedného poľa `receiverAddress`.
receiverCity	string	optional	Mesto príjemcu.
receiverPostalCode	string	optional	PSČ príjemcu.
receiverAddress	string	optional	Jednoriadková adresa príjemcu. Použite ju, ak neviete poslať split polia `receiverStreet`, `receiverCity`, `receiverPostalCode`.
receiverCountry	string	optional	ISO 3166-1 alpha-2 krajina príjemcu. (default: `SK`)
attachments	array	optional	Prí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[].fileName	string	REQ	Názov súboru prílohy. Nesmie byť prázdny.
attachments[].mimeType	string	REQ	Povolené 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[].content	string	REQ	Base64-encoded obsah súboru bez `data:` prefixu.
attachments[].description	string	optional	Voliteľný krátky popis prílohy.
xml	string	optional	UBL 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", "evidenceBundle": "/api/v1/documents/clx9abc123/evidence-bundle" }, "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", "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ázov	Typ	Povinné	Popis
items	array	REQ	Pole max 50 položiek — rovnaká schéma ako POST /documents/send
items[].idempotencyKey	string	optional	Voliteľ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 A 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ázov	Typ	Povinné	Popis
payload	object	optional	Rovnaký send payload ako POST /api/v1/documents/send; ak payload chýba, použije sa koreňové telo.
scheduledFor	string	optional	ISO 8601 čas plánovaného odoslania.
externalId	string	optional	ERP/external correlation ID.
idempotencyKey	string	optional	Idempotentné 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ázov	Typ	Povinné	Popis
status	string	optional	Filter stavu
limit	integer	optional	Max 100 (default: `20`)
offset	integer	optional	Offset (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ázov	Typ	Povinné	Popis
itemId	string	REQ	Box 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ázov	Typ	Povinné	Popis
scheduledFor	string	REQ	ISO 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ázov	Typ	Povinné	Popis
itemId	string	REQ	Box 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ázov	Typ	Povinné	Popis
itemId	string	REQ	Box 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ázov	Typ	Povinné	Popis
itemId	string	REQ	Box 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ázov	Typ	Povinné	Popis
since	string	optional	Opaque kurzor z `next_cursor` predchádzajúcej odpovede. Vynechajte na prvej požiadavke (začne od najstaršieho dokumentu).
limit	integer	optional	1-500. Hodnoty nad 500 sa potichu orezú na 500 (bez 400). (default: `100`)
kind	string	optional	Filter 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`)
sender	string	optional	Filter 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 — API access vyžaduje api-enterprise priamo alebo integrator-managed cez spravujúceho integrátora.
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 — implicitný ack je posun kurzora cez `GET /inbound/documents`. Explicit ack existuje pre klientov, ktorí chcú zaznamenať „úspešne spracované u nás" oddelene od „úspešne stiahnuté". Vyžaduje scope `documents:write`, nie iba `documents:read`, pretože mení stav dokumentu. Idempotentné: druhé volanie prepíše timestamp a `client_reference`.

Parametre

Názov	Typ	Povinné	Popis
client_reference	string	optional	Voliteľ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ázov	Typ	Povinné	Popis
since	string	optional	Opaque kurzor z `next_cursor` predchádzajúcej odpovede.
limit	integer	optional	1-500. Hodnoty nad 500 sa potichu orezú na 500. (default: `100`)
kind	string	optional	Filter 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`)
status	string	optional	Filter podľa `transport_status` (uniformné cez všetky dokumenty). (povolené: `queued`, `sending`, `sent`, `delivered`, `failed`, `dead`)
business_status	string	optional	Filter 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`)
recipient	string	optional	Filter 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 — API access vyžaduje api-enterprise priamo alebo integrator-managed cez spravujúceho integrátora.
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 API plán (`api-enterprise` priamo alebo `integrator-managed` cez spravujúceho integrátora).
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ázov	Typ	Povinné	Popis
since	string	optional	Opaque kurzor z `next_cursor` predchádzajúcej odpovede.
limit	integer	optional	1-500. Hodnoty nad 500 sa orezú na 500. (default: `100`)
document_id	string	optional	Filter 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

Vrati zoznam prijatych fakturačných dokumentov so strankovaniem. Pre plný Peppol scope vrátane non-billing typov používajte GET /api/v1/inbound/documents. Oba endpointy fungujú pre api-enterprise priamo alebo pre integrator-managed firmu cez spravujúci sk_int_* integrátorský token. Pole docType moze nadobudat tieto hodnoty: invoice (BIS 380 — bezna faktura), credit_note (BIS 381 — dobropis), self_billing (BIS 389 — samofakturacia), self_billing_credit_note (BIS 261 — dobropis k samofakturaci, nova hodnota).

Parametre

Názov	Typ	Povinné	Popis
limit	integer	optional	Max 100 (default: `20`)
offset	integer	optional	Offset pre stránkovanie. Pre stabilné stránkovanie vo veľkom objeme použite cursor namiesto offset. (default: `0`)
cursor	string	optional	Opaque kurzor zo `nextCursor` predchádzajúcej odpovede. Stabilné stránkovanie aj keď sa medzitým pridajú nové dokumenty.
status	string	optional	Filter 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`)
peppolMessageId	string	optional	Vyhľadanie dokumentu podľa Peppol message ID (max 100 znakov)
since	string	optional	ISO 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

Zapíše lokálny klientsky ack po stiahnutí alebo spracovaní v ERP. 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" }

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ázov	Typ	Povinné	Popis
ids	string[]	REQ	1 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

Preferovaný Lifecycle & proof alias nad dôkazovým balíkom dokumentu. Enterprise reliability contract používa support-packet ako posledný krok flowu capability → preflight → send → events → support: pri incidente ukladajte requestId + support-packet namiesto posielania celého XML, ak stačí hash a dôkazový balík. Vráti rovnaký ZIP support/evidence balík ako /api/v1/documents/{id}/evidence-bundle: manifest, evidence.json, UBL XML, PDF a dostupné AS4/MDN artefakty. Pôvodný evidence-bundle endpoint zostáva podporovaný.

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}/evidence-bundle

Dôkazový ZIP balík

Vráti jeden ZIP balík pre audit, reklamáciu alebo support: manifest.json, evidence.json, UBL XML, PDF, AS4 envelope z WORM archívu a MDN receipt obálky, ak sú dostupné. Voliteľné artefakty, ktoré ešte nie sú archivované alebo sa nedajú vygenerovať, sú zapísané v manifest.json v poli missing; endpoint stále vráti balík so zvyšnou evidenciou. Ak MDN receipt v archíve nesedí na uložený SHA-256 hash, odpoveď je 500 a balík sa nevydá.

Príklady volania

cURL

curl https://epostak.sk/api/v1/documents/clx9abc123/evidence-bundle \
  -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 dohodnutého odstupného obdobia po jeho ukončení; 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ázov	Typ	Povinné	Popis
limit	integer	optional	Max 100 (default: `20`)
cursor	string	optional	Opaque 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ázov	Typ	Povinné	Popis
status	string	REQ	AB (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`)
note	string	optional	Voliteľ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ázov	Typ	Povinné	Popis
state	string	REQ	delivered \| processed \| failed \| read (povolené: `delivered`, `processed`, `failed`, `read`)
note	string	optional	Voliteľ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/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 nastaviť cez multipart fields {"document_type":"self_billing"}. Max 20 MB. Polia missing_fields, field_sources a next_action tvoria checklist pre integrátora: čo doplniť, odkiaľ hodnota pochádza a čo spraviť ďalej. Ak OCR niečo neprečíta, pošlite rovnaký súbor znova a pridajte multipart field fields ako JSON, napr. {"vendor_dic":"2020123456","vendor_ic_dph":"SK2020123456","iban":"SK..."}. Rate limit: 10 extrakcií / minúta na firmu.

Parametre

Názov	Typ	Povinné	Popis
file	File	REQ	PDF, JPEG, PNG, WebP (max 20 MB)
fields	JSON string	optional	Optional 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/extract \
  -H "Authorization: Bearer eyJhbGc..." \
  -F "file=@invoice.pdf"

Príklady odpovedí

200 OK

{
  "extraction":{"invoiceNumber":"FAK-001","totalWithVat":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/extract/batch

Batch extrakcia max 50

Spracuje az 50 suborov naraz. Chyba jedneho neblokuje ostatne. Kazdy uspesny riadok vracia rovnaky review checklist ako POST /api/v1/extract: missing_fields, field_sources a next_action. Outbound štandardné faktúry vrátia direction=outbound a send_payload na samostatné review + POST /api/v1/documents/send; nepodporované outbound typy vrátia per-file kód OUTBOUND_OCR_UNSUPPORTED_DOCUMENT_TYPE. Rate limit: 3 požiadavky / minúta na firmu. Celková veľkosť max 200 MB na požiadavku.

Parametre

Názov	Typ	Povinné	Popis
files	File[]	REQ	Pole suborov max 50 x 20 MB

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/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/documents/validate

Validovať dokument

Validuje dokument oproti Peppol BIS 3.0 pravidlám. Podporuje JSON aj UBL XML vstup. Maximum tela požiadavky 6 MB. Vyžaduje API plán (api-enterprise priamo alebo integrator-managed cez spravujúceho integrátora).

Parametre

Názov	Typ	Povinné	Popis
format	string	REQ	"json" \| "ubl" (povolené: `json`, `ubl`)
document	object\|string	REQ	JSON objekt alebo UBL XML string

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/documents/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

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ázov	Typ	Povinné	Popis
receiverParticipantId	string	optional	Peppol ID príjemcu, napr. `0245:2020123456` alebo `iso6523-actorid-upis::0245:2020123456`. Odporúčaný nový názov.
receiverPeppolId	string	optional	Alias pre `receiverParticipantId`.
senderParticipantId	string	optional	Voliteľné Peppol ID odosielateľa. Ak je uvedené, musí sedieť s autentifikovanou firmou.
documentTypeId	string	optional	Peppol document-type URN. Default je BIS Billing 3.0 Invoice.
processId	string	optional	Peppol process ID. Default je `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`.
ublDocument	string	optional	Raw UBL XML dokument na validáciu. Alias `xml` je podporovaný.
documentType	string	optional	Skratka pre invoice profil. Pre non-invoice profily používajte `documentTypeId`. (povolené: `invoice`)
invoice	object	optional	JSON faktúra na validáciu
xml	string	optional	Alias pre `ublDocument`

Príklady volania

cURL

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/documents/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 rešpektuje items[].vatCategoryCode rovnako ako /documents/send, takže ho môžete použiť na kontrolu vygenerovaných TaxSubtotalov pred odoslaním.

Parametre

Názov	Typ	Povinné	Popis
input_format	string	REQ	"json" \| "ubl" (povolené: `json`, `ubl`)
output_format	string	REQ	"ubl" \| "json" (povolené: `ubl`, `json`)
document	object\|string	REQ	Dokument na konverziu

Príklady volania

cURL 1

curl -X POST https://epostak.sk/api/v1/documents/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/documents/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ázov	Typ	Povinné	Popis
xml	string	REQ	UBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/documents/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/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ázov	Typ	Povinné	Popis
xml	string	REQ	Raw UBL XML body, or the xml field when Content-Type is application/json. Max 20 MB.
source	string	optional	Optional JSON-only source label such as email, sftp, manual or migration. Stored as import_source metadata.
messageId	string	optional	Optional JSON-only external message ID. If omitted, the API stores import:{documentId}.
documentTypeId	string	optional	Optional JSON-only Peppol document-type URN override. Defaults from the parsed invoice type.
processId	string	optional	Optional JSON-only Peppol process URN override. Defaults from the parsed invoice type.
Idempotency-Key	header	optional	Optional 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 spravovaných firiem v jednej odpovedi. Vyžaduje JWT získané zo sk_int_* kľúča. Vysledky su obmedzene na dokumenty s createdAt >= integratorFirm.createdAt — integratori vidia len dokumenty dorucene po tom, ako bol integrator priradeny k danej firme. Priame dashboard sessions (bez integratorského kontextu) zobrazia vsetky dokumenty bez tohto obmedzenia.

Parametre

Názov	Typ	Povinné	Popis
since	string	optional	ISO 8601 — dokumenty od dátumu
status	string	optional	Filter 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_id	string	optional	Filtrovať podľa firmy
offset	number	optional	Posunutie pre stránkovanie
limit	number	optional	Max 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

Notifikacie v realnom case. Vyžaduje API plán (api-enterprise priamo alebo integrator-managed cez spravujúceho integrátora). HMAC-SHA256 podpis. 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) je status-code-aware: retryujeme 408, 425, 429, 502, 503, 504 a network errors až do 10 pokusov (1 prvotný + 9 retry-ov) s bounded backoffom 30s → 2m → 10m → 30m → 2h → 6h → 12h → 24h (celkom ~44h). Pri retryable odpovedi s Retry-After čakáme minimálne túto hodnotu, max 24h na pokus. Terminálne kódy 400/401/403/404/405/410/413/415/422/500/501 končia okamžite ako FAILED, žiadny retry — receiver ktorý chce retry na transient 500 nech vráti 503. Timeout per request 10 s. Po terminálnom zlyhaní subscription failedAttempts sa zvýši o 1; úspešné doručenie ho znižuje o 1 (nikdy pod 0). Auto-disable po 20 po sebe idúcich terminálnych zlyhaniach bez úspechu medzi nimi. SSRF blok je terminálny a bumpuje counter.

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.
Legacy webhook-queue ostáva compatibility povrch.

Events pull Create webhook Batch 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.

Deliveries Dead letters

Push vs pull — Každá subscription je buď push (POST na vašu URL) alebo pull (event v queue, ktorú periodicky čítate cez preferovaný alias GET /api/v1/events/pull; legacy GET /api/v1/webhook-queue ostáva podporovaný). 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 / item v pull queue obsahuje obálku { event, event_version: "1", webhook_id, webhook_event_id, timestamp, data }. event_version je verzia schémy. webhook_id je per-delivery (push only, null v pull queue). webhook_event_id (od 2026-05-12) je VŽDY UUID — stabilná identifikácia per-logical-event, rovnaká hodnota cez všetky retry-e tej istej delivery aj cez push+pull rozdelenie. Použite ju ako primárny dedup key na strane receiveru (INSERT ON CONFLICT DO NOTHING). Pre pull subscription je to zároveň ack key (DELETE /api/v1/webhook-queue/{id}). data závisí od event-u — pre billing eventy obsahuje document_id, document_number, direction, doctype_key, status, previous_status, total_amount, currency, issue_date, due_date, sender_peppol_id, receiver_peppol_id. Per-event extras: sent_at (document.sent), received_at (document.received), delivered_at + as4_message_id (document.delivered), rejected_at + response_code + response_reason + responder (document.rejected), responded_at + response_code + response_reason (document.response_received), failure_reason + attempts (document.delivery_failed).

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

Vytvori novy webhook alebo pull-only event subscription. URL je voliteľná: ak ju vynecháte alebo dáte null, eventy čítate cez preferovaný GET /api/v1/events/pull; legacy /api/v1/webhook-queue ostáva podporovaný. 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ázov	Typ	Povinné	Popis
url	string \| null	optional	HTTPS URL pre push, alebo null/omit pre pull-only
events	string[]	optional	Predvolene 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. Všetky polia sú nepovinné.

Parametre

Názov	Typ	Povinné	Popis
url	string	optional	HTTPS URL
events	string[]	optional	Nove udalosti
isActive	boolean	optional	Aktivovat/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 syntetické POSTy okamžite a vráti agregovaný výsledok. mode=queued vytvorí reálne pending delivery riadky a doručenie nechá na produkčný webhook worker s retry/backoff politikou; odpoveď 202 obsahuje testRunId na sledovanie v histórii doručení. URL je znovu validovaná voči SSRF allowliste pred každým testom. Typ udalosti možno zadať buď ako query parameter ?event= (preferované) alebo v tele { event }. Parameter count (query alebo body) odošle viac test udalostí; povolený rozsah je 1..1000. Platné typy: document.sent, document.received, document.delivered, document.delivery_failed, document.rejected, document.response_received.

Parametre

Názov	Typ	Povinné	Popis
event	string	optional	Query 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`)
count	integer	optional	Query param or body field. Number of synthetic webhook POSTs to send in one test run. Valid range: 1..1000. Default: 1. (default: `1`)
mode	string	optional	direct sends immediately and waits for aggregate results. queued creates delivery rows and lets the production webhook worker process them. 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":250,"queued":250,"deliveryIdsTruncated":true,"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ázov	Typ	Povinné	Popis
limit	number	optional	1–100 (default: `20`)
offset	number	optional	Začiatok od (predvolene 0) (default: `0`)
cursor	string	optional	Opaque cursor from nextCursor in the previous response. Use instead of offset for stable pagination over large history.
status	string	optional	PENDING \| SUCCESS \| FAILED \| RETRYING (povolené: `PENDING`, `SUCCESS`, `FAILED`, `RETRYING`)
event	string	optional	Filter podľa typu udalosti
testRunId	string	optional	Filter deliveries created by POST /webhooks/{id}/test?mode=queued.
includeResponseBody	boolean	optional	When true, includes the responseBody field on each delivery record. Omitted by default to reduce payload size. 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ázov	Typ	Povinné	Popis
limit	number	optional	1–100 (default: `20`)
offset	number	optional	Začiatok od (predvolene 0) (default: `0`)
event	string	optional	Filter podľa typu udalosti
subscriptionId	string	optional	Filter na konkrétnu webhook subscription
includeResponseBody	boolean	optional	Ak true, vráti aj poslednú odpoveď ERP endpointu. (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ázov	Typ	Povinné	Popis
deliveryId	string	REQ	ID 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ázov	Typ	Povinné	Popis
deliveryId	string	REQ	ID z GET /api/v1/webhook-dead-letter
reason	string	optional	Krá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

Preferovaný názov pre pull stream udalostí v Enterprise reliability kontrakte. Po odoslaní čítajte nepotvrdené udalosti a potvrďte ich až po lokálnom uložení v ERP; ak spracujete viac položiek naraz, potvrďte ich cez POST /api/v1/events/batch-ack. Server drží stav cez acknowledge, takže klient nepotrebuje vlastný kurzor. Pôvodný endpoint /api/v1/webhook-queue zostáva podporovaný ako kompatibilný queue.

Parametre

Názov	Typ	Povinné	Popis
limit	integer	optional	Max 100 (default: `20`)
event_type	string	optional	Filter 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

{
  "items": [{
    "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

Preferovaný alias pre potvrdenie jedného pull eventu. Volanie je POST /api/v1/events/{eventId}/ack; starší DELETE /api/v1/webhook-queue/{eventId} zostáva podporovaný.

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

Preferovaný alias pre potvrdenie viacerých pull eventov. Enterprise reliability contract: acknowledge after local commit, nie pri načítaní eventu; pri retry spracovania nechajte event neacknutý a znovu ho načítajte z pull queue. Pôvodný endpoint /api/v1/webhook-queue/batch-ack zostáva podporovaný.

Parametre

Názov	Typ	Povinné	Popis
event_ids	string[]	REQ	Pole 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

Compatibility: webhook queue pull

Kompatibilný pôvodný endpoint pre pull eventy. Nové ERP integrácie majú používať preferovaný alias GET /api/v1/events/pull; vracia rovnaké nepotvrdené udalosti (oldest-first). Po spracovaní potvrďte každú udalosť cez /api/v1/events/{eventId}/ack alebo /api/v1/events/batch-ack.

Parametre

Názov	Typ	Povinné	Popis
limit	integer	optional	Max 100 (default: `20`)
event_type	string	optional	Filter podľa typu udalosti

Príklady volania

cURL

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

Príklady odpovedí

200 OK

{
  "items": [{
    "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

DELETE/api/v1/webhook-queue/{eventId}

Compatibility: webhook queue ack

Kompatibilný pôvodný endpoint pre ack jedného eventu. Nové ERP integrácie majú používať POST /api/v1/events/{eventId}/ack. Označí jednotlivú udalosť ako spracovanú (acknowledged) a vráti 200 s telom { acknowledged: true }.

Príklady volania

cURL

curl -X DELETE https://epostak.sk/api/v1/webhook-queue/11111111-1111-1111-1111-111111111111 \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK

{ "acknowledged": true }

Odpovede

200OK
401Unauthorized
403Forbidden
404Not Found

POST/api/v1/webhook-queue/batch-ack

Compatibility: webhook queue batch ack

Kompatibilný pôvodný endpoint pre batch ack. Nové ERP integrácie majú používať POST /api/v1/events/batch-ack. Hromadne potvrdí viaceré udalosti. Max 1000 ID v jednej požiadavke. Vráti 200 s telom { acknowledged: N }.

Parametre

Názov	Typ	Povinné	Popis
event_ids	string[]	REQ	Pole ID udalosti max 1000

Príklady volania

cURL

curl -X POST https://epostak.sk/api/v1/webhook-queue/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ú.

Parametre

Názov	Typ	Povinné	Popis
limit	number	optional	Max výsledkov (default 100, max 500) (default: `100`)
since	string	optional	ISO 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ázov	Typ	Povinné	Popis
event_ids	string[]	REQ	Pole 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.

Capabilities Participant 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.

Directory Preflight

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ázov	Typ	Povinné	Popis
scheme	string	REQ	4-ciferný ISO 6523 kód napr. 0245
identifier	string	REQ	Identifiká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ázov	Typ	Povinné	Popis
ico	string	optional	Slovak IČO, 6-8 digits. Mutually exclusive with other identifiers.
dic	string	optional	Slovak DIČ, 10 digits. Mutually exclusive with other identifiers.
icDph	string	optional	VAT ID, e.g. SK2020123456. Mutually exclusive with other identifiers.
peppolId	string	optional	Direct Peppol participant ID, e.g. 0245:2020123456.
scheme	string	optional	ISO 6523 scheme when using scheme+identifier instead of peppolId.
identifier	string	optional	Participant identifier when using scheme+identifier instead of peppolId.
documentTypeId	string	optional	Peppol document-type URN. Default is BIS Billing 3.0 Invoice.
processId	string	optional	Peppol 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ázov	Typ	Povinné	Popis
q	string	REQ	Hľadaný výraz min 2 znaky
country	string	optional	ISO kod krajiny napr. SK
page	integer	optional	Stranka vysledkov
page_size	integer	optional	Max 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ázov	Typ	Povinné	Popis
participant	object	REQ	Objekt { scheme, identifier }. scheme = 4-ciferný ISO 6523 kód (napr. 0245), identifier = identifikátor účastníka
documentType	string	optional	Konkrétny Peppol document-type URN pre overenie
documentTypes	array	optional	Pole 1-20 Peppol document-type URN hodnôt pre batch capability probe. Ak je vyplnené, má prednosť pred documentType.
processId	string	optional	Voliteľ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ázov	Typ	Povinné	Popis
participants	array	REQ	Pole 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ázov	Typ	Povinné	Popis
xml	string	REQ	UBL 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. Správa prístupu k firmám pre integrátorské kľúče (sk_int_*).

Managed firms

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

Firmy vznikajú alebo sa priraďujú po consent-e klienta.
X-Firm-Id určuje cieľovú firmu pri firm-scoped volaniach.

List firms Assign Keys

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.

Audit Licencie

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/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. Integrátori môžu pristupovať k dokumentom spravovaných klientov. Integratori vidia len dokumenty s createdAt >= integratorFirm.createdAt — teda dokumenty dorucene az po priradeni integrátora k firme. Priame dashboard sessions (bez integratorského kontextu) zobrazia vsetky dokumenty.

Parametre

Názov	Typ	Povinné	Popis
page	integer	optional	Stranka (default: `1`)
page_size	integer	optional	Max 100 (default: `20`)
direction	string	optional	inbound \| outbound (povolené: `inbound`, `outbound`)
status	string	optional	Filter podľa stavu
from	string	optional	ISO 8601 date
to	string	optional	ISO 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ázov	Typ	Povinné	Popis
scheme	string	REQ	ISO 6523 kód napr. 0245
identifier	string	REQ	Identifiká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/assign

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

Aktivuje firmu pre integrátorský účet 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. DÔLEŽITÉ: Priame priradenie funguje iba vtedy, keď už existuje neodvolaná IntegratorFirm väzba vytvorená po OAuth súhlase vlastníka alebo admina firmy. Plán firmy nie je súhlas konkrétnemu integrátorovi. Každé prvotné priradenie musí prejsť cez OAuth authorization_code flow, kde majiteľ alebo admin firmy explicitne klikne "Súhlasím". Bez existujúceho súhlasu endpoint vráti 403 CONSENT_REQUIRED.

Parametre

Názov	Typ	Povinné	Popis
dic	string	optional	DIČ firmy (10 číslic), preferované
ico	string	optional	IČ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

{
  "error": {
    "code": "CONSENT_REQUIRED",
    "message": "First-time firm claim requires explicit owner consent. Send the firm through the OAuth authorization_code flow at /oauth/authorize.",
    "docs": "/api/docs/enterprise#oauth-flow"
  }
}

Odpovede

201Created
400Bad Request
401Unauthorized
403Forbidden — CONSENT_REQUIRED
404Not Found
409Conflict
422Validation Error

POST/api/v1/firms/assign/batch

Hromadné priradenie firiem

Hromadne aktivuje až 50 firiem k integrátorskému účtu podľa DIČ alebo IČO. Preferujte `dics`; `icos` držíme kvôli spätnej kompatibilite. Rovnaké obmedzenia ako pri /firms/assign: táto cesta funguje iba pre firmy s existujúcou neodvolanou IntegratorFirm väzbou po OAuth súhlase. Prvotné priradenie vždy vyžaduje OAuth authorization_code flow.

Parametre

Názov	Typ	Povinné	Popis
dics	string[]	optional	Pole DIČ (max 50), preferované
icos	string[]	optional	Pole 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":"CONSENT_REQUIRED", "message":"First-time firm claim requires explicit owner consent. Send the firm through the OAuth authorization_code flow at /oauth/authorize." }
  ]
}

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. Použite ho na nájdenie id alebo keyPrefix kľúča vydaného cez /api/oauth/token.

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ľúč. Pošlite buď keyId z GET /api/v1/integrator/keys, alebo client_id/keyPrefix vrátený z /api/oauth/token. Endpoint nenechá zneplatniť posledný aktívny kľúč integrátora.

Parametre

Názov	Typ	Povinné	Popis
keyId	uuid	optional	UUID kľúča z GET /api/v1/integrator/keys
client_id	string	optional	sk_int_* keyPrefix/client_id vrátený z /api/oauth/token

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, tarifné sadzby a odhadovaný náklad. Použiteľné pre billing dashboard a kvótové upozornenia. Vyžaduje sk_int_* kľúč a scope account:read. Bez X-Firm-Id hlavičky — endpoint je integrátorský, nie firemný. billable obsahuje produkčné integrator-managed firmy, ktoré sa reálne fakturujú. sandbox obsahuje integrator-managed sandbox firmy, ktoré sa neúčtujú. productionEstimate ukazuje, koľko by stálo rovnaké využitie po preklopení sandbox firiem do produkcie. nonManaged sumarizuje firmy, ktoré sú prepojené ale platia si plán samé. perFirm rozpisuje skupiny. Keď billable prevádzka prekročí contactThreshold (5 000 / mesiac), exceedsAutoTier sa nastaví na true, auto-billing sa zastaví a obchod kontaktuje integrátora pre individuálnu zmluvu. Budúce prekročenie po preklopení sandboxu sledujte cez productionEstimate.exceedsAutoTier.

Parametre

Názov	Typ	Povinné	Popis
offset	integer	optional	Posun pre stránkovanie zoznamu firiem (default: `0`)
limit	integer	optional	Max 100 — počet firiem v firms (default: `50`)
period	string	optional	Aktuálne fakturačné obdobie vo formáte YYYY-MM (SK časová zóna). [response field]
nextResetAt	string	optional	ISO 8601 — kedy sa počítadlá vynulujú (1. deň ďalšieho mesiaca, SK polnoc v UTC). [response field]
billable.outboundCharge	number	optional	Tarifný náklad za odoslané dokumenty — sadzby aplikované na outboundCount ako agregát. [response field]
billable.totalCharge	number	optional	Súčet outbound + inbound API. Zaokrúhlené na centy. [response field]
sandbox.totalCharge	number	optional	Neúčtovaný sandbox odhad pri aktuálnej sandbox prevádzke. [response field]
productionEstimate.totalCharge	number	optional	Odhad ceny, ak by sandbox integrator-managed firmy bežali v produkcii. [response field]
exceedsAutoTier	boolean	optional	true keď billable produkčný outbound alebo inbound prekročí contactThreshold. Auto-billing sa zastaví, obchod riadi manuálne. [response field]
contactThreshold	integer	optional	Hranica (5 000) nad ktorou sa vyžaduje individuálna zmluva. [response field]
firms[].managed	boolean	optional	true = 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[].sandbox	boolean	optional	true = firma je sandbox a neúčtuje sa. [response field]
firms[].billable	boolean	optional	true = 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": 5000,
  "pricing": {
    "model":"tiered","currency":"EUR",
    "outboundTiers":[
      {"upTo":1000,"rate":0.10},
      {"upTo":2000,"rate":0.08},
      {"upTo":5000,"rate":0.06},
      {"upTo":null,"rate":null,"label":"Individuálne","contactRequired":true}
    ],
    "inboundApiTiers":[
      {"upTo":1000,"rate":0.08},
      {"upTo":2000,"rate":0.07},
      {"upTo":5000,"rate":0.06},
      {"upTo":null,"rate":null,"label":"Individuálne","contactRequired":true}
    ]
  },
  "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.

Usage Submissions

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ázov	Typ	Povinné	Popis
period	string	optional	month \| quarter \| year (default: `month`) (povolené: `month`, `quarter`, `year`)
from	string	optional	Začiatok obdobia ISO 8601
to	string	optional	Koniec 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ázov	Typ	Povinné	Popis
limit	number	optional	Max 100 (default: `20`)
offset	number	optional	Posun pre stránkovanie (default: `0`)
report_type	string	optional	EUSR \| 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

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 codes Rate limits

Commercial and retention

Pricing, archive a SLA 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.

Pricing Retention

Non-breaking adoption contract. Nové facade endpointy sú additívne: existujúce integrácie nemusia prepisovať funkčný kód. Ak už používate /api/v1/extract, /api/v1/documents/validate, /api/v1/webhook-queue alebo /api/v1/documents/{id}/evidence-bundle, tieto endpointy zostávajú podporované. Nové implementácie majú preferovať ľahší tok /api/v1/payloads/extract, /api/v1/events/pull a /api/v1/documents/{id}/support-packet, ale migráciu môžete robiť postupne podľa release okna ERP.

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.

Objem	Cena
Neobmedzene	zadarmo

Odoslané

Cena za dokument odoslaný cez Peppol.

Objem	Cena
1 – 1 000	0,10 €
1 001 – 2 000	0,08 €
2 001+	0,06 €
5 000+	individuálne

Prijaté cez API

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

Objem	Cena
1 – 1 000	0,08 €
1 001 – 2 000	0,07 €
2 001+	0,06 €
5 000+	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.

Status	Kód	Popis
400	`BAD_REQUEST`	Neplatné JSON telo alebo chýbajúce pole
400	`INVALID_PARAM`	Neplatná hodnota query parametra
401	`UNAUTHORIZED`	Chýbajúci alebo neplatný API kľúč
403	`FORBIDDEN`	Nedostatočný scope alebo prístup k cudzej firme; alebo firma nemá API-eligible plán
404	`NOT_FOUND`	Prostriedok neexistuje alebo nepatrí vašej firme
409	`CONFLICT`	Duplikát (OAuth klient, priradenie firmy, idempotency in-flight)
409	`IDEMPOTENCY_IN_FLIGHT`retryable	Rovnaký Idempotency-Key už spracúva rovnaký payload; počkajte a skontrolujte stav neskôr
413	`PAYLOAD_TOO_LARGE`	Telo požiadavky presahuje povolený limit
422	`VALIDATION_ERROR / UNPROCESSABLE_ENTITY`	JSON alebo povinné polia neprešli vstupnou validáciou; opravte payload
422	`UBL_VALIDATION_ERROR`	UBL je syntakticky spracované, ale porušuje Peppol/CEN pravidlo; pozrite details[].rule
422	`IDEMPOTENCY_KEY_MISMATCH`	Rovnaký Idempotency-Key bol znovu použitý s iným kanonizovaným telom
422	`participant_not_found`	Katalóg príjemcov: prijímateľ sa nenašiel v Peppol/SMP; retryable=false; fix_hint=zmeňte alebo overte Peppol ID príjemcu
422	`receiver_unsupported_document_type`	Katalóg príjemcov: prijímateľ existuje, ale nepodporuje zvolený document type/profile; retryable=false; fix_hint=zmeňte typ dokladu alebo capability
422	`validation_failed`	Validácia payloadu: UBL/JSON sémantická validácia zlyhala; retryable=false; fix_hint=opravte payload podľa details/rule
502	`temporary_transport_error`retryable	Transport: AP alebo sieťová závislosť dočasne zlyhala; retryable=true; fix_hint=opakujte s rovnakým Idempotency-Key
409	`delivery_dead_lettered`	Doruč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
422	`duplicate_idempotency_key`	Idempotencia: 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
429	`RATE_LIMITED`retryable	Prekročený rate limit
500	`INTERNAL_ERROR`retryable	Neočakávaná chyba servera
502	`SEND_FAILED`retryable	Odoslanie cez Peppol AP zlyhalo
503	`IDEMPOTENCY_STORE_UNAVAILABLE`retryable	Dočasne nedostupný idempotency store; opakujte s rovnakým Idempotency-Key
503	`VALIDATION_SERVICE_UNAVAILABLE`retryable	Dočasne nedostupný validačný engine; opakujte s backoffom

Uchovávanie dát

Archív počas kontraktu

Enterprise API uchováva 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). Endpointy /documents/{id} a /documents/{id}/ubl ostávajú dostupné počas aktívneho kontraktu a dohodnutého odstupného obdobia po jeho ukončení. Poskytovateľ vyvíja primerané úsilie na cieľ dostupnosti 99,5 % podľa VOP a podpora sa riadi programom; 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

API archív a zálohy sú viazané na zmluvný vzťah: počas aktívneho kontraktu plus dohodnuté odstupné obdobie po ukončení na export, audit alebo migráciu. Signované AS4 obálky a transportné dôkazy uchovávame ako infraštruktúru Access Pointu, no Enterprise API nie je samostatná účtovná archivácia mimo kontraktu. Po odstupnom období sa API prístup uzatvára.

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 kontraktu a odstupného obdobia, no formálne nepreberá povinnosť účtovnej archivácie zákazníka.