ePošťák.sk

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

Vybrať správny postup

Connector API

SprievodcoviaConnector: keď ERP posiela údaje faktúry v JSON

Connector: keď ERP posiela údaje faktúry v JSON

Najkratší tok: získajte token, vyberte firmu cez customerRef a odošlite jeden business JSON. Príjem, obchodné odpovede, webhooky a vlastný export riešte až potom, keď ich potrebujete.

Vyberte si integračný tok

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

Pripojenie

Získajte token a vyberte firmu cez customerRef.

  1. Pripojiť ERPSDK alebo krátkodobý Bearer token; bez X-Firm-Id.

Odosielanie

Pošlite alebo uložte business JSON bez UBL projektu.

  1. Odoslať prvý dokladJeden kanonický JSON pre send aj stage.

Príjem

Čítajte events, načítajte doklad a potvrďte lokálny import.

  1. Prijať a importovať dokladCursor polling funguje okamžite; webhook je voliteľný.
  2. Odoslať obchodnú odpoveďrespond je rozhodnutie protistrane, nie potvrdenie importu.

Vlastný export

Mapper a Autopilot sú voliteľná API cesta pre ERP bez kanonického JSON.

  1. Otestovať vlastný export cez MapperMapovanie, náhľad, Autopilot a riadené odoslanie.

Pripojiť ERP

Oficiálne SDK rieši OAuth automaticky. Pri raw HTTP vymeňte client_id a sk_int_* client_secret za 15-minútový access_token. Firmu potom na každom Connector volaní určíte uloženým customerRef.

Postup

  1. 01Načítajte client_id a client_secret iba na serveri ERP.
  2. 02Zavolajte POST /api/v1/auth/token s grant_type=client_credentials.
  3. 03Token cacheujte do expires_in a Connector requesty posielajte bez X-Firm-Id.

Endpoint

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

Token request

curl
1curl -X POST https://dev.epostak.sk/api/v1/auth/token \
2 -H "Content-Type: application/json" \
3 -d '{"grant_type":"client_credentials","client_id":"8924a11d-a93c-4d5a-b54b-1f1ff246152c","client_secret":"sk_int_test_face36350e1005c930acff02a00f73140f2a1eabfb87c282","scope":"documents:send documents:read documents:write webhooks:read webhooks:write"}'

Prihlásenie

NázovTypPovinnéPopis
grant_typestringáno
client_idstringánoThe client_id displayed with the assigned integrator credential; it is separate from the sk_int_* secret.
client_secretstringánoThe full compatible sk_int_* integrator secret. Keep it server-side.
scopestringnieOptional space-separated subset of the credential's effective allowed scopes. Omitting it returns that allowed set. Unknown names and known but ungranted scopes are rejected.
api_interfacestringnieOptional interface selector. Send <code>connector</code> for Connector integrations. Omitting it preserves the legacy enterprise_api default on /api/v1/auth/token.

Ďalšie kroky

  • V Integrátorskom paneli uložte stabilné customerRef pre každú spravovanú firmu.
  • Rovnaký token môže pracovať s viacerými schválenými firmami; každé volanie má vlastné customerRef.

Odoslať prvý doklad

Pošlite firemné údaje príjemcu, hlavičku Idempotency-Key a stabilné externalId. delivery=send je explicitný pokyn držiteľa scope documents:send a nie je podmienený autoSendEnabled; state=queued znamená prijaté asynchrónne odoslanie. Iba delivery=stage doklad uloží na neskoršie uvoľnenie a pri novom príkaze vráti send/cancel odkazy. Uložený doklad čaká 14 dní; potom ho zrušíme (state=cancelled), odkaz send zmizne a odoslanie vráti 422 DOCUMENT_INVALID. Taký doklad pošlite znova s novým externalId.

Postup

  1. 01Vyberte odosielateľa cez customerRef.
  2. 02Príjemcu identifikujte cez country a správne companyId, taxId alebo vatId.
  3. 03Pri retry zachovajte rovnaké externalId, Idempotency-Key aj telo requestu.

Endpoint

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

Prvý DEV doklad A → B

Použite JWT získaný vlastným DEV kľúčom, customerRef firmy A a DIČ pridelenej firmy B. Spustite s curl a jq. Obe firmy musia mať dokončenú testovaciu Peppol registráciu. Pri opakovaní zachovajte rovnaké telo aj ID; pre ďalší doklad zvoľte nové ID. Odpoveď potvrdzuje prijatie, nie doručenie — ďalej sledujte vrátený odkaz na stav.

curl
1# Set TOKEN, CUSTOMER_REF_A and TAX_ID_B from your DEV configuration.
2export DOCUMENT_ID="sandbox-a-b-001"
3jq -n --arg customerRef "$CUSTOMER_REF_A" --arg taxId "$TAX_ID_B" --arg id "$DOCUMENT_ID" --arg date "$(date +%F)" '{
4 customerRef: $customerRef, externalId: $id, number: $id,
5 delivery: "send", type: "invoice", issueDate: $date, dueDate: $date,
6 currency: "EUR", buyerReference: "DEV-TEST",
7 recipient: {country: "SK", taxId: $taxId},
8 lines: [{description: "Testovacia sluzba", quantity: 1, unit: "C62", unitPrice: 1, vatRate: 23, taxTreatment: "standard"}]
9}' > invoice.json
10curl --fail-with-body "https://dev.epostak.sk/api/v1/connector/documents" \
11 -H "Authorization: Bearer $TOKEN" \
12 -H "Content-Type: application/json" \
13 -H "Idempotency-Key: $DOCUMENT_ID" \
14 --data-binary @invoice.json

Payload faktúry

Rozšírený príklad ukazuje aj platobné údaje, adresu, zľavu, preddavok a prílohu. Úplná tabuľka polí je v API referencii nižšie.

json
1{
2 "customerRef": "erp-acme",
3 "externalId": "invoice-2026-0042",
4 "delivery": "send",
5 "type": "invoice",
6 "number": "2026-0042",
7 "recipient": {
8 "country": "SK",
9 "name": "ODBERATEĽ, s.r.o.",
10 "taxId": "2120123456",
11 "address": { "street": "Hlavná 1", "city": "Bratislava", "postalCode": "811 01" }
12 },
13 "issueDate": "2026-07-15",
14 "dueDate": "2026-07-29",
15 "currency": "EUR",
16 "iban": "SK3112000000198742637541",
17 "paymentMethod": "bank_transfer",
18 "paymentTerms": "Splatnosť 14 dní",
19 "variableSymbol": "20260042",
20 "buyerReference": "ODD-IT",
21 "orderReference": "OBJ-1042",
22 "lines": [{
23 "description": "Mesačná licencia",
24 "quantity": 1,
25 "unit": "C62",
26 "unitPrice": 100,
27 "vatRate": 23,
28 "taxTreatment": "standard",
29 "discount": 5
30 }],
31 "prepayments": [{ "amountWithVat": 20, "vatRate": 23, "settlementDate": "2026-07-10" }],
32 "attachments": [{ "fileName": "objednavka.pdf", "mimeType": "application/pdf", "content": "JVBERi0xLjQ..." }]
33}

Minimálny request

NázovTypPovinnéPopis
Idempotency-KeyheaderánoStabilný kľúč rovnakého business príkazu.
customerRefstringánoERP referencia odosielajúcej firmy.
externalIdstringánoStabilné ID dokladu v ERP.
numberstringánoČíslo faktúry alebo dobropisu.
recipientobjectánocountry a aspoň jedno správne business ID.
lines[]arrayánoAspoň jedna položka.
buyerReference | orderReferencestringánoInterná referencia kupujúceho alebo číslo jeho objednávky, najviac 100 znakov.

Práca so stavmi

send
Doklad sa prijme do asynchrónneho odoslania.
stage
Doklad sa uloží a odpoveď vráti send a cancel odkazy.

Ďalšie kroky

  • Úplnú schému každého koreňového a vnoreného poľa nájdete v sekcii Odoslať business doklad.
  • Na test medzi firmami použite happy path v Integrátorskom paneli.

Prijať a importovať doklad

Čítajte udalosti pre konkrétne customerRef. Pri document.received načítajte detail, uložte doklad v jednej lokálnej transakcii a až potom zavolajte acknowledge.

Postup

  1. 01Volajte GET /connector/events?customerRef=... s posledným cursorom.
  2. 02Deduplikujte podľa event id a načítajte detail dokumentu.
  3. 03nextCursor uložte až po úspešnom lokálnom commite.
  4. 04Acknowledge opakujte bezpečne, kým dostanete úspech.

Endpoint

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

Polling

curl
1curl "https://dev.epostak.sk/api/v1/connector/events?customerRef=erp-acme&limit=50" \
2 -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN"

Potvrdenie importu

curl
1curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/DOCUMENT_ID/acknowledge?customerRef=erp-acme" \
2 -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN"

Práca so stavmi

document.received
Doklad je pripravený na import do ERP.
acknowledge
Iba lokálne potvrdenie importu; protistrane nič neposiela.

Ďalšie kroky

  • Voliteľný webhook nastavte raz pre integrátora; každá udalosť obsahuje customerRef.

Odoslať obchodnú odpoveď

Respond použite až vtedy, keď ERP pozná obchodné rozhodnutie k prijatému dokladu. Acknowledge a respond sú dve nezávislé akcie.

Postup

  1. 01Import potvrďte cez acknowledge.
  2. 02Po rozhodnutí pošlite jeden podporovaný business status cez respond.

Endpoint

POST/api/v1/connector/documents/{documentId}/respond
Vyskúšať

Akceptovať doklad

curl
1curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/DOCUMENT_ID/respond?customerRef=erp-acme" \
2 -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN" \
3 -H "Content-Type: application/json" \
4 -d '{"status":"accepted"}'

Práca so stavmi

received
Podporovaný obchodný stav.
in_process
Podporovaný obchodný stav.
under_query
Podporovaný obchodný stav.
conditionally_accepted
Podporovaný obchodný stav.
rejected
Podporovaný obchodný stav.
accepted
Podporovaný obchodný stav.
paid
Podporovaný obchodný stav.

Ďalšie kroky

  • Neodosielajte accepted automaticky iba preto, že import do ERP prešiel.

Otestovať vlastný export cez Mapper

Ak ERP ešte nevie vytvoriť kanonický Connector JSON, pošlite vlastný JSON alebo CSV export na POST /api/v1/connector/mapper. Mapper vytvorí mapovanie a náhľad; Autopilot pomôže odhaliť a opraviť bezpečné odchýlky. Výsledok môžete najprv uložiť cez stage.

Postup

  1. 01Otvorte referenciu Mappera v Enterprise dokumentácii.
  2. 02Pošlite reprezentatívny ERP export a označte zdrojové polia.
  3. 03Skontrolujte kanonický JSON a výsledok validácie.
  4. 04Najprv použite stage; send povoľte až po overení mapovania.

Endpoint

POST/api/v1/connector/mapper
Vyskúšať

Vstupný bod

curl
1# API reference: POST /api/v1/connector/mapper

Ďalšie kroky

  • Mapper a Autopilot sú pomocné nástroje; výsledný runtime kontrakt ostáva POST /connector/documents.

Začnite v sandboxe

Po schválení žiadosti máte integrátorský účet a dve testovacie firmy A a B vrátane ich testovacej Peppol registrácie, už prepojené s vaším účtom. Vy si pre každú firmu nastavíte vlastné customerRef. Produkcia je oddelená.

1. Požiadajte o prístup

Vyplňte žiadosť na https://dev.epostak.sk/dev. Prístup pripravíme v pracovný deň do 4 hodín, príde e-mailom. Prihlásite sa na https://dev.epostak.sk/integrator, dve testovacie firmy A/B nájdete hotové a vlastný API kľúč si vytvoríte v DEV portáli.

  • Základná URL sandboxu: https://dev.epostak.sk/api/v1
  • Vlastný kľúč si vytvoríte v DEV portáli; dve testovacie firmy sú pripravené a prepojené s vaším účtom; Connector nemá verejné API na vytvorenie alebo vyhľadanie zákazníka.

2. Nastavte si customerRef

V integrátorskom dashboarde otvorte Firmy a pre každú už schválenú firmu zvoľte vlastnú stabilnú ERP referenciu. Nepoužívajte IČO ani interné firmId ako automatický fallback. Po prvom stage/send použití zostáva referencia uzamknutá.

3. Použite SDK alebo získajte token

Odporúčame oficiálne SDK, ktoré token cacheuje a customerRef posiela automaticky. Pri raw HTTP vytvorte z pridelených credentials 15-minútový JWT cez client_credentials, uchovajte ho do expirácie a potom vytvorte nový.

Testovací príjemca v sandboxe

Sandbox overuje príjemcu v testovacej sieti Peppol. Reálne IČO preto funguje iba vtedy, keď má firma registráciu aj v testovacej sieti; produkčná registrácia sama nestačí. Najistejší prvý test odošlite testovaciemu príjemcovi „ePošťák Test – Prijaté“ (0245:4188071545), ktorý doklad prijme.

4. Pošlite business JSON

Použite vlastné customerRef zo schválenej firmy a bežné firemné alebo daňové ID príjemcu. Connector sám overí príjemcu v správnej sieti a vyrieši elektronický formát aj doručenie.

  • Authorization: Bearer <krátkodobý JWT>
  • Bez X-Firm-Id a bez sieťových identifikátorov.

5. Čítajte udalosti, potvrďte import a odpovedzte

Pravidelne volajte GET /connector/events. nextCursor uložte až po lokálnom commite. Pri document.received importujte doklad a idempotentne zavolajte acknowledge. Ak chcete odosielateľovi oznámiť business stav faktúry, zavolajte respond; nejde o ten istý krok.

6. Voliteľne zapnite okamžitý push

Connector obsahuje vlastný webhook, takže kvôli push notifikáciám nemusíte prechádzať na Enterprise API. Nastavíte ho raz pre celý integrátorský účet; dokumentové udalosti majú rovnaký business tvar ako polling a voliteľné lifecycle udalosti oznamujú zmeny vzťahu s firmou alebo jej digitálnym poštárom. Všetky nesú customerRef, ale nikdy nie migračný kód ani identitu používateľa. GET /connector/events ponechajte ako spoľahlivý checkpoint dokumentov.

  • X-Webhook-Signature má tvar sha256=<hex>. HMAC-SHA256 počítajte nad X-Webhook-Timestamp + '.' + pôvodné raw body; timestamp je v sekundách.
  • Secret sa zobrazí iba pri vytvorení alebo rotácii; uložte ho do secret managera a použite nezmenený ako UTF-8 text, nie dekódovaný hex. Testy aj reálne doručenia používajú aktuálny secret webhooku.
  • Deduplikujte podľa X-Webhook-Event-Id a pri dočasnej chybe vráťte 503; 500 je terminálny výsledok bez retry.
Základná URL sandboxu: https://dev.epostak.sk/api/v1. Produkčný host a prístupové údaje dostanete až pri osobitne schválenom prechode do produkcie.
Strojový kontrakt: Connector OpenAPI JSON obsahuje iba auth a Connector operácie, oba servery (sandbox aj produkciu) a scope pre každú operáciu.
POST/api/v1/auth/tokenCore

Získať krátkodobý token

Exchange the assigned client_id and a compatible sk_int_* client_secret for a short-lived Bearer JWT. Existing supported integrator credentials do not need to be replaced just to adopt Connector. client_id is the displayed key ID or prefix; it is not the secret. Set api_interface to connector and request only the Connector scopes needed by your integration. Použite pridelené client_id a kompatibilný sk_int_* client_secret s grant_type=client_credentials. Existujúci podporovaný integrátorský credential nemusíte meniť iba kvôli Connectoru. access_token uchovajte do expires_in (900 sekúnd) a potom vytvorte nový rovnakým volaním. V Connector volaniach pošlite Authorization: Bearer a customerRef, ktoré ste si nastavili pre schválenú firmu; X-Firm-Id neposielajte.

Parametre

NázovTypPovinnéPopis
grant_typestringREQ (povolené: client_credentials)
client_idstringREQThe client_id displayed with the assigned integrator credential; it is separate from the sk_int_* secret.
client_secretstringREQThe full compatible sk_int_* integrator secret. Keep it server-side.
scopestringoptionalOptional space-separated subset of the credential's effective allowed scopes. Omitting it returns that allowed set. Unknown names and known but ungranted scopes are rejected.
api_interfacestringoptionalOptional interface selector. Send connector for Connector integrations. Omitting it preserves the legacy enterprise_api default on /api/v1/auth/token. (povolené: connector)

Príklady volania

cURL
curl -X POST https://dev.epostak.sk/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"8924a11d-a93c-4d5a-b54b-1f1ff246152c","client_secret":"sk_int_test_face36350e1005c930acff02a00f73140f2a1eabfb87c282","scope":"documents:send documents:read documents:write webhooks:read webhooks:write"}'

Príklady odpovedí

200 Access token + refresh token issued
{"access_token":"eyJhbGc...","token_type":"Bearer","expires_in":900,"scope":"documents:send documents:read documents:write firms:manage webhooks:read webhooks:write"}

Odpovede

  • 200Access token + refresh token issued
  • 400Invalid grant_type or malformed body
  • 401Invalid client credentials
  • 403Requested scope(s) not allowed by key
  • 423Invalid credential attempts throttled after 5 failures; valid credentials remain usable
  • 429Rate limit exceeded

Connector

Jedno business API pre ERP: pošlite doklad, čítajte doklady a udalosti, voliteľne zapnite webhook a potvrďte spracovanie. Sieťové a transportné detaily rieši ePošťák.

Managed ERP flow

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

  • POST /connector/documents je jediný odporúčaný vstup pre nové integrácie.
  • Príjemcu stačí určiť bežným firemným alebo daňovým ID.
  • Pri delivery=stage použite iba send alebo cancel link v odpovedi; request akcie nemá telo.

Oprava už odoslanej faktúry

Každý opravný doklad má vlastné jedinečné number, externalId a Idempotency-Key. precedingDocumentNumber označuje pôvodnú faktúru. Zníženie sumy alebo úplné storno pošlite ako credit_note, navýšenie ako debit_note. Opravu textu alebo údajov bez zmeny sumy pošlite ako credit_note na celú pôvodnú faktúru a potom novú, správnu faktúru. Typ correction (384) Peppol povoľuje len medzi dvoma nemeckými stranami (pravidlo P0112), medzi slovenskými firmami ho odmietneme. Pôvodný doklad sa neprepisuje. Endpoint cancel ruší iba ešte neodoslaný staged dokument.

Ťarchopis a faktúra k zálohovej platbe

type=debit_note vytvorí ťarchopis s kódom 383 a vyžaduje precedingDocumentNumber pôvodnej faktúry. type=prepayment_invoice vytvorí samostatnú faktúru s kódom 386. prepayments a prepaidAmount na konečnej faktúre slúžia na zúčtovanie zaplatených súm; nenahrádzajú samostatný doklad. Proforma výzva na platbu nie je automaticky faktúrou typu 386. V odpovediach v1 a udalostiach zostáva type=invoice; voliteľné businessType obsahuje debit_note, prepayment_invoice alebo advance_payment. Pri čítaní použite businessType, ak je prítomné, inak type.

Daňový doklad k prijatej platbe a odpočet zálohy

type=advance_payment vytvorí daňový doklad k prijatej platbe s kódom 388. Pošlite ho až po prijatí platby a do taxPointDate zadajte dátum prijatia platby; je povinný a nesmie byť po issueDate ani v budúcnosti. Celá suma je už zaplatená, suma na úhradu je 0 a prepayments ani riadky advance_deduction nie sú povolené. Rovnako typ 386 posielajte až po prijatí platby. Zálohová faktúra (proforma), ktorou platbu len žiadate, nie je faktúra a cez Peppol sa neposiela. Na konečnej faktúre uveďte zálohu v prepayments: s taxDocumentRef (zdanená záloha) ju ePošťák odpočíta záporným riadkom so sadzbou DPH daňového dokladu a odkazom BT-25, takže sa zníži základ aj DPH; bez taxDocumentRef (nezdanená) len zníži sumu na úhradu cez prepaidAmount. Na doklade 388 uveďte prijatú platbu v prepaidAmount: DPH sa vypočíta z platby (platba × sadzba / (100 + sadzba), § 19 ods. 4), takže doklad uvedie presne zaplatenú sumu. Na konečnej faktúre ePošťák odpočíta presnú DPH daňového dokladu (vatAmount, inak amountWithVat − amountWithoutVat), nie základ × sadzba; odchýlku 1 centu pravidlo BR-CO-17 pripúšťa.

Príjemca: použite správny typ ID

country určuje krajinu registrácie. companyId je registračné číslo firmy, taxId lokálne daňové ID a vatId VAT ID. Connector oreže okrajové medzery a normalizuje porovnanie, ale nikdy nehádže jeden typ ID do iného poľa.

  • Pre zahraničnú firmu začnite country + jedným správne klasifikovaným ID.
  • Ak pošlete viac ID, všetky musia viesť k tej istej firme; inak dostanete 409 RECIPIENT_AMBIGUOUS.
  • Nenájdený alebo nesprávne klasifikovaný identifikátor vráti 422 RECIPIENT_NOT_FOUND; Connector nevyskúša iný typ potichu. Príjemca s rovnakým Peppol ID ako odosielateľ vráti 422 SELF_ADDRESSED_SEND, aj v testovacej sieti.
  • Ak firma existuje, ale nemá endpoint v aktívnej sieti, rovnaký kód 422 vráti v nextAction pokyn na overenie registrácie. V sandboxe odporučí inú spravovanú testovaciu firmu z Integrátorského panelu.

Scope podľa operácie

Vyžiadajte iba scope potrebné pre konkrétny Connector tok.

  • documents:send — vytvoriť/odoslať/zrušiť doklad.
  • documents:read — zoznam, detail, events a pokročilé artefakty.
  • documents:write — acknowledge prijatého dokladu alebo odoslať jeho business odpoveď.
  • webhooks:read — načítať konfiguráciu a históriu doručení.
  • webhooks:write — nastaviť, odstrániť, rotovať a otestovať webhook.
  • Mapper navyše vyžaduje documents:send + firms:manage.

Events checkpoint, webhook a obnova

nextCursor uložte až po lokálnom commite spracovaných udalostí a pošlite ho v ďalšom volaní aj keď hasMore=false. Voliteľný webhook pushuje rovnaké dokumentové event položky s menšou latenciou a môže navyše posielať explicitne vybrané lifecycle udalosti; cursor dokumentov nenahrádza. Cursor je nepriehľadný.

  • Ak checkpoint stratíte alebo server odmietne jeho verziu, začnite bez cursor a deduplikujte podľa event id.
  • Acknowledge dokladu je idempotentné, takže recovery replay je bezpečný.
  • Acknowledge označí lokálny ERP import; respond odošle business odpoveď protistrane cez Peppol.
  • Webhook je globálny pre integrátora; root customerRef určuje firmu každej udalosti.
Jeden model: customerRef vyberá schválenú firmu, externalId spája doklad s ERP a links ukazujú povolené ďalšie akcie. Normálny Connector tok nepoužíva X-Firm-Id ani sieťové a transportné detaily.
Kompatibilita: Connector je odporúčaný spravovaný vstup pre nové ERP integrácie. Existujúce Enterprise API a SAPI integrácie, endpointy aj podporované credentials ostávajú funkčné; nasadenie Connectora ich nenúti migrovať. Iba pri Connector volaniach vyberá firmu customerRef a X-Firm-Id sa neposiela.
POST/api/v1/connector/documents

Odoslať business doklad

Potrebný scope: documents:send

Recommended Connector entry point. Send ordinary business JSON and identify the recipient with a company ID, tax ID, or VAT ID. ePošťák verifies the exact recipient and capability, then uses the managed delivery pipeline. delivery=send is an explicit instruction from a documents:send scope holder and proceeds to physical dispatch regardless of autoSendEnabled, which governs only automated policy-driven sources. state=queued after delivery=send means asynchronous dispatch was accepted; without send/cancel links it is not a staged document waiting for manual action. Only delivery=stage stores a new command and returns send/cancel links. externalId and Idempotency-Key are unique within the assigned Connector mailbox/customerRef. A replay of the same command returns the original result, including a historical staged state without automatically sending it; reusing either identifier with different content returns 409. When both are supplied they must identify the same business command. Odporúčaný Connector endpoint. Pošlete bežný business JSON a príjemcu určíte cez IČO, DIČ alebo IČ DPH. ePošťák overí presnú firmu a použije riadené doručenie. Predvolené delivery=send je explicitný pokyn držiteľa scope documents:send a pokračuje do fyzického odoslania bez ohľadu na autoSendEnabled, ktoré riadi iba automatizované policy-driven zdroje. state=queued po delivery=send znamená prijaté asynchrónne odoslanie; bez send/cancel odkazov nejde o staged doklad čakajúci na manuálny zásah. delivery=stage je jediný create tok, ktorý doklad iba bezpečne uloží a pri novom príkaze vráti send aj cancel odkazy. externalId aj Idempotency-Key sú jedinečné v rámci prideleného Connector mailboxu pre customerRef; rovnaký príkaz sa bezpečne replayne, ale opätovné použitie ktoréhokoľvek identifikátora s iným obsahom vráti 409 IDEMPOTENCY_CONFLICT. Historický replay vráti pôvodný stav a nikdy ho automaticky neodošle. Ak pošlete oba identifikátory, musia označovať ten istý príkaz.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.
Idempotency-KeystringREQStable retry key scoped to the assigned Connector mailbox/customerRef. Reusing it with the same command is safe; different content returns 409 IDEMPOTENCY_CONFLICT. (max 255 znakov / chars)

Parametre

NázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
externalIdstringREQmax 255 znakov / chars
deliverystringoptionalsend (default) dispatches the document; stage only stores it for a later send or cancel. A staged document is kept for 14 days; after that it is cancelled and can no longer be sent. (default: send) (povolené: send, stage)
typestringoptional (default: invoice) (povolené: invoice, credit_note, debit_note, prepayment_invoice, advance_payment, correction, self_billing_invoice, self_billing_credit_note)
numberstringREQmax 255 znakov / chars
precedingDocumentNumberstringoptionalOriginal invoice number. Required for credit_note, self_billing_credit_note, correction (384) and debit_note (383). At most 100 characters. (max 255 znakov / chars)
recipientobjectREQ
recipient.countrystringREQISO country code that determines how the ordinary identifier is interpreted. (max 2 znakov / chars, pattern ^[A-Za-z]{2}$)
recipient.namestringoptionalmax 255 znakov / chars
recipient.companyIdstringoptionalCompany registration number for this country. Do not put a tax or VAT identifier in this field. At most 20 characters. (max 255 znakov / chars)
recipient.taxIdstringoptionalLocal tax identifier for this country. Do not put a company registration or VAT identifier in this field. At most 20 characters. (max 255 znakov / chars)
recipient.vatIdstringoptionalVAT identifier for this country. Do not put a company registration or local tax identifier in this field. At most 20 characters. (max 255 znakov / chars)
recipient.networkIdstringoptionalOptional expert override. The identifier is still verified before use. At most 100 characters. (max 255 znakov / chars)
recipient.addressobjectoptionalstreet at most 255, city at most 120 and postalCode at most 20 characters.
recipient.address.streetstringoptional
recipient.address.citystringoptional
recipient.address.postalCodestringoptionalmax 32 znakov / chars
issueDatedateoptional
dueDatedateoptional
taxPointDatedateoptionalVAT tax point date (BT-7). Kept separate from the actual delivery date. For advance_payment (388) and prepayment_invoice (386) it is the date the payment was received; required for 388, not after issueDate and not in the future.
deliveryDatedateoptionalActual delivery date for the whole document (BT-72).
documentDiscountPercentnumberoptionalDocument-level discount percentage represented as a Peppol BG-20 allowance. This is additional to any lines[].discount. (0–100)
currencystringoptionalmax 3 znakov / chars (default: EUR)
notestringoptionalmax 5000 znakov / chars
ibanstringoptionalmax 64 znakov / chars
paymentMethodstringoptionalUNCL4461 payment means code (e.g. 30 bank transfer). At most 30 characters.
paymentTermsstringoptionalPeppol BT-20 textual payment terms. (max 500 znakov / chars)
variableSymbolstringoptionalAt most 50 characters. Only its digits are kept and sent as the payment identifier (PaymentID) (Slovak variable symbol); when more than 10 digits remain, the last 10 are used. A value without digits is treated as not sent. The format is never refused.
buyerReferencestringoptionalPeppol BT-10 internal buyer routing reference, up to 100 characters. A document must contain buyerReference or orderReference. (max 100 znakov / chars, pattern \S)
orderReferencestringoptionalPeppol BT-13 purchase-order reference, up to 100 characters. A document must contain orderReference or buyerReference. (max 100 znakov / chars, pattern \S)
contractReferencestringoptionalOptional contract number (BT-12), up to 100 characters. (max 100 znakov / chars)
projectReferencestringoptionalOptional project reference (BT-11), up to 100 characters. (max 100 znakov / chars)
invoicePeriodStartdateoptionalOptional first day of the billing period (BT-73) in YYYY-MM-DD format.
invoicePeriodEnddateoptionalOptional last day of the billing period (BT-74) in YYYY-MM-DD format. It must not be before invoicePeriodStart.
prepaidAmountnumberoptionalmin 0
prepaymentsobject[]optionalmax 100 položiek / items
prepayments[].advanceInvoiceRefstringoptional
prepayments[].taxDocumentRefstringoptional
prepayments[].settlementDatedateoptional
prepayments[].amountWithoutVatnumberoptionalmin 0
prepayments[].vatAmountnumberoptionalmin 0
prepayments[].amountWithVatnumberREQmin 0
prepayments[].vatRatenumberoptional0–100
prepayments[].taxTreatmentstringoptional (povolené: standard, zero_rated, reverse_charge, exempt, intra_community_supply, export, out_of_scope)
linesobject[]REQAt most 999 lines. (max 1000 položiek / items)
lines[].descriptionstringREQmax 1000 znakov / chars
lines[].quantitynumberREQNon-zero. A negative quantity on a standard line is a discount or returned item (unitPrice stays non-negative); lineType=advance_deduction requires a negative quantity.
lines[].unitstringoptionalmax 16 znakov / chars
lines[].unitPricenumberREQmin 0
lines[].vatRatenumberREQSlovak VAT rate: 0, 5, 10, 19, 20 or 23. Must be 0 for zero_rated, reverse_charge, exempt, intra_community_supply, export and out_of_scope, and greater than 0 for standard. (0–100)
lines[].taxTreatmentstringoptional (povolené: standard, zero_rated, reverse_charge, exempt, intra_community_supply, export, out_of_scope)
lines[].taxExemptionReasonCodestringoptionalPeppol BT-121 VAT exemption reason code from the current CEF VATEX list. The code must match taxTreatment and is allowed only for exempt or non-taxable values. (max 255 znakov / chars)
lines[].taxExemptionReasonstringoptionalPeppol BT-120 human-readable VAT exemption reason. Allowed only for exempt or non-taxable taxTreatment values. (max 1000 znakov / chars)
lines[].discountnumberoptional0–100
lines[].deliveryDatedateoptional
lines[].lineTypestringoptionalstandard (default) or advance_deduction. advance_deduction requires a negative quantity and advanceInvoiceReference.
lines[].advanceInvoiceReferencestringoptional
lines[].customsTariffCodestringoptionalCustoms tariff (KN) code, 4-10 digits.
lines[].commodityClassificationCodestringoptional
lines[].commodityClassificationListIdstringoptional
lines[].reverseChargeParagraphLetterstringoptional
lines[].controlStatementTypestringoptionalKontrolný výkaz reverse-charge category: IO or MT.
lines[].controlStatementQuantitynumberoptionalGreater than 0 when present. (min 0)
lines[].controlStatementUnitstringoptionalkg, t, m or ks.
attachmentsobject[]optionalmax 20 položiek / items
attachments[].fileNamestringREQmax 255 znakov / chars
attachments[].mimeTypestringREQapplication/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet or application/vnd.oasis.opendocument.spreadsheet. (max 255 znakov / chars)
attachments[].contentbase64REQBase64 file content. At most 10 MB per file and 15 MB for all attachments together (decoded); the bytes must match mimeType.
attachments[].descriptionstringoptionalmax 1000 znakov / chars

Príklady volania

Odoslať teraz
curl -X POST https://dev.epostak.sk/api/v1/connector/documents \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Idempotency-Key: erp-acme:invoice:2026-0042" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"erp-acme","externalId":"invoice-2026-0042","type":"invoice","number":"2026-0042","recipient":{"country":"SK","taxId":"2120123456"},"issueDate":"2026-07-14","dueDate":"2026-07-28","taxPointDate":"2026-07-13","deliveryDate":"2026-07-12","documentDiscountPercent":5,"currency":"EUR","paymentTerms":"Splatnosť 14 dní","buyerReference":"ODD-IT","orderReference":"OBJ-1042","lines":[{"description":"Mesačná licencia","quantity":1,"unitPrice":100,"vatRate":23}]}'

Príklady odpovedí

200 Idempotent replay of the same document
{
  "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
  "customerRef": "erp-acme",
  "externalId": "invoice-2026-0042",
  "direction": "outbound",
  "type": "invoice",
  "number": "2026-0042",
  "state": "queued",
  "replayed": true,
  "currency": "EUR",
  "amounts": {
    "withoutTax": 100,
    "tax": 23,
    "total": 123,
    "due": 123
  },
  "createdAt": "2026-07-14T10:00:00.000Z",
  "updatedAt": "2026-07-14T10:00:00.000Z",
  "links": {
    "self": "/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme",
    "evidence": "/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"
  }
}
201 Document accepted into the managed flow
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c222","customerRef":"erp-acme","externalId":"invoice-2026-0043","direction":"outbound","type":"invoice","number":"2026-0043","state":"queued","replayed":false,"recipient":{"name":"ODBERATEĽ, s.r.o.","country":"SK","taxId":"2120123456","resolution":"verified"},"links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c222?customerRef=erp-acme","send":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c222/send?customerRef=erp-acme","cancel":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c222/cancel?customerRef=erp-acme"}}
409 CUSTOMER_NOT_READY, IDEMPOTENCY_CONFLICT, or RECIPIENT_AMBIGUOUS
{"error":{"code":"IDEMPOTENCY_CONFLICT","message":"The idempotency key or external ID was reused with different document content.","retryable":false,"nextAction":"Retry the original document unchanged or use a new idempotency key and external ID.","requestId":"req_01JZ..."}}
422 Invalid document, recipient not found/not reachable, or SELF_ADDRESSED_SEND when the receiver is the sender's own Peppol ID (test network too)
{"error":{"code":"DOCUMENT_INVALID","message":"lines must contain at least one item","field":"lines","retryable":false,"nextAction":"Correct the indicated document field and retry.","requestId":"req_01JZ..."}}
429 Connector rate limit exceeded. Retry only after the advertised delay.
{"error":{"code":"DELIVERY_TEMPORARILY_UNAVAILABLE","message":"Too many Connector requests.","retryable":true,"nextAction":"Retry after the Retry-After delay with the same Idempotency-Key.","requestId":"req_01JZ..."}}
503 Recipient verification or delivery temporarily unavailable
{"error":{"code":"DELIVERY_TEMPORARILY_UNAVAILABLE","message":"The document could not be queued for delivery right now.","retryable":true,"nextAction":"Retry the same request with the same idempotency key later.","requestId":"req_01JZ..."}}

Odpovede

  • 200Idempotent replay of the same document
  • 201Document accepted into the managed flow
  • 400Malformed JSON; returns a correlated DOCUMENT_INVALID business error
  • 401Missing, expired, or invalid Connector access token
  • 403The credential is valid but lacks the required scope, firm access, or plan entitlement for this operation. Retrying with the same credential does not help.
  • 409CUSTOMER_NOT_READY, IDEMPOTENCY_CONFLICT, or RECIPIENT_AMBIGUOUS
  • 413Request body exceeds the limit; returns a correlated DOCUMENT_INVALID business error
  • 422Invalid document, recipient not found/not reachable, or SELF_ADDRESSED_SEND when the receiver is the sender's own Peppol ID (test network too)
  • 429Connector rate limit exceeded. Retry only after the advertised delay.
  • 503Recipient verification or delivery temporarily unavailable
GET/api/v1/connector/documents

Zoznam dokladov

Potrebný scope: documents:read

Returns business-only documents for one approved customer. Tenant scope and the consent floor are applied before data is read.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
directionstring (query)optional (povolené: inbound, outbound)
statestring (query)optional (povolené: queued, sending, delivered, received, processed, needs_attention, failed, cancelled)
typestring (query)optional (povolené: invoice, credit_note, debit_note, prepayment_invoice, advance_payment, correction, self_billing_invoice, self_billing_credit_note)
createdAfterdatetime (query)optional
cursorstring (query)optional
limitinteger (query)optional1–100 (default: 50)

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/documents?customerRef=erp-acme&direction=inbound&state=received" -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Cursor-paged business document list
{
  "documents": [
    {
      "id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
      "customerRef": "erp-acme",
      "externalId": null,
      "direction": "inbound",
      "type": "invoice",
      "number": "2026-0088",
      "state": "received",
      "currency": "EUR",
      "amounts": { "withoutTax": 100, "tax": 23, "total": 123, "due": 123 },
      "sender": { "name": "Dodávateľ, s.r.o.", "country": "SK", "companyId": "12345678", "taxId": "2120123456", "vatId": "SK2120123456" },
      "recipient": { "name": "Odberateľ, s.r.o.", "country": "SK", "companyId": "87654321", "taxId": "2199999999", "vatId": "SK2199999999" },
      "issueDate": "2026-07-14",
      "dueDate": "2026-07-28",
      "processedAt": null,
      "processedReference": null,
      "response": null,
      "createdAt": "2026-07-14T10:00:00.000Z",
      "updatedAt": "2026-07-14T10:01:00.000Z",
      "links": {
        "self": "/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme",
        "evidence": "/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme",
        "acknowledge": "/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/acknowledge?customerRef=erp-acme"
      }
    }
  ],
  "nextCursor": "eyJ2IjoxLCJyIjoiMjAyNi0wNy0xNFQxMDowMTowMC4wMDBaIiwiaSI6IjhlNGI4ZjBlLTIxZDMtNGQyYS05YzJiLTI0YTNmOGEwYzExMSJ9",
  "hasMore": true
}

Odpovede

  • 200Cursor-paged business document list
  • 401Missing, expired, or invalid API key or access token. Get a new access token and retry; the error code says which credential was rejected.
  • 403The credential is valid but lacks the required scope, firm access, or plan entitlement for this operation. Retrying with the same credential does not help.
  • 409Customer not ready
  • 422Invalid query parameter
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.
GET/api/v1/connector/documents/{documentId}

Detail business dokladu

Potrebný scope: documents:read

Backward-compatible dual contract. Calling an established Invoice documentId without customerRef returns the original ERP lifecycle shape and preserves that documentId and its links. Supplying customerRef, or addressing a canonical Connector run ID, returns the canonical business document. include=technical remains available for the lifecycle projection. Visibility is limited to documents created after consent. When no submitted Connector payload lists attachments (received invoices, invoices issued outside Connector), the detail returns the files embedded in the Peppol document in attachments with fileName, mimeType and base64 content; lists, polled events and webhooks do not carry them.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentIduuidREQ
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
includestring (query)optionalRequests the established technical lifecycle projection. (povolené: technical)

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme" -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Established lifecycle detail or canonical business document, selected as described above
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"delivered","response":{"status":"accepted","direction":"received","reason":null,"respondedAt":"2026-07-15T10:05:00.000Z"}}

Odpovede

  • 200Established lifecycle detail or canonical business document, selected as described above
  • 401Unauthorized
  • 403Forbidden
  • 404Document not found
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.
POST/api/v1/connector/documents/{documentId}/send

Odoslať uložený doklad

Potrebný scope: documents:send

Sends a document created with delivery=stage. Call this operation only when the create or detail response contains links.send. The request has no body. Replays are safe: a completed send returns 200; an in-flight send returns 202 with state=sending for polling through document detail or events. A staged document is kept for 14 days. After that its stored content expires: the document moves to state=cancelled, links.send disappears, and this operation returns 422 DOCUMENT_INVALID with retryable=false. Submit the document again with a new externalId.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentIduuidREQDocument ID from the create response, document list, or events.
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/send?customerRef=erp-acme" -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Send accepted or safe replay of a completed send
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","state":"queued","replayed":false,"links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}
202 Send is in flight; response state is sending and can be polled
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","direction":"outbound","type":"invoice","number":"2026-0042","state":"sending","replayed":false,"links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme"}}
422 Document is not eligible for this action, for example a staged document older than 14 days whose stored content expired
{"error":{"code":"DOCUMENT_INVALID","message":"The stored content of this staged document has expired or was replaced and can no longer be sent.","field":"documentId","retryable":false,"nextAction":"Do not retry this documentId. Submit the document again as a new staged document with a new externalId.","requestId":"req_01JZ..."}}

Odpovede

  • 200Send accepted or safe replay of a completed send
  • 202Send is in flight; response state is sending and can be polled
  • 401Unauthorized
  • 403Forbidden
  • 404Opaque not found: the document is unavailable or customerRef is blank, repeated, or mismatched
  • 409Customer is not ready to send
  • 422Document is not eligible for this action, for example a staged document older than 14 days whose stored content expired
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.
  • 503Delivery is temporarily unavailable
POST/api/v1/connector/documents/{documentId}/cancel

Zrušiť uložený doklad

Potrebný scope: documents:send

Cancels a staged document before sending starts. Call this operation only when the create or detail response contains links.cancel. The request has no body and repeated cancellation is idempotent.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentIduuidREQDocument ID from the create response, document list, or events.
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/cancel?customerRef=erp-acme" -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Document cancelled or safe replay of an earlier cancellation
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","direction":"outbound","type":"invoice","number":"2026-0042","state":"cancelled","replayed":false,"links":{"self":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}

Odpovede

  • 200Document cancelled or safe replay of an earlier cancellation
  • 401Unauthorized
  • 403Forbidden
  • 404Opaque not found: the document is unavailable or customerRef is blank, repeated, or mismatched
  • 422Document is not eligible for cancellation
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.
  • 503Cancellation is temporarily unavailable
POST/api/v1/connector/documents/{documentId}/acknowledge

Potvrdiť spracovanie

Potrebný scope: documents:write

Idempotently records that the ERP processed an inbound document. This is local state only and does not emit a recipient response or change transport state.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentIduuidREQ
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
referencestringREQmax 255 znakov / chars

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/acknowledge?customerRef=erp-acme" -H "Authorization: Bearer eyJhbGc..." -H "Content-Type: application/json" -d '{"reference":"erp-import-8471"}'

Príklady odpovedí

200 Processing recorded or already recorded
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","state":"processed","processedAt":"2026-07-14T10:05:00.000Z","reference":"erp-import-8471","idempotent":false}
413 Acknowledgement body exceeds 64 KiB
{"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds the 64 KiB limit.","retryable":false,"nextAction":"Send only the local ERP processing reference.","requestId":"req_connector_01J2YQ5B"}}

Odpovede

  • 200Processing recorded or already recorded
  • 401Missing, expired, or invalid API key or access token. Get a new access token and retry; the error code says which credential was rejected.
  • 403The credential is valid but lacks the required scope, firm access, or plan entitlement for this operation. Retrying with the same credential does not help.
  • 404Document not found in the permitted customer scope
  • 413Acknowledgement body exceeds 64 KiB
  • 422Document cannot be acknowledged or request is invalid
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.
GET/api/v1/connector/events

Connector udalosti

Potrebný scope: documents:read

Canonical polling-first document event stream for one approved customerRef. customerRef is always at the event root. Persist nextCursor only after committing the returned events locally. Operational connection, intake, mapping, review, and ERP-delivery events use the separate feature-gated /connector/operations/events stream, so this released response contract remains unchanged.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
cursorstring (query)optionalOpaque cursor from the previous response.
limitinteger (query)optional1–500 (default: 100)

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/events?customerRef=erp-acme&limit=100" -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 OK
{"events":[{"id":"evt_01J2YQ5A","customerRef":"erp-acme","documentId":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","type":"document.cancelled","state":"cancelled","occurredAt":"2026-07-14T10:01:00.000Z","data":{"direction":"outbound","type":"invoice","number":"2026-0042","response":null}}],"nextCursor":"eyJ0cyI6IjIwMjYtMDctMTRUMTA6MDE6MDAuMDAwWiIsImlkIjoiZXZ0XzAxSjJZUTVBIn0","hasMore":false}

Odpovede

  • 200OK
  • 401Unauthorized
  • 403API plan required or access denied
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.
POST/api/v1/connector/documents/{documentId}/respond

Odoslať business odpoveď na faktúru

Potrebný scope: documents:write

Sends a business response for an inbound invoice to the counterparty. This is different from acknowledge: acknowledge records the local ERP import only, while respond sends a Peppol Invoice Response behind this business-language contract. The integrator does not call the internal ePošťák Box or an Enterprise endpoint. The strict JSON body is limited to 32 KB and note to 500 characters. Repeating an already stored identical status is a safe idempotent replay. Odošle odosielateľovi prijatej faktúry business odpoveď cez Peppol Invoice Response, ale ERP pracuje iba so stavmi uvedenými nižšie. Je to odlišné od acknowledge: acknowledge iba lokálne zaznamená úspešný import do ERP, zatiaľ čo respond informuje protistranu. Interný ePošťák Box ani Enterprise endpoint integrátor nevolá. Telo je striktné, najviac 32 KiB; note má najviac 500 znakov. Rovnaký už uložený stav sa bezpečne replayne s idempotent=true.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentIduuidREQInbound invoice ID.
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
statusstringREQ (povolené: received, in_process, under_query, conditionally_accepted, rejected, accepted, paid)
notestringoptionalOptional explanation sent to the counterparty. (max 500 znakov / chars)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/respond?customerRef=erp-acme" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"status":"under_query","note":"Prosíme doplniť číslo objednávky."}'

Príklady odpovedí

200 Response sent, or a safe replay of an already stored identical status.
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","response":{"status":"under_query","direction":"sent","delivery":"sent","respondedAt":"2026-07-15T10:05:00.000Z"},"idempotent":false}
202 Response accepted and queued for delivery.
{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","response":{"status":"accepted","direction":"sent","delivery":"queued","respondedAt":"2026-07-15T10:05:00.000Z"},"idempotent":false}

Odpovede

  • 200Response sent, or a safe replay of an already stored identical status.
  • 202Response accepted and queued for delivery.
  • 400Connector business error.
  • 401Connector business error.
  • 403Connector business error.
  • 404Connector business error.
  • 409Connector business error.
  • 413Request body exceeds 32 KB.
  • 422Connector business error.
  • 429Connector business error.
  • 503Connector business error.
GET/api/v1/connector/webhook

Načítať Connector webhook

Potrebný scope: webhooks:read

Returns the single Connector webhook configuration for this integrator. No X-Firm-Id is used. webhook is null until configured.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Príklady volania

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

Príklady odpovedí

200 Current configuration or webhook=null.
{"webhook":{"id":"wh_01JZ...","url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered"],"active":true,"failedAttempts":0,"createdAt":"2026-07-15T09:00:00.000Z","updatedAt":"2026-07-15T09:00:00.000Z"}}

Odpovede

  • 200Current configuration or webhook=null.
  • 401Request rejected.
  • 403Request rejected.
PUT/api/v1/connector/webhook

Vytvoriť alebo aktualizovať webhook

Potrebný scope: webhooks:write

Configures one global webhook for the integrator. The JSON body is limited to 32 KB. Omitting events preserves the backward-compatible default of the seven document events; customer lifecycle events require explicit opt-in. Creation returns the HMAC secret once; an update keeps the existing secret. No X-Firm-Id is used.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
urlstringREQPublic HTTPS receiver URL.
eventsstring[]optionalOptional document and customer lifecycle filter. Omit both event fields to subscribe only to the backward-compatible document default (document.queued, document.delivered, document.received, document.processed, document.needs_attention, document.failed, document.cancelled). Customer lifecycle events require explicit opt-in. (max 15 položiek / items)
operationalEventsstring[]optionalOptional feature-gated connection, intake, mapping, review, and ERP-delivery lifecycle subscriptions. (max 58 položiek / items)

Príklady volania

cURL
curl -X PUT "https://dev.epostak.sk/api/v1/connector/webhook" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed","customer.active","customer.provider_change_requested","customer.provider_changed"]}'

Príklady odpovedí

200 Webhook updated; the existing signing secret remains active.
{"webhook":{"id":"wh_01JZ...","url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed"],"active":true,"failedAttempts":0,"createdAt":"2026-07-15T09:00:00.000Z","updatedAt":"2026-07-15T09:10:00.000Z"}}
201 Webhook created. Store the signing secret now; it is shown only once.
{"webhook":{"id":"wh_01JZ...","url":"https://erp.example.com/epostak/events","events":["document.received","document.delivered","document.failed"],"active":true,"failedAttempts":0,"createdAt":"2026-07-15T09:00:00.000Z","updatedAt":"2026-07-15T09:00:00.000Z"},"secret":"7c4a8d09ca3762af61e59520943dc26494f8941b7a8331369f7f16f2e19f6c21"}

Odpovede

  • 200Webhook updated; the existing signing secret remains active.
  • 201Webhook created. Store the signing secret now; it is shown only once.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 413Request body exceeds 32 KB.
  • 422Request rejected.
DELETE/api/v1/connector/webhook

Odstrániť Connector webhook

Potrebný scope: webhooks:write

Stops new push deliveries and removes the Connector webhook. Polling through GET /connector/events remains available for reconciliation. No X-Firm-Id is used.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Príklady volania

cURL
curl -X DELETE "https://dev.epostak.sk/api/v1/connector/webhook" \
  -H "Authorization: Bearer eyJhbGc..."

Odpovede

  • 204Webhook deleted.
  • 401Request rejected.
  • 403Request rejected.
POST/api/v1/connector/webhook/rotate-secret

Otočiť podpisový secret

Potrebný scope: webhooks:write

Replaces the HMAC signing secret and returns the new secret once. No X-Firm-Id is used.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Príklady volania

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

Príklady odpovedí

200 New signing secret, shown once.
{"secret":"7c4a8d09ca3762af61e59520943dc26494f8941b7a8331369f7f16f2e19f6c21"}

Odpovede

  • 200New signing secret, shown once.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
POST/api/v1/connector/webhook/test

Otestovať Connector webhook

Potrebný scope: webhooks:write

Queues one signed test event for an approved customerRef. The event has the same canonical business shape as polling and production pushes, plus test=true. No X-Firm-Id is used.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
eventstringoptionalOptional business event; defaults to document.queued. (povolené: document.queued, document.delivered, document.received, document.processed, document.needs_attention, document.failed, document.cancelled, customer.active, customer.integration_detachment_scheduled, customer.integration_detachment_cancelled, customer.integration_detached, customer.provider_change_requested, customer.provider_change_cancelled, customer.provider_changed, customer.deactivated)
scenariostringoptionalOptional deterministic receiver scenario. (povolené: success, deduplication, retry_503, rate_limit_429, terminal_422, timeout, signature)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/webhook/test" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"erp-acme"}'

Príklady odpovedí

202 Test delivery queued.
{"deliveryId":"whd_01JZ...","status":"queued","event":{"id":"evt_test_01JZ...","customerRef":"erp-acme","documentId":"doc_test_01JZ...","type":"document.received","state":"received","occurredAt":"2026-07-15T09:15:00.000Z","data":{"direction":"inbound","type":"invoice","number":"TEST-2026-001"},"test":true}}

Odpovede

  • 202Test delivery queued.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
GET/api/v1/connector/webhook/deliveries

História webhook doručení

Potrebný scope: webhooks:read

Cursor-paged push delivery diagnostics across the integrator's customerRef values. Use GET /connector/events as the business reconciliation checkpoint. No X-Firm-Id is used.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
cursorstring (query)optionalOpaque cursor from the previous response.
limitinteger (query)optional1–100 (default: 50)
statusstring (query)optionalOptional delivery-status filter. (povolené: PENDING, SUCCESS, FAILED, RETRYING)
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
typestring (query)optional (povolené: document.queued, document.delivered, document.received, document.processed, document.needs_attention, document.failed, document.cancelled, customer.active, customer.integration_detachment_scheduled, customer.integration_detachment_cancelled, customer.integration_detached, customer.provider_change_requested, customer.provider_change_cancelled, customer.provider_changed, customer.deactivated, connection.created, connection.updated, connection.disabled, connection.credential_rotated, connection.test_passed, connection.test_failed, connection.learning_started, connection.learning_stopped, connection.adapter_quarantined, intake.received, intake.sample_received, intake.scanning, intake.ocr_extracted, intake.transforming, intake.validating, intake.needs_review, intake.staged, intake.sending, intake.sent, intake.delivered, intake.malware_rejected, intake.mapping_failed, intake.validation_failed, intake.retry_later, intake.failed_internal, intake.cancelled, intake.sampled, intake.learning_corpus_updated, intake.learning_candidate_created, mapping.profile_created, mapping.candidate_created, mapping.revision_approved, mapping.revision_activated, mapping.revision_rolled_back, mapping.technical_certified, mapping.probation_reset, mapping.automation_enabled, mapping.pdf_probation_started, mapping.pdf_probation_ready, mapping.pdf_automation_enabled, mapping.pdf_suspended, review.opened, review.claimed, review.released, review.resolved, review.cancelled, delivery.received, delivery.transforming, delivery.validating, delivery.needs_review, delivery.staged, delivery.ready, delivery.delivering, delivery.delivered, delivery.acknowledged, delivery.retry_later, delivery.failed, delivery.cancelled)
testboolean (query)optional
fromdatetime (query)optional
todatetime (query)optionalThe from/to range may not exceed 90 days.

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/webhook/deliveries?customerRef=erp-acme&status=FAILED&test=false&limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Webhook delivery history.
{"deliveries":[{"id":"whd_01JZ...","eventId":"evt_01JZ...","customerRef":"erp-acme","type":"document.received","status":"SUCCESS","attempts":1,"responseStatus":204,"lastAttemptAt":"2026-07-15T09:16:00.000Z","nextRetryAt":null,"createdAt":"2026-07-15T09:15:59.000Z"}],"nextCursor":"eyJpZCI6IndoZF8wMUpaLi4uIn0","hasMore":false}

Odpovede

  • 200Webhook delivery history.
  • 401Request rejected.
  • 403Request rejected.
GET/api/v1/connector/webhook/deliveries/{deliveryId}

Detail doručenia udalosti

Potrebný scope: webhooks:read

Returns the authorized business event, exact signed request body when available, safe endpoint origin/path, diagnosis and every real delivery execution. Historical rows never fabricate missing attempts.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
deliveryIduuidREQ

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/webhook/deliveries/DELIVERY_ID" \
  -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN"

Odpovede

  • 200Authorized delivery evidence.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
POST/api/v1/connector/webhook/deliveries/{deliveryId}/replay

Zopakovať presné doručenie

Potrebný scope: webhooks:write

Durably creates a new delivery while preserving the original event ID, customerRef, business payload and exact raw request body. A successful real delivery requires explicit confirmation so the receiver can deduplicate the unchanged event ID.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.
Idempotency-KeystringREQmax 255 znakov / chars

Parametre

NázovTypPovinnéPopis
deliveryIduuidREQ
confirmSuccessfulReplaybooleanoptional (default: false)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/webhook/deliveries/DELIVERY_ID/replay" \
  -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN" \
  -H "Idempotency-Key: replay-erp-acme-001" \
  -H "Content-Type: application/json" -d '{}'

Odpovede

  • 200Idempotent repeat of an accepted replay.
  • 202Replay durably accepted; pending publication recovery remains automatic.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 429Request rejected.
POST/api/v1/connector/webhook/test-suite

Spustiť sedem testov prijímača

Potrebný scope: webhooks:write

Runs selected scenarios through the real signing, authorization, queue, endpoint-safety and delivery path with three test attempts at 0, 5 and 30 seconds. Test failures never affect the production circuit breaker.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.
Idempotency-KeystringREQmax 255 znakov / chars

Parametre

NázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
eventstringoptional (default: document.queued) (povolené: document.queued, document.delivered, document.received, document.processed, document.needs_attention, document.failed, document.cancelled, customer.active, customer.integration_detachment_scheduled, customer.integration_detachment_cancelled, customer.integration_detached, customer.provider_change_requested, customer.provider_change_cancelled, customer.provider_changed, customer.deactivated)
scenariosstring[]optionalmax 7 položiek / items (default: ["success","deduplication","retry_503","rate_limit_429","terminal_422","timeout","signature"])

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/webhook/test-suite" \
  -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN" \
  -H "Idempotency-Key: diagnostics-20260716-01" \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"erp-acme"}'

Odpovede

  • 200Idempotent repeat of the same run.
  • 202Diagnostic run durably accepted.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 429Request rejected.
GET/api/v1/connector/webhook/test-suite/{testRunId}

Sledovať diagnostický test

Potrebný scope: webhooks:read

Returns scenario progress. Replay identity intentionally pauses with REPLAY_TEST_DELIVERY after its first success; replay the supplied delivery through the normal replay endpoint. The suite proves stable event ID/body and signed-request acceptance, but cannot observe the receiver's internal deduplication or HMAC calculation.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
testRunIduuidREQ

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/webhook/test-suite/TEST_RUN_ID" \
  -H "Authorization: Bearer $EPOSTAK_ACCESS_TOKEN"

Odpovede

  • 200Diagnostic run progress.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.

Universal Connector · súkromný DEV pilot

Voliteľná pilotná cesta pre ERP, ktoré chcú odovzdávať svoje existujúce exporty namiesto implementácie kanonického Connector JSON. Stabilný Connector API tok vyššie sa nemení.

Dostupnosť je potvrdená serverom

Preview sa zobrazí iba explicitne povolenému integrátorovi v DEV a jednotlivé kanály môžu byť zapnuté samostatne. Mimo pilotného allowlistu nové operácie vracajú zámerne neurčité 404. Ich prítomnosť v OpenAPI neznamená produkčnú dostupnosť ani povinnú migráciu existujúcich integrácií.

  • OpenAPI značka: x-epostak-availability: private-preview.
  • Produkčný pilot vyžaduje samostatné schválenie; stabilné /connector/documents a /connector/events pokračujú bez zmeny.

Jeden cloudový tok, viac spôsobov pripojenia

Nastavenie ide cez connection → bezpečný test → vzorky a mapovanie → review alebo stage → povolenú automatiku. API, portál, e-mail, SFTP a Bridge sú iba adaptéry nad rovnakým intake, validáciou, auditom a Peppol doručením; dostupné sú iba kanály potvrdené v Cockpite.

  • Epostak-Connection môže bezpečne určiť firmu, profil a delivery politiku; zdrojový súbor ani AI tieto väzby nemenia.
  • AI vytvorí iba kandidáta mapovania. Produkčný replay používa deterministickú, pripnutú a auditovateľnú revíziu.

Bridge pre Windows a macOS

V Cockpite vyberte ePošťák Bridge a platformu. Tlačidlo na stiahnutie sa zobrazí priamo vedľa pairing kroku iba vtedy, keď je pre pilot publikovaný schválený podpísaný klient. macOS distribúcia navyše vyžaduje Developer ID podpis a notarizáciu; nepodpísaný interný build sa zákazníkom neponúka.

  • Po stiahnutí vytvorte 15-minútový pairing kód pre konkrétne connection.
  • Kontrola neistého dokladu sa robí v cloudovom ePošťák portáli, nie v lokálnom Bridge klientovi.
Pilotný kontrakt: importujte rovnaký Connector OpenAPI JSON, ale preview operácie generujte alebo volajte iba vtedy, keď váš DEV účet dostal príslušnú capability. Stabilné operácie bez preview značky majú naďalej vlastný release kontrakt.
POST/api/v1/connector/intakesSúkromný pilot

Accept an ERP export for asynchronous Peppol processing

Potrebný scope: documents:send, firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Feature-gated, channel-neutral intake shared by direct API, portal, SFTP, email and Bridge adapters. The source artifact and intake record are stored durably before HTTP 202 is returned. A normal non-UBL source pins the exact active Mapping Spec revision at acceptance; recognized Peppol Billing or Self-Billing UBL can use validated passthrough without a profile. When Epostak-Connection has an explicitly started learning session, the server instead classifies the intake as onboarding_sample, forces stage, accepts only the bounded sample set and never invokes Autopilot or Peppol. Requested send remains stage-only until the selected structured or eligible digital-PDF profile is certified and auto-send is explicitly enabled. Scans and images require human review.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.
Epostak-Customer-RefstringoptionalIntegrator-owned routing reference for an approved company. Required when Epostak-Connection is omitted. It is never read from the source document or AI output. (max 128 znakov / chars)
Epostak-ConnectionuuidoptionalTrusted connection binding that derives the company, outbound profile and delivery policy. Required when Epostak-Customer-Ref is omitted. If both selectors are sent, they must resolve to the same company.
Epostak-Mapping-ProfilestringoptionalMapping profile key. An active revision is required for production non-UBL intake. A server-started connection learning session may use its bound draft profile without granting runtime or send authority. (max 120 znakov / chars, pattern ^[a-z0-9][a-z0-9._-]{1,119}$)
Idempotency-KeystringREQStable replay key. Reuse with identical bytes and metadata returns the existing intake; reuse with different input returns 409. (max 255 znakov / chars)
Epostak-DeliverystringoptionalRequested delivery. send is honored only when the exact pinned structured profile revision has document-type auto-send permission. (default: stage) (povolené: stage, send)

Parametre

NázovTypPovinnéPopis
bodyapplication/json | application/xml | text/xml | application/ubl+xml | text/csvREQ
documentfileREQOne PDF, JPEG, PNG or WebP file. OCR inputs always require review.

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/intakes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpovede

  • 202Artifact and intake accepted durably, or an exact idempotent replay resolved to the existing intake
  • 400Malformed source or multipart request
  • 401Unauthorized
  • 403Forbidden, insufficient scope or customerRef is not approved for the integrator
  • 404Universal intake feature is unavailable
  • 409Idempotency-Key was reused with different content or metadata
  • 411Content-Length is required for bounded multipart parsing
  • 413Production structured input exceeds 22 MiB, an onboarding structured sample exceeds 2 MiB, or OCR input exceeds 20 MiB
  • 415Unsupported or MIME-spoofed source content
  • 422Metadata, mapping profile or source structure is invalid
  • 429Rate limit exceeded
GET/api/v1/connector/intakes/{intakeId}Súkromný pilot

Get asynchronous intake status

Potrebný scope: documents:send, firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Returns the tenant-isolated status of one accepted intake, including its pinned profile revision, review requirement, effective delivery and safe failure code. Raw source or extracted accounting values are never returned.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
intakeIduuidREQ

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/intakes/<intakeId>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Current intake state
  • 401Unauthorized
  • 403Forbidden or insufficient scope
  • 404Intake was not found or the feature is unavailable
  • 429Rate limit exceeded
POST/api/v1/connector/mapper/ocrSúkromný pilot

Advanced: map a PDF or image with OCR

Potrebný scope: documents:send, firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Feature-gated OCR preview for an explicitly selected approved Mapping Spec v2 revision. External provider processing must be explicitly approved for the environment. The upload is size-bounded, MIME-sniffed and malware-scanned before one OCR extraction. OCR never stages or sends directly in this version: review the returned canonical draft and submit the confirmed document through the normal Connector flow. Uploading the binary again starts a new extraction. This endpoint does not alter the established /connector/mapper JSON contract.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentfileREQPDF, JPEG, PNG or WebP document, at most 20 MB.
templateKeystringREQOCR Mapper profile key. (max 120 znakov / chars)
revisionIduuidREQExact approved active Mapping Spec v2 revision.
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
executestringoptional (default: preview) (povolené: preview)
confirmedstringoptionalOCR requires a separate human review; direct confirmation is not accepted. (default: false) (povolené: false)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/mapper/ocr" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  --data-binary @request.bin

Odpovede

  • 200OCR mapping preview or idempotent execution result
  • 400Malformed multipart request
  • 401Unauthorized
  • 403Forbidden or insufficient scope
  • 404OCR feature, mapping profile or revision is unavailable
  • 411Content-Length is required so the multipart limit can be enforced before parsing
  • 413Multipart body or document exceeds the limit
  • 415Unsupported or spoofed document content
  • 422Unsafe, unextractable or invalid mapped document
  • 429OCR rate limit exceeded
  • 503Malware scanner, OCR provider or delivery dependency is unavailable
GET/api/v1/connector/connectionsSúkromný pilot

List Connector connections

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Lists tenant-isolated adapter bindings. Credentials and channel secrets are never returned.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
statusstring (query)optional (povolené: draft, testing, active, needs_attention, disabled)

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/connections" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Connection list.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 422Request rejected.
POST/api/v1/connector/connectionsSúkromný pilot

Create a Connector connection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Binds one approved company and Connector mailbox to a channel. Company identity comes only from customerRef during this authenticated setup; uploaded files and AI output cannot change it. New connections start in draft, staged delivery, and integrator-owned review. Managed Exceptions is not currently available.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
channelstringREQ (povolené: api, portal, email, sftp, bridge)
namestringREQmax 120 znakov / chars
directionstringoptional (default: outbound) (povolené: outbound, inbound, bidirectional)
outboundProfileIduuidoptional
inboundProfileIduuidoptional
reviewOwnerstringoptionalIntegrator review is the only writable ownership mode. Firm and ePostak queues are reserved for a future additive release. (default: integrator) (povolené: integrator)
managedExceptionsEnabledbooleanoptionalReserved compatibility field. Managed Exceptions is not currently available and true is rejected. (default: false) (povolené: false)
outboundDeliveryModestringoptional (default: stage) (povolené: stage, auto)
inboundDeliveryModestringoptional (default: stage) (povolené: stage, auto)
channelConfigobjectoptional
channelConfig.allowedSendersstring[]optionalExact sender allowlist for an email connection. Required before the connection test can pass. (max 50 položiek / items)
channelConfig.deliveryRecipientsstring[]optionalExact ERP mailbox recipients for inbound delivery over an email connection. Required before an inbound or bidirectional email connection can pass its test. (max 50 položiek / items)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "customerRef": "string",
  "name": "string",
  "channel": "api"
}'

Odpovede

  • 201Connection state.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
GET/api/v1/connector/connections/{connectionId}Súkromný pilot

Get a Connector connection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Connection state.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
PATCH/api/v1/connector/connections/{connectionId}Súkromný pilot

Update a Connector connection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Updates configuration additively. Any readiness-affecting change returns the connection to draft so it must be tested again. Review ownership can remain integrator-owned only; preserved historical non-integrator ownership cannot be changed through this API.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ
namestringoptionalmax 120 znakov / chars
directionstringoptional (default: outbound) (povolené: outbound, inbound, bidirectional)
outboundProfileIduuidoptional
inboundProfileIduuidoptional
reviewOwnerstringoptionalIntegrator review is the only writable ownership mode. Firm and ePostak queues are reserved for a future additive release. (default: integrator) (povolené: integrator)
managedExceptionsEnabledbooleanoptionalReserved compatibility field. Managed Exceptions is not currently available and true is rejected. (default: false) (povolené: false)
outboundDeliveryModestringoptional (default: stage) (povolené: stage, auto)
inboundDeliveryModestringoptional (default: stage) (povolené: stage, auto)
channelConfigobjectoptional
channelConfig.allowedSendersstring[]optionalExact sender allowlist for an email connection. Required before the connection test can pass. (max 50 položiek / items)
channelConfig.deliveryRecipientsstring[]optionalExact ERP mailbox recipients for inbound delivery over an email connection. Required before an inbound or bidirectional email connection can pass its test. (max 50 položiek / items)

Príklady volania

cURL
curl -X PATCH "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpovede

  • 200Connection state.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
POST/api/v1/connector/connections/{connectionId}/disableSúkromný pilot

Disable a Connector connection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Idempotently disables the binding and revokes its connection credential and Bridge device tokens.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/disable" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Connection state.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
POST/api/v1/connector/connections/{connectionId}/credentials/rotateSúkromný pilot

Rotate a connection credential

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Rotates an SFTP password or unguessable email intake address and returns the new value once. Rotation returns the connection to draft until it passes its channel test again.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/credentials/rotate" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Credential rotated.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 422Request rejected.
POST/api/v1/connector/connections/{connectionId}/testSúkromný pilot

Test a Connector connection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Checks the channel without sending a Peppol document. Transport and mapping readiness are returned separately so a working Bridge, SFTP, API, email or portal connection can start bounded sample collection before a mapping revision is active.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/test" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Connection test completed.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
POST/api/v1/connector/connections/{connectionId}/learning/startSúkromný pilot

Start bounded outbound sample collection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Starts or returns the active learning session for a transport-tested outbound connection with a bound mapping profile. While the session is collecting, every intake through this connection is forced to onboarding_sample and stage; no document can reach Autopilot or Peppol. The session accepts 3–10 unique samples and expires automatically.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ
durationMinutesintegeroptional15–1440 (default: 60)
sampleLimitintegeroptional3–10 (default: 10)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/learning/start" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpovede

  • 200The already active session was returned.
  • 201Sample collection started.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
POST/api/v1/connector/connections/{connectionId}/learning/stopSúkromný pilot

Stop outbound sample collection

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Closes the active learning session without deleting accepted samples. Later connection intakes return to the normal pinned-revision rules.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/learning/stop" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Sample collection stopped.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
GET/api/v1/connector/connections/{connectionId}/bridge-devicesSúkromný pilot

List Bridge devices

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Lists token-free device state for one Bridge connection.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/bridge-devices" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Bridge device list.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
POST/api/v1/connector/connections/{connectionId}/bridge-devicesSúkromný pilot

Create a Bridge pairing

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Creates one short-lived pairing code for the connection. Revoke the existing live device before replacing it.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ
namestringREQmax 120 znakov / chars
platformstringREQ (povolené: windows, macos)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/bridge-devices" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "platform": "windows"
}'

Odpovede

  • 201Pairing created; store or enter the code now.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
POST/api/v1/connector/connections/{connectionId}/bridge-devices/{deviceId}/revokeSúkromný pilot

Revoke a Bridge device

Potrebný scope: firms:manage

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Immediately revokes the device token while preserving its audit record.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
connectionIduuidREQ
deviceIduuidREQ

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/connections/<connectionId>/bridge-devices/<deviceId>/revoke" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Bridge device revoked.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
POST/api/v1/connector/documents/{documentId}/exportSúkromný pilot

Create a pinned ERP export

Potrebný scope: documents:read

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Creates an idempotent asynchronous export for an inbound Peppol invoice. The active inbound mapping revision and connection policy are pinned when the job is accepted. The endpoint is hidden unless the server-side inbound mapping capability is enabled for the approved DEV integrator.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.
Epostak-ConnectionuuidREQTrusted inbound or bidirectional connection that selects the company, mapping profile, and delivery policy.
Idempotency-KeystringREQmax 255 znakov / chars
Epostak-Customer-RefstringoptionalOptional compatibility assertion. When present, it must match the company bound to Epostak-Connection. (max 128 znakov / chars)

Parametre

NázovTypPovinnéPopis
documentIduuidREQInbound Peppol invoice ID.

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/documents/<documentId>/export" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 202Pinned ERP delivery state.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
  • 429Request rejected.
GET/api/v1/connector/deliveries/{deliveryJobId}Súkromný pilot

Get an ERP delivery

Potrebný scope: documents:read

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
deliveryJobIduuidREQ

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/deliveries/<deliveryJobId>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Pinned ERP delivery state.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 429Request rejected.
GET/api/v1/connector/deliveries/{deliveryJobId}/artifactSúkromný pilot

Download a generated ERP artifact

Potrebný scope: documents:read

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Returns the immutable artifact generated by the exact revision pinned on the delivery job. Its Content-Type and filename describe the configured ERP format.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
deliveryJobIduuidREQ

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/deliveries/<deliveryJobId>/artifact" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Immutable ERP artifact.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 429Request rejected.
POST/api/v1/connector/deliveries/{deliveryJobId}/acknowledgeSúkromný pilot

Acknowledge an ERP import

Potrebný scope: documents:write

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Records durable ERP acceptance. Identical retries are idempotent; a different reference conflicts. Acknowledged staged imports advance the probation counter of the pinned inbound profile revision.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
deliveryJobIduuidREQ
referencestringoptionalOptional stable reference of the ERP import operation. (max 255 znakov / chars)

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/deliveries/<deliveryJobId>/acknowledge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpovede

  • 200Pinned ERP delivery state.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
  • 429Request rejected.
POST/api/v1/connector/deliveries/{deliveryJobId}/releaseSúkromný pilot

Release a staged ERP delivery

Potrebný scope: documents:write

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Explicitly releases a reviewed staged artifact to the configured inbound ERP adapter. The pinned mapping revision and generated artifact remain unchanged. Identical retries after release are idempotent; expectedUpdatedAt prevents acting on a stale staged view.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
deliveryJobIduuidREQ
expectedUpdatedAtdatetimeREQThe updatedAt value returned when the staged delivery was reviewed.

Príklady volania

cURL
curl -X POST "https://dev.epostak.sk/api/v1/connector/deliveries/<deliveryJobId>/release" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedUpdatedAt": "2026-01-15T10:00:00Z"
}'

Odpovede

  • 200Pinned ERP delivery state.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 409Request rejected.
  • 413Request rejected.
  • 422Request rejected.
  • 429Request rejected.
GET/api/v1/connector/operations/eventsSúkromný pilot

List Connector operational events

Potrebný scope: documents:read

Private preview: available only in DEV to explicitly allowlisted integrators with the required server capability enabled. Other callers receive an opaque 404. Production availability requires a separate approved go-live. Feature-gated polling stream for connection, intake, mapping, review, and ERP-delivery lifecycle events. It has an independent exact cursor and does not change the released document event stream. Persist nextCursor only after committing the returned events locally.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
cursorstring (query)optionalOpaque cursor returned by this operational stream. Do not reuse a document-events cursor.
limitinteger (query)optional1–500 (default: 100)

Príklady volania

cURL
curl -X GET "https://dev.epostak.sk/api/v1/connector/operations/events?customerRef=<customerRef>" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Odpovede

  • 200Operational lifecycle page.
  • 400Request rejected.
  • 401Request rejected.
  • 403Request rejected.
  • 404Request rejected.
  • 422Request rejected.
  • 429Request rejected.
  • 503Request rejected.

Pokročilé (voliteľné)

Tu nájdete voliteľné PDF vizualizácie, vlastné mapovanie vstupu a technické balíky pre podporu či audit. Bežný send, príjem a polling ich nevyžaduje.

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

Stiahnuť PDF vizualizáciu faktúry

Potrebný scope: documents:read

Returns the invoice PDF shown in the portal for a document with stored UBL XML. An available stored PDF is returned first; otherwise ePošťák generates a PDF visualization. A generated PDF includes a payment QR code only when an IBAN and positive amount due are available. This is not the original Peppol XML.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer &lt;JWT&gt; získaný cez POST /api/v1/auth/token z integrátorského kľúča sk_int_*. Surový kľúč ako Bearer server odmietne s 401.

Parametre

NázovTypPovinnéPopis
documentIduuidREQ
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.

Príklady volania

cURL
curl "https://dev.epostak.sk/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/pdf?customerRef=erp-acme" -H "Authorization: Bearer eyJhbGc..." --output invoice.pdf

Odpovede

  • 200Invoice PDF
  • 401Unauthorized
  • 403Forbidden
  • 404Document or stored UBL XML not found
  • 429Rate limit exceeded. Wait until X-RateLimit-Reset (or the Retry-After header when present) and retry; reuse the same Idempotency-Key for a write.