Enterprise API

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 sprievodcoviaOdosielanieAko vytvoriť faktúru, poslať hotový UBL a sledovať výsledok.4 sprievodcoviaPríjem a importAko čítať prijaté dokumenty, importovať mimo-Peppol UBL a rozhodnúť sa medzi pull a webhookmi.3 sprievodcoviaBezpeč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 sprievodcoviaPrevá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.

1

Overiť príjemcu

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

2

Poslať hotový UBL XML

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

3

Prijímať dokumenty

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

4

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

  1. 1Vezmite client_id a client_secret z API kľúča.
  2. 2Zavolajte POST /api/v1/auth/token s grant_type client_credentials.
  3. 3Používajte access_token ako Authorization: Bearer.
  4. 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ázovTypPovinnéPopis
grant_typestringánoPoužite client_credentials.
client_idstringánoPrefix alebo identifikátor API kľúča.
client_secretstringánoPlaintext sk_live_* alebo sk_int_* hodnota uložená vo vašom secret manageri.
X-Firm-IdheadernieNeposiela sa na token endpoint; 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

  1. 1Rozdeľte Peppol ID na scheme a identifier.
  2. 2Pošlite documentType alebo documentTypes[] pre presné typy.
  3. 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": "0000000001"
5  },
6  "documentTypes": [
7    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
8    "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
9  ]
10}

Response

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

Povinné polia

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

Práca so stavmi

found=true

Účastník existuje v SMP.

networkReady=true

Pre daný typ dokumentu existuje použiteľná routa.

accepts=false

Účastník existuje, ale neprijíma požadovaný document type.

Chyby

400 INVALID_PARAMS

Scheme, identifier alebo documentTypes[] majú neplatný tvar.

404 NOT_FOUND

Účastník nie je registrovaný v Peppol SMP.

Ďalšie kroky

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

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

  1. 1Overte príjemcu cez capabilities, hlavne ak ho ešte nemáte v adresári.
  2. 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.
  3. 3Pre self-billing použite UBL XML mode: receiverPeppolId je dodávateľ, AccountingCustomerParty je vaša autentifikovaná firma a InvoiceTypeCode je 389.
  4. 4Uložte documentId/submissionId, messageId, status link a payloadSha256.
  5. 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:0000000001",
3  "receiverName": "Zakaznik Demo s.r.o.",
4  "receiverIco": "12345678",
5  "receiverDic": "0000000001",
6  "receiverIcDph": "SK0000000001",
7  "receiverStreet": "Testovacia 1",
8  "receiverCity": "Bratislava",
9  "receiverPostalCode": "811 01",
10  "receiverCountry": "SK",
11  "invoiceNumber": "FA-2026-001",
12  "issueDate": "2026-07-01",
13  "dueDate": "2026-07-15",
14  "currency": "EUR",
15  "paymentMethod": "bank_transfer",
16  "iban": "SK9811000000000000000001",
17  "variableSymbol": "2026001",
18  "buyerReference": "PO-2026-0001",
19  "note": "Služby za obdobie jún 2026. Príloha: akceptačný protokol.",
20  "prepayments": [
21    {
22      "advanceInvoiceRef": "ZAL-2026-0004",
23      "taxDocumentRef": "DDP-2026-0022",
24      "settlementDate": "2026-02-23",
25      "amountWithoutVat": 1000,
26      "vatAmount": 230,
27      "amountWithVat": 1230,
28      "vatRate": 23
29    }
30  ],
31  "items": [
32    {
33      "description": "Implementačné práce",
34      "quantity": 16,
35      "unit": "HUR",
36      "unitPrice": 75,
37      "vatRate": 23,
38      "vatCategoryCode": "S",
39      "discount": 5,
40      "deliveryDate": "2026-06-30"
41    },
42    {
43      "description": "Servisná podpora",
44      "quantity": 1,
45      "unit": "C62",
46      "unitPrice": 240,
47      "vatRate": 23,
48      "vatCategoryCode": "S"
49    }
50  ],
51  "attachments": [
52    {
53      "fileName": "akceptacny-protokol.pdf",
54      "mimeType": "application/pdf",
55      "content": "JVBERi0xLjQKJc...",
56      "description": "Podpísaný akceptačný protokol"
57    }
58  ]
59}

Self-billing UBL payload

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

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

Response

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

Polia požiadavky

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

Práca so stavmi

SENT

Payload prešiel validáciou a odoslanie bolo prijaté na spracovanie.

DELIVERED

AS4 doručenie bolo potvrdené access pointom príjemcu.

RESPONSE_RECEIVED

Príjemca poslal Invoice Response; spracujte AP/RE/PD/UQ ako obchodnú odpoveď.

Chyby

422 VALIDATION_ERROR

JSON alebo XML neprešlo vstupnou validáciou. Opravte payload a skúste znova.

422 RECIPIENT_NOT_REACHABLE

Príjemca nie je dostupný pre daný typ dokumentu. Nič sa neodoslalo ani nefakturuje.

503 VALIDATION_SERVICE_UNAVAILABLE

Dočasná chyba validačnej služby. Retryujte s rovnakým Idempotency-Key.

Ďalšie kroky

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

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

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

Postup

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

Endpoint

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

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

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

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

Najdôležitejšie polia

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

5. Poslať hotový UBL XML

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

Postup

  1. 1Vygenerujte UBL Invoice alebo CreditNote v Peppol BIS Billing 3.0.
  2. 2Pošlite { receiverPeppolId, xml } na /documents/send s Idempotency-Key.
  3. 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">0000000001</cbc:EndpointID>
12    </cac:Party>
13  </cac:AccountingCustomerParty>
14  <cac:InvoiceLine>...</cac:InvoiceLine>
15</Invoice>

Response

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

Povinné polia

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

Práca so stavmi

SENT

UBL prešiel validáciou a bol odoslaný alebo prijatý na odoslanie.

SENT_DB_PENDING

Transport prebehol, lokálny stav sa dorovná reconciliation workerom.

Chyby

422 UBL_VALIDATION_ERROR

XML je dobre formované, ale porušuje Peppol/CEN pravidlo.

403 SENDER_MISMATCH

Party, ktorá má patriť autentifikovanej firme, sa nezhoduje. Pri štandardnej faktúre je to supplier; pri self-billing customer.

Ďalšie kroky

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

6. Sledovať životný cyklus dokladu

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

Postup

  1. 1Pollujte /documents/{id}/status pre aktuálny stav.
  2. 2Použite /outbound/events pre cursor stream udalostí.
  3. 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ázovTypPovinnéPopis
idstringánodocumentId alebo submissionId zo send odpovede.
cursorstringniePri event streame cursor z predchádzajúcej odpovede.

Práca so stavmi

SENT

Doklad bol odoslaný na Peppol transport alebo je prijatý na odoslanie.

DELIVERED

Access point príjemcu potvrdil doručenie.

REJECTED

Príjemca alebo validačná vrstva odmietla doklad.

Chyby

404 NOT_FOUND

Doklad neexistuje, patrí inej firme alebo ešte nie je v danej projekcii.

409 PENDING

Niektoré dôkazové artefakty môžu vzniknúť až pár minút po transporte.

Ďalšie kroky

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

7. Prijímať dokumenty

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

Postup

  1. 1Pollujte /inbound/documents s limitom.
  2. 2Spracujte metadata a stiahnite raw UBL podľa links.ubl.
  3. 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:0000000001",
9      "receivedAt": "2026-07-01T09:15:30.000Z",
10      "links": {
11        "document": "/api/v1/inbound/documents/inb_01JZ8...",
12        "ubl": "/api/v1/inbound/documents/inb_01JZ8.../ubl",
13        "ack": "/api/v1/inbound/documents/inb_01JZ8.../ack"
14      }
15    }
16  ],
17  "next_cursor": "eyJpZCI6ImluYl8wMU..."
18}

Povinné polia

NázovTypPovinnéPopis
cursorstringnieCursor z predchádzajúcej odpovede next_cursor.
limitintegernieMax počet dokumentov na stránku; držte stabilnú hodnotu pri pollingu.
X-Firm-IdheaderniePovinné 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.

8. Importovať prijatý UBL

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

Postup

  1. 1Pošlite raw XML alebo JSON s xml.
  2. 2Skontrolujeme receiver identity proti firme.
  3. 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ázovTypPovinnéPopis
xmlstringánoUBL XML payload, raw body alebo JSON pole xml.
sourcestringniePôvod importu, napr. email, sftp alebo migration.
messageIdstringnieExterný audit identifikátor z pôvodného kanála. Dedup/retry kontrakt používa Idempotency-Key.

Práca so stavmi

RECEIVED

UBL bol uložený do inbound schránky a správa sa ako sieťovo prijatý dokument.

duplicate: true

Rovnaký Idempotency-Key s rovnakým XML a metadátami vráti pôvodný dokument bez nového uploadu.

Chyby

422 RECEIVER_MISMATCH

Receiver party nepatrí firme, v mene ktorej importujete: pri štandardnej faktúre AccountingCustomerParty, pri self-billing AccountingSupplierParty.

422 INVALID_UBL

XML nie je čitateľný UBL doklad.

Ďalšie kroky

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

9. Webhook fallback alebo Events pull

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

Postup

  1. 1Pre push nastavte URL a overujte HMAC podpis.
  2. 2Pre pull fallback vytvorte subscription bez URL a čítajte Events pull.
  3. 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ázovTypPovinnéPopis
urlstring | nullnieVerejný HTTPS receiver pre push; null pre Events pull.
events[]string[]ánoTypy udalostí, napr. document.received alebo document.response_received.
X-Webhook-SignatureheaderánoHMAC podpis prijatého push webhooku.

Práca so stavmi

active

Subscription prijíma alebo frontuje udalosti.

failedAttempts

Po terminálnych zlyhaniach sa counter zvyšuje; úspech ho znižuje.

auto-disabled

Po opakovaných terminálnych chybách sa push subscription vypne.

Chyby

400 INVALID_URL

URL nie je verejný HTTPS endpoint alebo narazila na SSRF guard.

410 GONE

Receiver signalizuje trvalé vypnutie; retry sa nerobí.

Ďalšie kroky

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

10. Bezpečnosť, identita a úložisko

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

Postup

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

Práca so stavmi

scoped

Volanie je naviazané na 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.

11. ePošťák Box workflow

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

Postup

  1. 1POST /api/v1/box/items je Enterprise skratka nad stagingom; Connector /outbox používa rovnakú Box vrstvu pre ERP-first flow.
  2. 2Každá položka dostane boxItemId, status, payloadSha256, retention a links na ďalšie akcie.
  3. 3Detail vracia bezpečný storage summary a timeline, nie raw UBL alebo plaintext object key.
  4. 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:0000000001",
7    "receiverName": "Zakaznik s.r.o.",
8    "invoiceNumber": "FA-2026-001",
9    "items": [
10      {
11        "description": "Servisna podpora",
12        "quantity": 1,
13        "unitPrice": 240,
14        "vatRate": 23
15      }
16    ]
17  }
18}

Stage response

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

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

Detail storage summary

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

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

Polia Box položky

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

Práca so stavmi

ready

Položka je pripravená na odoslanie.

scheduled

Worker ju odošle po scheduledFor a podľa tenant/rate limitov.

needs_repair

Preflight alebo mapping našiel blokujúci problém; opravte dáta a skúste odoslanie znovu.

failed

Transport alebo spracovanie zlyhalo; pozrite lastError a timeline.

Chyby

409 DISPATCH_POINTER_UNAVAILABLE

send-now nemá Connector/Enterprise pointer; použite detail a repair flow.

422 INVALID_SCHEDULE

scheduledFor musí byť budúci ISO čas.

Ďalšie kroky

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

12. Dôkazy a retencia

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

Postup

  1. 1Po send-e uložte documentId/submissionId, Peppol messageId a payloadSha256.
  2. 2Pollujte status alebo outbound events, kým transport a evidence state nedávajú očakávaný výsledok.
  3. 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ázovTypPovinnéPopis
documentIdstringánoID z odpovede send/status alebo Connector detailu.
messageIdstringniePeppol korelácia na transportnej vrstve.
payloadSha256stringnieHash payloadu, ktorý v supporte pomáha bez posielania celého XML.

Práca so stavmi

bundleReady

ZIP s dostupnými technickými artefaktmi je pripravený na stiahnutie.

PENDING

Niektoré artefakty sa ešte vytvárajú; skúste požiadavku zopakovať neskôr.

Chyby

404 NOT_FOUND

Doklad nepatrí firme alebo evidence endpoint preň zatiaľ nemá artefakt.

409 PENDING

Dôkazový balík ešte nie je kompletný.

Ďalšie kroky

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

13. Riešiť zlyhané odoslanie

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

Postup

  1. 1Pozrite HTTP status a error.code.
  2. 2Pri retry použite rovnaký Idempotency-Key.
  3. 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:0000000001",
3  "receiverName": "Zakaznik s.r.o.",
4  "items": []
5}

Response

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

Povinné polia

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

Práca so stavmi

retryable

503 alebo dočasné transportné chyby opakujte s rovnakým idempotency key.

fix payload

422 VALIDATION_ERROR/UBL_VALIDATION_ERROR vyžaduje opravu dát.

track status

SENT_DB_PENDING alebo prijaté send ID sledujte cez status/eventy.

Chyby

422 VALIDATION_ERROR

JSON schema alebo povinné polia zlyhali; opravte vstup.

422 UBL_VALIDATION_ERROR

UBL porušuje Peppol/CEN pravidlá; opravte XML alebo mapping.

409 IDEMPOTENCY_IN_FLIGHT

Rovnaký kľúč už beží; počkajte a skontrolujte stav neskôr.

Ďalšie kroky

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

14. Enterprise reliability contract

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

Postup

  1. 1Capability: zavolajte POST /api/v1/peppol/capabilities a branchujte podľa networkReady, matchedDocumentTypes a routing statusu.
  2. 2Preflight: zavolajte POST /api/v1/documents/preflight pre rovnaký documentTypeId/processId a blokované výsledky opravte pred sendom.
  3. 3Send: POST /api/v1/documents/send opakujte iba s rovnakým Idempotency-Key, ak ide o ten istý payload.
  4. 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.
  5. 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:0000000001",
4    "networkReady": true,
5    "matchedDocumentTypes": ["urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##..."]
6  },
7  "send": {
8    "idempotencyKey": "erp-FAK-2026-001",
9    "documentId": "doc_01JZ8...",
10    "requestId": "req_01JZ8..."
11  },
12  "events": {
13    "lastEventCursor": "evt_cur_01JZ8...",
14    "ackPolicy": "acknowledge after local commit"
15  },
16  "support": {
17    "supportPacket": "/api/v1/documents/doc_01JZ8.../support-packet",
18    "payloadSha256": "7f9c..."
19  }
20}

Čo má ERP ukladať

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

Práca so stavmi

networkReady=true

Príjemca prijíma daný typ dokladu; pokračujte preflightom.

preflight blocked

Payload alebo routing opravte pred sendom; neposielajte naslepo.

event unacked

Event ostáva na opakované načítanie, kým ho ERP po lokálnom commite nepotvrdí.

Chyby

participant_not_found

Biznis chyba z capability/preflight; neopakujte bez opravy identifikátora.

temporary_transport_error

Retryable runtime chyba; opakujte s backoffom a rovnakým Idempotency-Key.

delivery_dead_lettered

Pre support použite events, requestId a support-packet pred manuálnym retry.

Ďalšie kroky

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

15. Vybrať Connector alebo Enterprise API

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

Postup

  1. 1Vyberte Connector pre rýchly ERP inbox/outbox.
  2. 2Vyberte Enterprise API pre vlastný lifecycle a dôkazy.
  3. 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ázovTypPovinnéPopis
Connectorproduct pathnieManaged ERP tok: mailbox, mapper, outbox, sync a repair report.
Enterprise APIproduct pathnieKontrolovaná API vrstva: send, inbound, webhooky, dôkazy, multi-firm.
SAPIcompatibility pathnieTransport-only kompatibilita so SAPI-SK, nie dashboard ani Connector flow.

Práca so stavmi

Connector

Najlepšie pre ERP tímy, ktoré chcú rýchly managed flow.

Enterprise API

Najlepšie pre platformy a integrátorov so step-level kontrolou.

SAPI

Použite iba keď potrebujete štandardný transportný kontrakt.

Chyby

Wrong abstraction

Ak ERP tím začne Enterprise API bez potreby vlastného lifecycle, integrácia bude zbytočne dlhšia.

Missing firm context

Pri 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 prijatie integrátorskej žiadosti o súhlas, 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: V partnerskej zóne v časti Firmy alebo cez POST /api/internal/integrator/consent-requests vytvoríte pozvánku na integrátorský súhlas. Vlastník alebo admin firmy potvrdí presné oprávnenia a systém uloží nemenný KYC dôkaz. Až potom možno použiť /oauth/authorize a POST /api/oauth/token na vydanie samostatného firemného sk_live_* kľúča. OAuth samotný firmu nepripája ani neobnovuje odvolaný súhlas.
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 účtyAuth token

Core documents

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

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

Alternative formats

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

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

Integration

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

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

Partner/admin

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

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

Autentifikácia

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

Introspekcia kľúča

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Rotovať API kľúč

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Info o konte

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Audit log firmy

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 401Neplatný alebo chýbajúci token.
  • 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ázovTypPovinnéPopis
namestringREQNázov OAuth klienta
redirect_urisstring[]REQPovolené redirect URI (HTTPS alebo localhost)
logo_urlstringoptionalURL loga zobrazené na consent obrazovke

Príklady odpovedí

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

Odpovede

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

Autorizačná URL

Presmerujte klienta na túto URL. Po schválení bude presmerovaný späť na redirect_uri s kódom.

Parametre

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

Príklady volania

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

Odpovede

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

Výmena kódu za kľúč

Vymení autorizačný kód za nový firemný sk_live_* client_secret naviazaný iba na autorizovanú firmu. Firma už musí mať aktívny, neodvolaný súhlas s integrátorom a nemenný KYC dôkaz. OAuth nevytvára ani neobnovuje integrátorské prepojenie. Content-Type: application/x-www-form-urlencoded (odporúčané podľa RFC 6749) alebo application/json.

Parametre

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

Príklady odpovedí

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

Odpovede

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

Payload Assistant

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

Create payload

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

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

Validate before send

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

  • Validation nič neodosiela a nevytvára produkčný doklad.
  • Preflight pridáva Peppol routing a receiver capability kontrolu.
ValidatePreflight
Od vstupu k send payloadu. 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ázovTypPovinnéPopis
fileFileREQPDF, JPEG, PNG, WebP (max 20 MB)
fieldsJSON stringoptionalOptional OCR overrides. Examples: vendor_ico, vendor_dic, vendor_ic_dph, iban, payment_means_code, invoice_number, due_date, document_type=self_billing.

Príklady volania

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

Príklady odpovedí

200 OK
{
  "extraction":{"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ázovTypPovinnéPopis
filesFile[]REQPole suborov max 50 x 20 MB

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

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ázovTypPovinnéPopis
xmlstringREQUBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

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ázovTypPovinnéPopis
input_formatstringREQ"json" | "ubl" (povolené: json, ubl)
output_formatstringREQ"ubl" | "json" (povolené: ubl, json)
documentobject|stringREQDokument na konverziu

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

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ázovTypPovinnéPopis
formatstringREQ"json" | "ubl" (povolené: json, ubl)
documentobject|stringREQJSON objekt alebo UBL XML string

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

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

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 sendSupport 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 prijatí integrátorskej žiadosti o súhlas vlastníkom alebo adminom 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringoptionalVoliteľ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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringREQID zákazníka v ERP.
policystringREQstage_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. Prijíma rovnaký JSON billing payload ako Connector send: odporúčaný je priamy tvar s receiverPeppolId, údajmi dokladu a items[] v koreni. Kompatibilný je aj obal {document: {...}}. Vráti dostupnosť príjemcu v Peppol/SMP, pripravenosť dokladu a správu o opravách bez vytvorenia alebo odoslania dokladu.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

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

Príklady volania

cURL
curl -X POST https://epostak.sk/api/v1/connector/preflight \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"receiverPeppolId":"0245:2123456789","receiverName":"Odberatel s.r.o.","invoiceNumber":"FA-2026-001","items":[{"description":"Servis","quantity":1,"unit":"C62","unitPrice":100,"vatRate":23,"taxTreatment":"standard"}]}'

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

Odošle JSON billing doklad cez riadený tok nad Enterprise API a vráti documentId použiteľný aj v plných Enterprise endpointoch. Odporúčaný request je priamy JSON tvar uvedený v tabuľke nižšie; ak použijete {document: {...}}, preferujte celý doklad vo vnútri. Legacy split obal ostáva kompatibilný iba pre explicitne zlúčené routing/documentType/supplier/prepayment polia. Odosielateľ sa vždy berie z autentifikovanej firmy, preto sender polia nepoužívajte.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

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

Príklady volania

cURL
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","receiverName":"Odberatel s.r.o.","invoiceNumber":"FA-2026-001","items":[{"description":"Servis","quantity":1,"unit":"C62","unitPrice":100,"vatRate":23,"taxTreatment":"standard"}]}'

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ší tolerantný vstup pre ERP. Tabuľka nižšie uvádza kanonický názov aj všetky akceptované aliasy, ktoré Zen normalizuje do Autopilot requestu. Textové a ID polia prijímajú neprázdny string alebo konečné JSON číslo; string sa oreže a číslo sa prevedie na string. Zen zámerne pokrýva bežné hlavičkové údaje a štyri základné polia položky; pre DPH kategórie, zálohy, prílohy a ostatné rozšírené polia použite presný /connector/autopilot payload. Pri previewOnly=true iba vráti normalizovaný request a odporúčané opravy.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstring|numberREQVaše ID zákazníka/firmy. Akceptované vstupy v poradí priority: customerRef, customer.ref, customer.id, clientId.
externalIdstring|numberoptionalERP ID dokladu. Akceptuje externalId alebo erpId; ak chýba, použije sa číslo faktúry.
idempotencyKeystring|numberoptionalKľúč opakovania. Akceptuje idempotencyKey alebo idempotency.key; ak chýba a existuje externalId, Zen vytvorí zen:{externalId}.
modeany JSONoptionalRozpoznané režimy sú shadow, stage a send. Neznáma alebo chýbajúca hodnota sa normalizuje na stage. (default: stage)
documentTypestring|numberoptionalRozpoznané typy sú invoice, credit_note, self_billing a self_billing_credit_note. Akceptuje documentType, document_type alebo docType; neznáma/chýbajúca hodnota sa zmení na invoice. (default: invoice)
invoiceNumberstring|numberoptionalČíslo dokladu. Akceptované vstupy: invoiceNumber, invoiceNo, number, document.invoiceNumber.
precedingInvoiceRefstring|numberoptionalČíslo pôvodnej faktúry; povinné pre oba credit-note typy. Akceptuje precedingInvoiceRef, preceding_invoice_ref, precedingInvoice, originalInvoiceNumber, correctedInvoiceNumber.
receiverPeppolIdstring|numberREQPeppol ID príjemcu. Akceptuje receiverPeppolId, receiver.peppolId, buyer.peppolId, customer.peppolId, supplierPeppolId alebo supplier.peppolId. Pri self-billing sa zapíše aj ako supplierPeppolId.
receiverNamestring|numberoptionalNázov protistrany. Akceptuje receiver.name, buyer.name, receiverName, supplierName, supplier.name.
receiverIcostring|numberoptionalIČO protistrany. Akceptuje receiver.ico, buyer.ico, receiverIco, supplierIco, supplier.ico.
receiverDicstring|numberoptionalDIČ protistrany. Akceptuje receiver.dic, buyer.dic, receiverDic, supplierDic, supplier.dic.
receiverIcDphstring|numberoptionalIČ DPH protistrany. Akceptuje receiver.icDph, buyer.icDph, receiverIcDph, supplierIcDph, supplier.icDph.
currencystring|numberoptionalMena. Akceptuje currency alebo currencyCode.
issueDatestring|numberoptionalDátum vystavenia. Akceptuje issueDate, issuedOn alebo date.
dueDatestring|numberoptionalDátum splatnosti. Akceptuje dueDate alebo dueOn.
variableSymbolstring|numberoptionalVariabilný symbol. Akceptuje variableSymbol alebo vs.
notestring|numberoptionalPoznámka. Akceptuje note alebo koreňové description.
itemsarrayREQPoložky. Akceptované názvy poľa: items, lines, invoiceLines, document.items.
items[].descriptionstring|numberREQPopis položky. Akceptuje description, name, title alebo text.
items[].quantitynumber|stringREQMnožstvo. Akceptuje quantity, qty, amount alebo count; desatinný string môže použiť bodku alebo čiarku.
items[].unitPricenumber|stringREQJednotková cena. Akceptuje unitPrice, price, unit_price alebo netPrice; desatinný string môže použiť bodku alebo čiarku.
items[].vatRatenumber|stringoptionalSadzba DPH. Akceptuje vatRate, vat alebo vatPercent. Ak chýba, presný payload neskôr vyžaduje opravu.
sendobjectoptionalObjekt pravidla odoslania. Alternatívne použite sendPolicy ako objekt alebo string policy.
sendPolicyobject|stringoptionalAlias pre send; string sa normalizuje na {policy: value}.
send.policystringoptionalAkceptované: stage_only, immediate, scheduled_at, daily_batch, paused. Rovnaké subpolia platia aj pre objekt sendPolicy. (povolené: stage_only, immediate, scheduled_at, daily_batch, paused)
send.sendAtstringoptionalISO 8601 čas pri scheduled_at.
send.dailySendTimestringoptionalLokálny čas HH:MM pri daily_batch.
send.timezonestringoptionalIANA časová zóna pri daily_batch.
previewOnlybooleanoptionalAk 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","name":"Odberatel s.r.o."},"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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
templateKeystringoptionalKľúč uloženého mapping template-u z Connector Mapper Studia, napr. pohoda-csv-v1.
sourceTypestringoptionaljson, csv, xml, text alebo pdf_text. Ak chýba a templateKey existuje, použije sa typ uložený v template.
sourceTextstringoptionalRaw CSV/XML/PDF-text export z ERP.
sourceJsonobjectoptionalJSON export z ERP, ak neposielate sourceText.
customerRefstringoptionalVaše ID zákazníka/firmy. Môže byť uložené aj v template defaults.
executestringoptionalpreview, 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:0000000001,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 spravovanej firmy, korelačné externalId/idempotencyKey a celý JSON billing doklad v payload. Polia payload.* sú presne vypísané nižšie. ePošťák podľa customerRef nájde Connector Schránku, overí súhlas firmy a podľa režimu doklad skontroluje, uloží alebo odošle.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringREQVaše ID zákazníka/firmy. Mapuje sa na Connector Schránku vytvorenú po súhlase firmy. Kompatibilne ho možno poslať aj ako options.customerRef.
modestringoptionalshadow = kontrola bez uloženia, stage = uložiť do schránky/outboxu, send = požiadať o vykonanie pravidla v send.policy. Bez pravidla sa použije immediate, ale ak schránka nie je pripravená alebo má vypnutý auto-send, runtime bezpečne zmení akciu na stage_only. (default: shadow) (povolené: shadow, stage, send)
externalIdstringoptionalERP identifikátor dokumentu pre deduplikáciu a spätné dohľadanie. Najviac 255 znakov; rovnaké ID s iným payloadom vráti 409.
idempotencyKeystringoptionalKľúč pre bezpečné opakovanie rovnakého Autopilot volania, najviac 255 znakov. Môže byť aj v hlavičke Idempotency-Key.
Idempotency-KeyheaderoptionalHlavičkový retry kľúč, najviac 255 znakov. Ak pošlete aj body idempotencyKey, body hodnota má prednosť.
X-Idempotency-KeyheaderoptionalKompatibilný alias pre Idempotency-Key.
sendobject|stringoptionalPravidlo odoslania ako objekt alebo priamo policy string. Alias sendPolicy akceptuje rovnaké hodnoty; kompatibilne možno použiť aj options.sendPolicy.
sendPolicyobject|stringoptionalAlias pre send. Root sendPolicy má prednosť pred send a options.sendPolicy.
optionsobjectoptionalKompatibilný obal pre options.customerRef a options.sendPolicy. Ostatné options sa uložia, ale nemenia dokument ani odoslanie.
options.customerRefstringoptionalFallback pre customerRef, ak koreňové pole chýba.
options.sendPolicyobject|stringoptionalFallback pre send policy, ak chýbajú koreňové sendPolicy aj send.
send.policystringoptionalPravidlo pre stage/send režim. immediate odošle iba pri pripravenej schránke so zapnutým auto-send; inak sa bezpečne zmení na stage_only. (povolené: stage_only, immediate, scheduled_at, daily_batch, paused)
send.sendAtstringoptionalISO 8601 čas odoslania pri policy=scheduled_at.
send.dailySendTimestringoptionalLokálny čas dávky HH:MM pri policy=daily_batch. Ak chýba, použije sa nastavenie schránky alebo 18:00.
send.timezonestringoptionalIANA časová zóna pre daily_batch, napr. Europe/Bratislava. Ak chýba, použije sa nastavenie schránky alebo Europe/Bratislava.
payloadobjectREQJSON billing doklad. Neobsahuje customerRef, mode ani send policy; tie patria do koreňa Autopilot requestu.
payload.documentTypestringoptionalBusiness typ JSON dokladu. Povolené: invoice, credit_note, self_billing, self_billing_credit_note. Ak chýba, použije sa invoice. (povolené: invoice, credit_note, self_billing, self_billing_credit_note)
payload.document_typestringoptionalSnake_case alias pre documentType. (povolené: invoice, credit_note, self_billing, self_billing_credit_note)
payload.docTypestringoptionalKompatibilný alias pre documentType. Neposielajte naraz rozdielne hodnoty aliasov. (povolené: invoice, credit_note, self_billing, self_billing_credit_note)
payload.receiverPeppolIdstringoptionalPeppol participant ID príjemcu vo formáte scheme:identifier, napr. 0245:2123456789. Pri invoice/credit_note je to kupujúci. Pri self-billing môžete namiesto neho poslať supplierPeppolId.
payload.supplierPeppolIdstringoptionalSelf-billing alias pre dodávateľa/príjemcu Peppol dokumentu. Povolené iba pri self_billing a self_billing_credit_note.
payload.itemsarrayREQPoložky faktúry. Povinné v JSON mode, 1 až 999 riadkov.
payload.items[].descriptionstringREQNázov alebo popis položky. Nesmie byť prázdny.
payload.items[].quantitynumberREQMnožstvo. Musí byť kladné číslo. Záporné množstvo je povolené iba pri items[].lineType=advance_deduction pre odpočet zálohy.
payload.items[].unitPricenumberREQCena za jednotku bez DPH. Nesmie byť záporná.
payload.items[].vatRatenumberREQSadzba DPH v %. Povolené: 0, 5, 10, 19, 20, 23; historická 20 % sadzba je podporovaná pre staršie doklady/opravné doklady. (povolené: 0, 5, 10, 19, 20, 23)
payload.items[].vatCategoryCodestringoptionalDPH kategória BT-151 podľa UNCL5305. Ak chýba, odvodíme ju zo sadzby: vatRate > 0 = S, vatRate 0 = Z. Pre prenesenie daňovej povinnosti pošlite AE. Najčastejšie: S = štandardná sadzba, Z = nulová sadzba, AE = prenesenie daňovej povinnosti. (povolené: S, Z, AE, E, K, G, O, L, M)
payload.items[].vatCategorystringoptionalAlias pre items[].vatCategoryCode. (povolené: S, Z, AE, E, K, G, O, L, M)
payload.items[].vat_categorystringoptionalSnake_case alias pre items[].vatCategoryCode. (povolené: S, Z, AE, E, K, G, O, L, M)
payload.items[].taxTreatmentstringoptionalVyšší ePošťák typ daňového režimu ako alternatíva k priamemu UBL kódu vatCategoryCode. Mapovanie: standard → S, zero_rate → Z, reverse_charge_domestic → AE, exempt → E, intra_community_supply → K, export → G, outside_scope → O. Ak pošlete aj vatCategoryCode, explicitný UBL kód má prednosť. (povolené: standard, zero_rate, reverse_charge_domestic, exempt, intra_community_supply, export, outside_scope)
payload.items[].tax_treatmentstringoptionalSnake_case alias pre items[].taxTreatment. (povolené: standard, zero_rate, reverse_charge_domestic, exempt, intra_community_supply, export, outside_scope)
payload.items[].discountnumberoptionalZľava v percentách, 0 až 100.
payload.items[].unitstringoptionalUN/ECE Rec 20 kód jednotky. Ak chýba, použije sa C62. Runtime normalizuje aj aliasy: ks→C62, hod→HUR, den→DAY, mes→MON, kg→KGM, m→MTR, l→LTR, km→KTM. (default: C62)
payload.items[].deliveryDatestringoptionalDátum dodania položky pre BT-134. Ak pošlete ISO timestamp, do UBL sa zapíše dátumová časť. Ak položkové dátumy použijete ako súhrnnú faktúru, musia byť v jednom kalendárnom mesiaci a issueDate musí byť najneskôr 15. deň po skončení tohto mesiaca.
payload.items[].lineTypestringoptionalTyp riadku. Použite advance_deduction pre záporný odpočet zálohy na finálnej faktúre. (povolené: standard, advance_deduction)
payload.items[].advanceInvoiceReferencestringoptionalČíslo zálohovej faktúry. Povinné pri lineType=advance_deduction; do UBL sa zapíše ako AdditionalItemProperty s názvom AdvanceInvoiceNumber.
payload.items[].customsTariffCodestringoptionalColný sadzobník / kombinovaná nomenklatúra pri prenesení daňovej povinnosti: 4 až 10 číslic. Do UBL sa zapisuje ako CommodityClassification/ItemClassificationCode listID="HS"; KV DPH A2 používa prvé 4 číslice ako TK.
payload.items[].commodityClassificationCodestringoptionalVšeobecný klasifikačný kód položky, ak nepoužívate customsTariffCode. Pri inom zozname než HS pošlite aj commodityClassificationListId.
payload.items[].commodityClassificationListIdstringoptionalIdentifikátor klasifikačného zoznamu podľa UNTDID 7143. Pri customsTariffCode sa použije HS.
payload.items[].reverseChargeParagraphLetterstringoptionalPísmeno §69 ods. 12 pre domácu evidenciu, napr. f alebo g. Do UBL sa zapisuje ako AdditionalItemProperty.
payload.items[].controlStatementTypestringoptionalTyp pre KV DPH A2 TD. Povolené: IO, MT. (povolené: IO, MT)
payload.items[].controlStatementQuantitynumberoptionalKladné množstvo pre KV DPH A2 Mn. Ak chýba a jednotka je známa, použije sa absolútna hodnota quantity.
payload.items[].controlStatementUnitstringoptionalJednotka pre KV DPH A2 MJ. Povolené: kg, t, m, ks. (povolené: kg, t, m, ks)
payload.invoiceNumberstringoptionalČíslo faktúry. Ak chýba alebo je prázdne, vygeneruje sa z číselného radu firmy.
payload.precedingInvoiceRefstringoptionalExterné číslo pôvodnej faktúry, ktorú dobropis opravuje. Povinné pri credit_note a self_billing_credit_note; do UBL sa zapíše ako BillingReference.
payload.issueDatestringoptionalDátum vystavenia. Ak chýba, použije sa aktuálny deň v časovej zóne Europe/Bratislava.
payload.dueDatestringoptionalDátum splatnosti.
payload.currencystringoptionalISO 4217 mena. Ak chýba, použije sa default firmy alebo EUR. (default: EUR)
payload.prepaidAmountnumberoptionalSuma zaplatená vopred (BT-113). Do UBL sa zapíše ako LegalMonetaryTotal/PrepaidAmount a zníži PayableAmount. Nekombinujte s riadkom advance_deduction.
payload.prepaymentsarrayoptionalŠtruktúrované zúčtované zálohy na finálnej faktúre. ePošťák spočíta prepayments[].amountWithVat do prepaidAmount, zníži PayableAmount a referencie záloh/daňových dokladov zachová v UBL poznámke. Nevytvára samostatný UBL daňový rozpad zálohy; daňové medzisúčty sa stále skladajú z položiek. Nekombinujte s riadkom advance_deduction.
payload.prepayments[].advanceInvoiceRefstringoptionalČíslo zálohy alebo zálohovej faktúry z IS.
payload.prepayments[].taxDocumentRefstringoptionalČíslo daňového dokladu k prijatej platbe.
payload.prepayments[].settlementDatestringoptionalZúčtovací dátum vo formáte YYYY-MM-DD.
payload.prepayments[].amountWithoutVatnumberoptionalZúčtovaná suma bez DPH.
payload.prepayments[].vatAmountnumberoptionalDPH zo zúčtovanej zálohy.
payload.prepayments[].amountWithVatnumberREQZúčtovaná suma vrátane DPH. Povinná; používa sa na výpočet BT-113 PrepaidAmount.
payload.prepayments[].vatRatenumberoptionalSadzba DPH zálohy, ak ju ERP vie poslať.
payload.prepayments[].vatCategoryCodestringoptionalVoliteľná DPH kategória zálohy, napr. S alebo AE. (povolené: S, Z, AE, E, K, G, O, L, M)
payload.paymentMethodstringoptionalSpôsob platby. Podporované sú ePošťák aliasy bank_transfer, credit_transfer, sepa, card, cash, direct_debit, alebo priamo UNCL4461 kód, napr. 30.
payload.variableSymbolstringoptionalVariabilný symbol / payment reference.
payload.buyerReferencestringoptionalReferencia kupujúceho, napr. číslo objednávky alebo interný nákupný odkaz.
payload.notestringoptionalVoľný text poznámky na faktúre. Pri nulovej DPH alebo špecifickom daňovom režime uveďte dôvod/oslobodenie, ktoré má vidieť príjemca.
payload.ibanstringoptionalIBAN pre platbu. Ak chýba, použije sa IBAN uložený pri firme, ak existuje.
payload.receiverNamestringoptionalObchodné meno príjemcu. Pri invoice/credit_note je to kupujúci; pri self-billing môžete použiť alias supplierName.
payload.receiverIcostringoptionalIČO príjemcu.
payload.receiverDicstringoptionalDIČ príjemcu.
payload.receiverIcDphstringoptionalIČ DPH príjemcu.
payload.receiverStreetstringoptionalUlica a číslo príjemcu. Preferované pred parsovaním jedného poľa receiverAddress.
payload.receiverCitystringoptionalMesto príjemcu.
payload.receiverPostalCodestringoptionalPSČ príjemcu.
payload.receiverAddressstringoptionalJednoriadková adresa príjemcu. Použite ju, ak neviete poslať split polia receiverStreet, receiverCity, receiverPostalCode.
payload.receiverCountrystringoptionalISO 3166-1 alpha-2 krajina príjemcu. (default: SK)
payload.supplierNamestringoptionalSelf-billing alias pre receiverName (dodávateľ).
payload.supplierIcostringoptionalSelf-billing alias pre IČO dodávateľa.
payload.supplierDicstringoptionalSelf-billing alias pre DIČ dodávateľa.
payload.supplierIcDphstringoptionalSelf-billing alias pre IČ DPH dodávateľa. Používa sa aj pri výpočte DPH, lebo dodávateľ je pri self-billing protistrana.
payload.supplierStreetstringoptionalSelf-billing alias pre ulicu dodávateľa.
payload.supplierCitystringoptionalSelf-billing alias pre mesto dodávateľa.
payload.supplierPostalCodestringoptionalSelf-billing alias pre PSČ dodávateľa.
payload.supplierAddressstringoptionalSelf-billing alias pre jednoriadkovú adresu dodávateľa.
payload.supplierCountrystringoptionalSelf-billing alias pre krajinu dodávateľa. (default: SK)
payload.attachmentsarrayoptionalPrílohy faktúry (Peppol BG-24) vložené ako base64 do UBL XML. Max 20 súborov, 10 MB na súbor a 15 MB spolu po base64 dekódovaní.
payload.attachments[].fileNamestringREQNázov súboru prílohy. Nesmie byť prázdny.
payload.attachments[].mimeTypestringREQPovolené MIME typy: application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.oasis.opendocument.spreadsheet. Obsah sa overuje magic-byte kontrolou.
payload.attachments[].contentstringREQBase64-encoded obsah súboru bez data: prefixu.
payload.attachments[].descriptionstringoptionalVoliteľný krátky popis prílohy.
payload.xmlstringoptionalUBL XML mode — hotový UBL XML string ako alternatíva k JSON poliam vyššie. Posiela sa v JSON tele spolu s receiverPeppolId. Max 5 MB pre XML string. Použite ho pre typy dokladov alebo špecifiká, ktoré JSON mode nepokrýva.

Príklady volania

cURL
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","receiverName":"Odberatel s.r.o.","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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
autopilotIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
autopilotIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
statusstringoptionalexceptions alebo all. (default: exceptions)
sincestringoptionalISO 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringoptionalVoliteľný filter na jednu spravovanú firmu.
cursorstringoptionalNepriehľadný cursor z predchádzajúcej odpovede.
limitintegeroptionalPoč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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
actionIdstringREQID 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. Plánovaný worker ich odosiela kontrolovaným tempom. Akceptuje tri tvary: (1) jednu faktúru priamo v koreni spolu s externalId/idempotencyKey/scheduledFor, (2) jednu položku s dokladom v payload, alebo (3) batch najviac 50 položiek v items[], kde každá má vlastný payload. Pole items sa považuje za batch iba vtedy, keď každý prvok obsahuje payload; inak ide o riadky jednej faktúry. Každá položka prejde preflightom a dostane outboxId aj repair checklist.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

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

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/connector/outbox \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"externalId":"ERP-FA-2026-001","scheduledFor":"2026-08-04T08:00:00Z","receiverPeppolId":"0245:2123456789","receiverName":"Odberatel s.r.o.","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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
statusstringoptionalready, blocked, scheduled, sending, sent, failed alebo cancelled.
limitintegeroptionalMaximálny počet vrátených položiek. Max 100. (default: 20)
offsetintegeroptionalPosun 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
outboxIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
outboxIduuidREQID položky Connector outboxu vrátené pri uložení do fronty.
forcebooleanoptionalNastavte 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
idsarrayoptionalVoliteľný zoznam najviac 50 outbox ID.
limitintegeroptionalMaximá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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
outboxIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
cursorstringoptionalNepriehľadný cursor z predchádzajúcej odpovede.
limitintegeroptionalMaximá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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
documentIduuidREQID 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ázovTypPovinnéPopis
AuthorizationstringREQBearer JWT získaný z rovnakých Enterprise API prihlasovacích údajov cez POST /api/v1/auth/token.
X-Firm-IduuidoptionalPovinné pri použití integrátorského sk_int_* JWT, keď voláte API v mene spravovanej firmy.

Parametre

NázovTypPovinnéPopis
cursorstringoptionalNepriehľadný cursor z predchádzajúcej odpovede `nextCursor`.
limitintegeroptionalMaximá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.
SendStatusEvents

Inbound and archive

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

  • Full-scope inbound/outbound API je pre non-billing Peppol typy.
  • PDF, UBL, AS4 envelope a MDN sú auditné artefakty.
Inbound listInboxUBL
Lifecycle & proof. Po odoslaní sledujte jeden dokument cez /documents/{id}/status, /documents/{id}/events, /documents/{id}/responses a /documents/{id}/support-packet. Tieto endpointy tvoria jeden supportovateľný flow: aktuálny stav, časová os, odpovede protistrany a dôkazný balík.
Tri integračné cesty — vyberte podľa potrieb. ePošťák ponúka tri rovnocenné spôsoby, ako konzumovať udalosti a dokumenty. Nemusíte si vybrať jeden — väčšina integrátorov používa kombináciu.
1. Webhooky (POST /api/v1/webhooks + push doručenia) — najnižšia latencia, server-to-server push. Vyžaduje, aby ste mali verejný HTTPS endpoint s HMAC verifikáciou. Vhodné, ak máte ops/IT schopnosť hostovať webhook receiver. HMAC-SHA256 podpis, SSRF guard, encrypted secret-at-rest, auto-disable po 20 terminálnych zlyhaniach, status-code-aware retry (~44h okno pre retryable kódy). Zachované ako mature feature pre súčasných klientov.
2. Events pull facade (GET /api/v1/events/pull + /events/{eventId}/ack) — 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 sieť Peppol. JSON režim podporuje štyri core Peppol billing typy: invoice, credit_note, self_billing a self_billing_credit_note; ePošťák z payloadu vytvorí UBL 2.1 / Peppol BIS 3.0 XML. Hotový UBL XML dokument môžete poslať v JSON poli xml ako expert fallback. Odosielateľ sa vždy berie z autentifikovanej firmy, nie z tela požiadavky. Pred odoslaním overíme v SMP, či je príjemca dostupný v Peppol sieti. Ak nie je, vrátime 422 a nič sa nefakturuje. Hlavička Idempotency-Key (alebo X-Idempotency-Key) je voliteľná: prvé volanie sa uloží, opakovanie s rovnakým telom vráti uložený výsledok (200/201), súbežné spracovanie vráti 409. Ak sa SHA-256 hash tela líši od uloženého, odpoveď je 422 IDEMPOTENCY_KEY_MISMATCH.

Parametre

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

Príklady volania

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

Príklady odpovedí

201 Sent
{ "documentId": "clx9abc123", "submissionId": "clx9abc123", "messageId": "msg_peppol_xyz", "status": "SENT", "links": { "document": "/api/v1/documents/clx9abc123", "status": "/api/v1/documents/clx9abc123/status", "events": "/api/v1/documents/clx9abc123/events", "ubl": "/api/v1/documents/clx9abc123/ubl", "evidence": "/api/v1/documents/clx9abc123/evidence", "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ázovTypPovinnéPopis
itemsarrayREQPole max 50 položiek — rovnaká schéma ako POST /documents/send
items[].idempotencyKeystringoptionalVoliteľný kľúč pre idempotentné opakovanie položky

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

ePošťák Box: zaradiť dokument

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

ePošťák Box: zoznam

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

Parametre

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

Príklady volania

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

Odpovede

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

ePošťák Box: detail položky

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

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

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

ePošťák Box: naplánovať

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

Parametre

NázovTypPovinnéPopis
scheduledForstringREQISO 8601 čas odoslania

Príklady volania

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

Odpovede

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

ePošťák Box: odoslať teraz

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

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

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

ePošťák Box: retry

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

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

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

ePošťák Box: zrušiť

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

Parametre

NázovTypPovinnéPopis
itemIdstringREQBox item UUID

Odpovede

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

Pull: zoznam prijatych dokumentov

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

Parametre

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

Príklady volania

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

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

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 400INVALID_CURSOR (kurzor je poškodený alebo nepodporovaná verzia), alebo BAD_REQUEST pre neplatný `limit`/`kind`.
  • 401Unauthorized
  • 403FORBIDDEN — 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ázovTypPovinnéPopis
client_referencestringoptionalVoliteľný klientsky identifikátor (napr. interné číslo faktúry), max 256 znakov. V tele požiadavky ako JSON `{"client_reference": "..."}`. Prázdne telo je tiež platné.

Príklady volania

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

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

Príklady odpovedí

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

Odpovede

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

Pull: zoznam odoslaných dokumentov

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

Parametre

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

Príklady volania

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

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

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 400INVALID_CURSOR alebo BAD_REQUEST (neplatný `limit`, `kind`, `status` alebo `business_status` skombinovaný s non-billing kind).
  • 401Unauthorized
  • 403FORBIDDEN — 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ázovTypPovinnéPopis
sincestringoptionalOpaque kurzor z `next_cursor` predchádzajúcej odpovede.
limitintegeroptional1-500. Hodnoty nad 500 sa orezú na 500. (default: 100)
document_idstringoptionalFilter len na udalosti jedného dokumentu (UUID).

Príklady volania

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

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

Príklady odpovedí

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

Odpovede

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

Zoznam prijatých fakturačných dokumentov

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Detail dokumentu

Vrati detail prijateho dokumentu vratane UBL XML payloadu.

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Potvrdiť spracovanie klientom

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ázovTypPovinnéPopis
idsstring[]REQ1 až 100 ID dokumentov. Duplicitné ID sa zlúčia, poradie odpovede zachová poradie vstupu.

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

AS4 potvrdenie a MLR

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Support packet dokumentu

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 30 dní po jeho ukončení na export; nejde o samostatnú účtovnú archiváciu mimo kontraktu. Payload je identický s tým, čo prešlo cez Peppol sieť — podpísaný, časovo razítkovaný, tamper-evident. Odpoveď má hlavičky X-Envelope-Archived-At (ISO 8601) a X-Envelope-Direction (inbound/outbound). 404 sa vracia, ak dokument neexistuje, nepatrí vám, alebo jeho envelope ešte nebol archivovaný (nové dokumenty sa archivujú za niekoľko minút).

Príklady volania

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

Odpovede

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

Udalosti životného cyklu dokumentu

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Invoice response história

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Stiahnuť PDF

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

Príklady volania

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

Odpovede

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

Stiahnuť UBL XML

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

Príklady volania

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

Odpovede

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

Odoslať odpoved na fakturu

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Označiť stav dokumentu

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required
  • 404Not Found
  • 422Invalid state
POST/api/v1/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ázovTypPovinnéPopis
fileFileREQPDF, JPEG, PNG, WebP (max 20 MB)
fieldsJSON stringoptionalOptional OCR overrides. Examples: vendor_ico, vendor_dic, vendor_ic_dph, iban, payment_means_code, invoice_number, due_date, document_type=self_billing.

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/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ázovTypPovinnéPopis
filesFile[]REQPole 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ázovTypPovinnéPopis
formatstringREQ"json" | "ubl" (povolené: json, ubl)
documentobject|stringREQJSON objekt alebo UBL XML string

Príklady volania

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

Príklady volania

cURL
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ázovTypPovinnéPopis
input_formatstringREQ"json" | "ubl" (povolené: json, ubl)
output_formatstringREQ"ubl" | "json" (povolené: ubl, json)
documentobject|stringREQDokument na konverziu

Príklady volania

cURL 1
curl -X POST https://epostak.sk/api/v1/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ázovTypPovinnéPopis
xmlstringREQUBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Príklady volania

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Cross-firm inbox

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 401Unauthorized
  • 403Forbidden

Webhooky a udalosti

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 pullCreate webhookBatch ack

Operate failures

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

  • Retry-After sa rešpektuje pri retryable odpovediach.
  • Terminálne chyby zastavia delivery bez ďalšieho retry.
DeliveriesDead letters
Push vs pull — Každá subscription je buď push (POST na vašu URL) alebo pull (event v queue, ktorú periodicky čítate cez 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ázovTypPovinnéPopis
urlstring | nulloptionalHTTPS URL pre push, alebo null/omit pre pull-only
eventsstring[]optionalPredvolene vsetky udalosti

Príklady volania

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

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

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

Príklady odpovedí

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

Odpovede

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

Detail + doručenia

Vrati detail webhooku a poslednych 20 pokusov o dorucenie.

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Upraviť webhook

Aktualizuje URL, udalosti alebo aktívny stav. Všetky polia sú nepovinné.

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Zmazať webhook

Trvalo zmaze webhook a vsetky zaznamy o doruceni.

Príklady volania

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

Odpovede

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

Poslať testovaciu udalosť

Pošle testovaciu udalosť na URL webhooku s platným HMAC podpisom. Predvolený mode=direct odošle 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ázovTypPovinnéPopis
eventstringoptionalQuery param (preferred) or body field. Valid values: document.sent | document.received | document.delivered | document.delivery_failed | document.rejected | document.response_received. Default: document.sent. (default: document.sent) (povolené: document.sent, document.received, document.delivered, document.delivery_failed, document.rejected, document.response_received)
countintegeroptionalQuery param or body field. Number of synthetic webhook POSTs to send in one test run. Valid range: 1..1000. Default: 1. (default: 1)
modestringoptionaldirect 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ázovTypPovinnéPopis
limitnumberoptional1–100 (default: 20)
offsetnumberoptionalZačiatok od (predvolene 0) (default: 0)
cursorstringoptionalOpaque cursor from nextCursor in the previous response. Use instead of offset for stable pagination over large history.
statusstringoptionalPENDING | SUCCESS | FAILED | RETRYING (povolené: PENDING, SUCCESS, FAILED, RETRYING)
eventstringoptionalFilter podľa typu udalosti
testRunIdstringoptionalFilter deliveries created by POST /webhooks/{id}/test?mode=queued.
includeResponseBodybooleanoptionalWhen true, includes the responseBody field 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ázovTypPovinnéPopis
limitnumberoptional1–100 (default: 20)
offsetnumberoptionalZačiatok od (predvolene 0) (default: 0)
eventstringoptionalFilter podľa typu udalosti
subscriptionIdstringoptionalFilter na konkrétnu webhook subscription
includeResponseBodybooleanoptionalAk true, vráti aj poslednú odpoveď ERP endpointu. (default: false)

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Replay zlyhaného webhooku

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Označiť webhook zlyhanie ako vyriešené

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

Parametre

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

Príklady volania

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

Príklady odpovedí

200 OK
{"resolved":true}

Odpovede

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

Rotovať podpisový secret

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Stiahnuť udalosti

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ázovTypPovinnéPopis
limitintegeroptionalMax 100 (default: 20)
event_typestringoptionalFilter podľa typu udalosti

Príklady volania

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

Príklady odpovedí

200 OK
{
  "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ázovTypPovinnéPopis
event_idsstring[]REQPole ID udalosti max 1000

Príklady volania

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

Príklady odpovedí

200 OK
{ "acknowledged": 2 }

Odpovede

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

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ázovTypPovinnéPopis
limitintegeroptionalMax 100 (default: 20)
event_typestringoptionalFilter 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ázovTypPovinnéPopis
event_idsstring[]REQPole 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ázovTypPovinnéPopis
limitnumberoptionalMax výsledkov (default 100, max 500) (default: 100)
sincestringoptionalISO 8601 — filter udalostí vytvorených po tomto čase

Príklady odpovedí

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

Odpovede

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

Hromadné potvrdenie udalostí

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

Parametre

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

Príklady odpovedí

200 OK
{
  "acknowledged": 5
}

Odpovede

  • 200OK
  • 400Bad Request
  • 401Unauthorized

Peppol

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

Authoritative checks

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

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

Discovery vs routing

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

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

SMP capability lookup

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Resolve firmy na Peppol účastníka

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Hľadať v adresári

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Info o firme + Peppol status

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Zistiť podporované dokumenty

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Hromadné overenie max 100

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Peppol BIS 3.0 validácia (verejné)

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Firmy

Správa firiem priradených k vášmu integrátorskému účtu. 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 firmsStav súhlasuAssignKeys

Access boundaries

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

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

Zoznam prístupných firiem

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 401Unauthorized
GET/api/v1/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ázovTypPovinnéPopis
pageintegeroptionalStranka (default: 1)
page_sizeintegeroptionalMax 100 (default: 20)
directionstringoptionalinbound | outbound (povolené: inbound, outbound)
statusstringoptionalFilter podľa stavu
fromstringoptionalISO 8601 date
tostringoptionalISO 8601 date

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Registrovat Peppol ID

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Stav súhlasu firmy

Read-only kontrola stavu integrátorského súhlasu firmy podľa DIČ alebo IČO. Aktívny stav v produkcii znamená prijatú a neodvolanú žiadosť vlastníkom alebo administrátorom firmy s nemenným dôkazom oprávnenia. Pri required/revoked vytvorte novú žiadosť v partnerskej zóne v časti Firmy; pri pending čakajte na jej prijatie. V dev sandboxe odpoveď rozlišuje samotné vytvorenie testovacej firmy od dokončeného OAuth testu vlastníka a uvádza testovacie cesty. Vyžaduje sk_int_* JWT s oprávnením firms:manage, bez X-Firm-Id.

Parametre

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

Príklady volania

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

Príklady odpovedí

200 OK — consent_status: active | pending | revoked | required
{
  "identifier": { "dic": "2122701339" },
  "firm": {
    "id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "name": "Kaja Solutions s.r.o.",
    "ico": "52345678",
    "dic": "2122701339",
    "peppol_id": "0245:2122701339",
    "peppol_status": "active"
  },
  "consent_status": "pending",
  "assign_status": "consent_required",
  "next_action": "await_consent_acceptance",
  "environment": "production",
  "consent_flow": "owner_consent"
}
200 OK — firma existuje, ale súhlas integrátorovi chýba
{
  "identifier": { "ico": "52345678" },
  "firm": {
    "id": "b1022d80-5016-4dad-a8d2-53685cab1701",
    "name": "Kaja Solutions s.r.o.",
    "ico": "52345678",
    "dic": "2122701339",
    "peppol_id": "0245:2122701339",
    "peppol_status": "active"
  },
  "consent_status": "required",
  "assign_status": "consent_required",
  "next_action": "request_integrator_consent"
}
404 Not Found — firma ešte nie je v ePošťák registri
{
  "error": {
    "code": "FIRM_NOT_REGISTERED",
    "message": "Firm is not registered in ePošťák yet.",
    "docs": "/api/docs/enterprise#ep-firms-consent-status"
  }
}

Odpovede

  • 200OK — consent_status: active | pending | revoked | required
  • 200OK — firma existuje, ale súhlas integrátorovi chýba
  • 400Bad Request — pošlite dic alebo ico v správnom formáte
  • 401Unauthorized
  • 403Forbidden — missing firms:manage scope
  • 404Not Found — firma ešte nie je v ePošťák registri
POST/api/v1/firms/assign

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

Aktivuje iba existujúcu, bezpečne priraditeľnú väzbu firmy 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É: Nová alebo odvolaná firma musí najprv prijať čerstvú žiadosť o integrátorský súhlas vytvorenú v partnerskej zóne v časti Firmy. Vlastník alebo admin firmy potvrdí scopes a systém uloží nemenný KYC dôkaz. OAuth súhlas nevytvára ani neobnovuje. Stav overíte cez GET /api/v1/firms/consent-status; plán firmy sám osebe nie je súhlas konkrétnemu integrátorovi.

Parametre

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

Príklady odpovedí

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

Odpovede

  • 201Created
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden — CONSENT_REQUIRED
  • 404Not Found
  • 409Conflict
  • 422Validation Error
POST/api/v1/firms/assign/batch

Hromadné priradenie firiem

Hromadne aktivuje až 50 už oprávnených firiem k integrátorskému účtu podľa DIČ alebo IČO. Preferujte `dics`; `icos` držíme kvôli spätnej kompatibilite. Nová alebo odvolaná firma musí najprv prijať čerstvú žiadosť o integrátorský súhlas z partnerskej zóny, časti Firmy; OAuth tento súhlas nevytvára ani neobnovuje.

Parametre

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

Príklady odpovedí

200 OK
{
  "results": [
    { "identifier":"2122701339", "dic":"2122701339", "firm":{"id":"b1022d80-5016-4dad-a8d2-53685cab1701","name":"Kaja Solutions s.r.o.","ico":"52345678","dic":"2122701339","peppol_id":"0245:2122701339","peppol_status":"active"}, "status":"active" },
    { "ico":"99887766", "error":"NOT_FOUND", "message":"No firm with ICO 99887766" },
    { "ico":"11223344", "error":"CONSENT_REQUIRED", "message":"First-time firm claim requires an accepted owner/admin integrator consent request." }
  ]
}

Odpovede

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

Zoznam integrátorských kľúčov

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Zneplatniť integrátorský kľúč

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

Plán a agregovaná spotreba

Vráti plán integrátora, spotrebu za aktuálne fakturačné obdobie naprieč všetkými spravovanými firmami, 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ď kombinovaná billable prevádzka dosiahne 20 001 dokumentov za mesiac, exceedsAutoTier sa nastaví na true a nasledujúce obdobie vyžaduje individuálnu objednávku; aktuálne obdobie sa dokončí interim overflow sadzbou. Budúce prekročenie po preklopení sandboxu sledujte cez productionEstimate.exceedsAutoTier.

Parametre

NázovTypPovinnéPopis
offsetintegeroptionalPosun pre stránkovanie zoznamu firiem (default: 0)
limitintegeroptionalMax 100 — počet firiem v firms (default: 50)
periodstringoptionalAktuálne fakturačné obdobie vo formáte YYYY-MM (SK časová zóna). [response field]
nextResetAtstringoptionalISO 8601 — kedy sa počítadlá vynulujú (1. deň ďalšieho mesiaca, SK polnoc v UTC). [response field]
billable.outboundChargenumberoptionalTarifný náklad za odoslané dokumenty — sadzby aplikované na outboundCount ako agregát. [response field]
billable.totalChargenumberoptionalSúčet outbound + inbound API. Zaokrúhlené na centy. [response field]
sandbox.totalChargenumberoptionalNeúčtovaný sandbox odhad pri aktuálnej sandbox prevádzke. [response field]
productionEstimate.totalChargenumberoptionalOdhad ceny, ak by sandbox integrator-managed firmy bežali v produkcii. [response field]
exceedsAutoTierbooleanoptionaltrue keď kombinovaný billable produkčný outbound + inbound dosiahne 20 001 dokumentov. Nasledujúce obdobie vyžaduje individuálnu objednávku. [response field]
contactThresholdintegeroptionalNajvyšší štandardný kombinovaný mesačný objem (20 000); od 20 001 sa vyžaduje individuálna objednávka. [response field]
firms[].managedbooleanoptionaltrue = firma je integrator-managed. Kombinujte s firms[].sandbox alebo firms[].billable na odlíšenie účtovaných a testovacích firiem. false = patrí do nonManaged. [response field]
firms[].sandboxbooleanoptionaltrue = firma je sandbox a neúčtuje sa. [response field]
firms[].billablebooleanoptionaltrue = firma je integrator-managed produkcia a počíta sa do aktuálne účtovanej prevádzky. [response field]

Príklady volania

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

Príklady odpovedí

200 OK
{
  "integrator": {"id":"int_abc","name":"Demo Integrátor","plan":"integrator","monthlyDocumentLimit":null},
  "period": "2026-04",
  "nextResetAt": "2026-05-01T00:00:00.000Z",
  "billable": {
    "managedFirms":42,"outboundCount":1850,"inboundApiCount":320,
    "outboundCharge":168.00,"inboundApiCharge":25.60,"totalCharge":193.60,"currency":"EUR"
  },
  "sandbox": {
    "firms":2,"outboundCount":120,"inboundApiCount":30,
    "outboundCharge":12.00,"inboundApiCharge":2.40,"totalCharge":14.40,"currency":"EUR"
  },
  "productionEstimate": {
    "managedFirms":44,"outboundCount":1970,"inboundApiCount":350,
    "outboundCharge":177.60,"inboundApiCharge":28.00,"totalCharge":205.60,"currency":"EUR"
  },
  "nonManaged": {"firms":3,"outboundCount":120,"inboundApiCount":15},
  "exceedsAutoTier": false,
  "contactThreshold": 20000,
  "pricing": {
    "model":"tiered","currency":"EUR",
    "outboundTiers":[
      {"upTo":1000,"rate":0.10},
      {"upTo":2000,"rate":0.08},
      {"upTo":5000,"rate":0.06},
      {"upTo":20000,"rate":0.05},
      {"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":20000,"rate":0.05},
      {"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.
UsageSubmissions
GET/api/v1/reporting/statistics

Štatistiky dokumentov

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

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

História reportov pre OpenPeppol

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

Parametre

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

Príklady volania

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

Príklady odpovedí

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

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required

Referencia

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

Error contract

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

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

Commercial and retention

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

  • Enterprise API archív je viazaný na aktívny kontrakt.
  • Objemové sadzby sa počítajú naprieč spravovanými firmami.
PricingRetention
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.

ObjemCena
Neobmedzenezadarmo

Odoslané

Cena za dokument odoslaný cez Peppol.

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

Prijaté cez API

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

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

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

Rate limity

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

Pravidlá

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

Hlavičky odpovede (HTTP 429)

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

Hlavičky sa vracajú len v HTTP 429 odpovediach. Odporúčame implementovať exponenciálny backoff. Aktuálny limit pre konkrétny endpoint sa zobrazí v X-RateLimit-Limit hlavičke pri 429 odpovedi.

Chybové kódy

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

StatusKódPopis
400BAD_REQUESTNeplatné JSON telo alebo chýbajúce pole
400INVALID_PARAMNeplatná hodnota query parametra
401UNAUTHORIZEDChýbajúci alebo neplatný API kľúč
403FORBIDDENNedostatočný scope alebo prístup k cudzej firme; alebo firma nemá API-eligible plán
404NOT_FOUNDProstriedok neexistuje alebo nepatrí vašej firme
409CONFLICTDuplikát (OAuth klient, priradenie firmy, idempotency in-flight)
409IDEMPOTENCY_IN_FLIGHTretryableRovnaký Idempotency-Key už spracúva rovnaký payload; počkajte a skontrolujte stav neskôr
413PAYLOAD_TOO_LARGETelo požiadavky presahuje povolený limit
422VALIDATION_ERROR / UNPROCESSABLE_ENTITYJSON alebo povinné polia neprešli vstupnou validáciou; opravte payload
422UBL_VALIDATION_ERRORUBL je syntakticky spracované, ale porušuje Peppol/CEN pravidlo; pozrite details[].rule
422IDEMPOTENCY_KEY_MISMATCHRovnaký Idempotency-Key bol znovu použitý s iným kanonizovaným telom
422participant_not_foundKatalóg príjemcov: prijímateľ sa nenašiel v Peppol/SMP; retryable=false; fix_hint=zmeňte alebo overte Peppol ID príjemcu
422receiver_unsupported_document_typeKatalóg príjemcov: prijímateľ existuje, ale nepodporuje zvolený document type/profile; retryable=false; fix_hint=zmeňte typ dokladu alebo capability
422validation_failedValidácia payloadu: UBL/JSON sémantická validácia zlyhala; retryable=false; fix_hint=opravte payload podľa details/rule
502temporary_transport_errorretryableTransport: AP alebo sieťová závislosť dočasne zlyhala; retryable=true; fix_hint=opakujte s rovnakým Idempotency-Key
409delivery_dead_letteredDoručenie: všetky pokusy o doručenie sa vyčerpali; retryable=false; fix_hint=pozrite events/support-packet a opakujte manuálne alebo kontaktujte support
422duplicate_idempotency_keyIdempotencia: rovnaký Idempotency-Key bol použitý s iným telom; retryable=false; fix_hint=pošlite pôvodné telo alebo nový kľúč pre zmenený payload
429RATE_LIMITEDretryablePrekročený rate limit
500INTERNAL_ERRORretryableNeočakávaná chyba servera
502SEND_FAILEDretryableOdoslanie cez Peppol AP zlyhalo
503IDEMPOTENCY_STORE_UNAVAILABLEretryableDočasne nedostupný idempotency store; opakujte s rovnakým Idempotency-Key
503VALIDATION_SERVICE_UNAVAILABLEretryableDočasne nedostupný validačný engine; opakujte s backoffom

Uchovávanie dát

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). Read-only exportné endpointy /documents/{id}, /documents/{id}/ubl, /documents/{id}/pdf, /documents/{id}/evidence, /documents/{id}/evidence-bundle a /documents/{id}/envelope ostávajú dostupné počas aktívneho kontraktu a 30 dní po jeho ukončení na export. Poskytovateľ vyvíja primerané úsilie na cieľ dostupnosti 99,5 % podľa VOP bez service creditov alebo automatických náhrad; Peppol sieť, FR SR, SMP/SML, OpenPeppol, cudzie Access Pointy a prijímacie systémy sú externé vrstvy mimo priamej kontroly ePošťáka.

Uchovávanie dát

API archív a technické zálohy sú viazané na zmluvný vzťah: počas aktívneho kontraktu a 30 dní po ukončení na export, audit alebo migráciu. 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 30-dňovej exportnej lehote sa API prístup k archívnym exportom 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 aktívneho kontraktu a 30 dní po jeho ukončení na export, no formálne nepreberá povinnosť účtovnej archivácie zákazníka.