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

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

Aký je rozdiel medzi SAPI a Enterprise API?

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

Koľko stojí API integrácia?

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

Ako získam prístup do sandbox prostredia?

Napíšte z pracovného e-mailu na integracie@epostak.sk a uveďte názov firmy a účel integrácie. ePošťák integrátora overí a operátor manuálne vytvorí sandbox prístup. Produkčný prístup je oddelený a vzniká až po go-live kontrole a podpísanej zmluve.

Podporuje ePošťák API Peppol sieť?

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

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

Áno. Enterprise API podporuje multi-firma prístup a white-label program umožní partnerovi vystupovať pod vlastnou značkou na infraštruktúre ePošťák. White-label má samostatný verejný cenník, API dokumenty a transakcie sa účtujú pay-per-use podľa používania.

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

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

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

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

ERP API · sandbox najprv

Connector API

Odporúčaný spravovaný API vstup pre ERP: odosielajte a prijímajte e-faktúry ako bežné údaje dokladu v JSON. ePošťák schváli prístup a Peppol firmy; vy si v dashboarde nastavíte customerRef. Elektronický formát aj doručenie rieši ePošťák.

SDK quickstart (6 jazykov)Connector OpenAPI JSON Sandbox prístup Získať token Odoslať doklad Čítať udalosti Zapnúť webhook

Začnite v sandboxe

ePošťák najprv manuálne schváli integrátora, sandbox a firmy vrátane ich Peppol registrácie. Vy si potom pre každú schválenú firmu nastavíte vlastné customerRef. Produkcia je oddelená.

1. Požiadajte o prístup

Napíšte na integracie@epostak.sk názov firmy, produkt alebo účel integrácie a meno aj e-mail technického kontaktu. ePošťák žiadosť preverí a sandbox pripraví manuálne; verejná registrácia nie je dostupná.

Základná URL sandboxu: https://dev.epostak.sk/api/v1
ePošťák vytvorí prístupové údaje a priradí iba schválené firmy; Connector nemá verejné API na vytvorenie alebo vyhľadanie zákazníka.

Požiadať o manuálne schválený sandbox

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

Nastaviť firmy

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

SDK quickstart Token request

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.

Odoslať prvý doklad

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.

Čítať udalosti Potvrdiť spracovanie Odoslať business odpoveď

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; každá podpísaná udalosť nesie customerRef konkrétnej firmy a rovnaký business tvar ako polling. GET /connector/events ponechajte ako spoľahlivý checkpoint a reconciliation tok.

HMAC-SHA256: X-Webhook-Timestamp + X-Webhook-Signature nad timestamp + '.' + raw body.
Secret sa zobrazí iba pri vytvorení alebo rotácii; uložte ho do secret managera.
Deduplikujte podľa X-Webhook-Event-Id a pri dočasnej chybe vráťte 503; 500 je terminálny výsledok bez retry.

Nastaviť webhook História doručení

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/token

Získať krátkodobý token

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.

Hlavičky

Názov	Typ	Povinné	Popis
Content-Type	string	REQ	application/json

Parametre

Názov	Typ	Povinné	Popis
grant_type	string	REQ	Pevná hodnota pre server-to-server prihlásenie. (default: `client_credentials`) (povolené: `client_credentials`)
client_id	string	REQ	ID prideleného integrátorského kľúča.
client_secret	string	REQ	Pridelený kompatibilný sk_int_* secret; držte ho iba na serveri.
scope	string	optional	Voliteľný medzerami oddelený podrozsah scope povolených pre kľúč. Ak ho vynecháte, token zdedí celý rozsah kľúča. Pre kompletný Connector lifecycle vrátane webhooku použite documents:send documents:read documents:write webhooks:read webhooks:write.

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":"YOUR_CLIENT_ID","client_secret":"sk_int_test_...","scope":"documents:send documents:read documents:write webhooks:read webhooks:write"}'

Príklady odpovedí

200 Použite access_token ako Bearer počas najviac 900 sekúnd.

{"access_token":"eyJhbGc...","token_type":"Bearer","expires_in":900,"scope":"documents:send documents:read documents:write firms:manage webhooks:read webhooks:write"}

Odpovede

200Použite access_token ako Bearer počas najviac 900 sekúnd.
401Neplatné alebo neaktívne pridelené credentials.

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.

Odoslať doklad Čítať doklady

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.

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é event položky s menšou latenciou, ale cursor 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

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 prijme doklad na asynchrónne odoslanie: state=queued bez send/cancel odkazov teda nie je staged doklad. delivery=stage doklad iba bezpečne uloží a 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. Ak pošlete oba, musia označovať ten istý príkaz.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.
Idempotency-Key	string	REQ	Stabilný retry kľúč. Rovnaký kľúč a payload nikdy neodošle doklad dvakrát.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	Vaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
externalId	string	REQ	Stabilné ID dokladu vo vašom ERP.
delivery	string	optional	send doklad odošle, stage ho iba bezpečne uloží. (default: `send`) (povolené: `send`, `stage`)
type	string	optional	Business typ dokladu. (default: `invoice`) (povolené: `invoice`, `credit_note`, `self_billing_invoice`, `self_billing_credit_note`)
number	string	REQ	Číslo dokladu.
precedingDocumentNumber	string	optional	Povinné číslo pôvodného dokladu pri dobropise.
recipient	object	REQ	Príjemca s country a aspoň jedným z companyId, taxId alebo vatId.
recipient.country	string	REQ	Dvojpísmenový kód krajiny.
recipient.companyId	string	optional	IČO alebo ekvivalent v danej krajine.
recipient.taxId	string	optional	DIČ alebo lokálne daňové ID.
recipient.vatId	string	optional	IČ DPH alebo VAT ID.
issueDate	date	optional	Dátum vystavenia YYYY-MM-DD.
dueDate	date	optional	Dátum splatnosti YYYY-MM-DD.
currency	string	optional	Trojpísmenový kód meny. (default: `EUR`)
lines	array	REQ	Aspoň jedna položka dokladu.
lines[].description	string	REQ	Popis položky.
lines[].quantity	number	REQ	Množstvo.
lines[].unitPrice	number	REQ	Jednotková cena bez DPH.
lines[].vatRate	number	REQ	Sadzba DPH v percentách.
lines[].taxTreatment	string	optional	Business daňový režim; technické kódy doplní ePošťák. (povolené: `standard`, `zero_rated`, `reverse_charge`, `exempt`, `intra_community_supply`, `export`, `out_of_scope`)

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","currency":"EUR","lines":[{"description":"Mesačná licencia","quantity":1,"unitPrice":100,"vatRate":23}]}'

Príklady odpovedí

201 Doklad bol prijatý do riadeného flow.

{"id":"8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111","customerRef":"erp-acme","externalId":"invoice-2026-0042","direction":"outbound","type":"invoice","number":"2026-0042","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-24a3f8a0c111?customerRef=erp-acme","evidence":"/api/v1/connector/documents/8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111/evidence?customerRef=erp-acme"}}

201 Staged doklad. Prítomnosť send a cancel odkazov je oprávnenie na ďalšiu akciu.

{"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 alebo RECIPIENT_AMBIGUOUS. Pri retryable=true počkajte podľa Retry-After; pri false opravte konfliktný príkaz alebo identifikátory príjemcu.

{"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 Neplatný doklad alebo nenájdený/nepodporovaný príjemca.

{"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 Rate limit. Počkajte počet sekúnd z hlavičky Retry-After a potom zopakujte rovnaký request s rovnakým Idempotency-Key.

{"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 Dočasne nedostupné overenie alebo doručenie; bezpečne opakujte rovnaký request.

{"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

200Bezpečný replay rovnakého dokladu; replayed=true a nový doklad sa nevytvorí.
201Doklad bol prijatý do riadeného flow.
201Staged doklad. Prítomnosť send a cancel odkazov je oprávnenie na ďalšiu akciu.
400Telo nie je platný JSON. Odpoveď používa rovnaký business error tvar a korelačné requestId.
401Chýbajúci, neplatný alebo expirovaný Connector access token.
409CUSTOMER_NOT_READY, IDEMPOTENCY_CONFLICT alebo RECIPIENT_AMBIGUOUS. Pri retryable=true počkajte podľa Retry-After; pri false opravte konfliktný príkaz alebo identifikátory príjemcu.
413Telo prekračuje limit. Odpoveď používa business kód DOCUMENT_INVALID a korelačné requestId.
422Neplatný doklad alebo nenájdený/nepodporovaný príjemca.
429Rate limit. Počkajte počet sekúnd z hlavičky Retry-After a potom zopakujte rovnaký request s rovnakým Idempotency-Key.
503Dočasne nedostupné overenie alebo doručenie; bezpečne opakujte rovnaký request.

GET/api/v1/connector/documents

Zoznam dokladov

Vráti business-only zoznam dokladov jednej schválenej firmy vrátane response=null alebo aktuálnej business odpovede. Consent floor a tenant scope sa aplikujú pred čítaním. Posledná stránka má nextCursor=null; dokumentový cursor nie je polling checkpoint.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	Vaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
direction	string	optional	Smer dokladu. (povolené: `inbound`, `outbound`)
state	string	optional	Business stav. (povolené: `queued`, `sending`, `delivered`, `received`, `processed`, `needs_attention`, `failed`, `cancelled`)
type	string	optional	Jeden zo štyroch verejných business typov dokladu. (povolené: `invoice`, `credit_note`, `self_billing_invoice`, `self_billing_credit_note`)
createdAfter	string	optional	Vráti doklady vytvorené po zadanom ISO 8601 date-time.
cursor	string	optional	Nepriehľadný cursor.
limit	integer	optional	1 až 100 dokladov. (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 Stránkovaný zoznam business dokladov.

{
  "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

200Stránkovaný zoznam business dokladov.

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

Detail business dokladu

Vráti stabilný business tvar a stav dokladu vrátane response=null alebo aktuálnej odoslanej/prijatej business odpovede. Technické údaje sú zámerne oddelené do pokročilých dôkazových a support-packet endpointov. Dokument je viditeľný iba po dátume súhlasu firmy s integrátorom.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID dokumentu z odpovede POST /connector/documents, zo zoznamu dokladov alebo z events.
customerRef	string (query)	REQ	Vaš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?customerRef=erp-acme" -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Business detail dokumentu.

{"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

200Business detail dokumentu.
404Nepriehľadné nenájdené: dokument nie je dostupný alebo customerRef chýba v SDK volaní, je prázdny, opakovaný či nezhodný.

POST/api/v1/connector/documents/{documentId}/send

Odoslať uložený doklad

Odošle doklad vytvorený s delivery=stage. Endpoint volajte iba vtedy, keď detail alebo create odpoveď obsahuje links.send. Request nemá telo. Opakované volanie je bezpečné: dokončené odoslanie vráti 200, prebiehajúce odoslanie 202 so state=sending, ktoré sledujete cez detail alebo events.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID staged dokumentu, ktorého links obsahuje send.
customerRef	string (query)	REQ	Vaš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 Odoslanie bolo prijaté alebo ide o bezpečné opakovanie dokončeného odoslania.

{"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 Odoslanie prebieha; odpoveď má state=sending a dokument môžete bezpečne pollovať.

{"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"}}

Odpovede

200Odoslanie bolo prijaté alebo ide o bezpečné opakovanie dokončeného odoslania.
202Odoslanie prebieha; odpoveď má state=sending a dokument môžete bezpečne pollovať.
409Customer momentálne nie je pripravený na odoslanie.
404Nepriehľadné nenájdené pre nedostupný dokument alebo neplatnú väzbu customerRef.
422Doklad nie je dostupný pre túto akciu; obnovte detail a použite iba ponúknuté links.
503Doručenie je dočasne nedostupné; obnovte detail a bezpečne opakujte send.

POST/api/v1/connector/documents/{documentId}/cancel

Zrušiť uložený doklad

Zruší staged doklad pred začiatkom odosielania. Endpoint volajte iba vtedy, keď detail alebo create odpoveď obsahuje links.cancel. Request nemá telo a opakované zrušenie je idempotentné.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID staged dokumentu, ktorého links obsahuje cancel.
customerRef	string (query)	REQ	Vaš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 Doklad bol zrušený alebo už bol zrušený skôr; odpoveď vracia canonical business dokument.

{"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

200Doklad bol zrušený alebo už bol zrušený skôr; odpoveď vracia canonical business dokument.
422Doklad už nie je možné zrušiť; obnovte detail a použite iba ponúknuté links.
404Nepriehľadné nenájdené pre nedostupný dokument alebo neplatnú väzbu customerRef.
503Zrušenie je dočasne nedostupné; obnovte detail pred ďalším pokusom.

POST/api/v1/connector/documents/{documentId}/acknowledge

Potvrdiť spracovanie

Idempotentne zaznamená, že ERP spracovalo prijatý doklad. Je to iba lokálny stav Connectora; neposiela odpoveď odosielateľovi ani nemení sieťový transportný stav.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID prijatého dokladu.
customerRef	string (query)	REQ	Vaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
reference	string	REQ	Referencia importu/spracovania vo vašom ERP.

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 Spracovanie bolo zaznamenané alebo už bolo zaznamenané skôr.

{"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 Telo prekračuje 64 KiB. Odpoveď používa business kód PAYLOAD_TOO_LARGE; pošlite iba krátku ERP referenciu.

{"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

200Spracovanie bolo zaznamenané alebo už bolo zaznamenané skôr.
404Nepriehľadné nenájdené pre nedostupný dokument alebo neplatnú väzbu customerRef.
413Telo prekračuje 64 KiB. Odpoveď používa business kód PAYLOAD_TOO_LARGE; pošlite iba krátku ERP referenciu.
422Doklad nie je prijatý inbound doklad alebo request je neplatný.

GET/api/v1/connector/events

Connector udalosti

Business-only udalosti jednej schválenej firmy, určené na pravidelné čítanie: document.queued, document.delivered, document.received, document.processed, document.needs_attention, document.failed a document.cancelled. customerRef je vždy v koreňovej úrovni udalosti a nové klienty routujú podľa neho; voliteľné data.customerRef zostáva iba ako deprecated compatibility alias. Cancelled je samostatný výsledok, nie failed. data.number a data.response sú vždy prítomné, ale môžu byť null. Neprázdna stránka vracia nextCursor aj pri hasMore=false — uložte ho ako polling checkpoint pre budúce eventy. Rovnakú event položku môže Connector voliteľne poslať aj webhookom. Payload neobsahuje transportné identifikátory, Peppol polia ani raw XML.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	Vaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
cursor	string	optional	Nepriehľadný cursor z predchádzajúcej odpovede `nextCursor`.
limit	integer	optional	Maximálny počet vrátených udalostí. (default: `100`)

Príklady volania

cURL

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

Príklady odpovedí

200 Connector udalosti stránkované cez cursor.

{"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

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

POST/api/v1/connector/documents/{documentId}/respond

Odoslať business odpoveď na faktúru

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ázov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
documentId	uuid	REQ	ID prijatej faktúry, na ktorú odpovedáte.
customerRef	string (query)	REQ	Vaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
status	string	REQ	Business stav, ktorý sa odošle protistrane. (povolené: `received`, `in_process`, `under_query`, `conditionally_accepted`, `rejected`, `accepted`, `paid`)
note	string	optional	Voliteľné vysvetlenie s dĺžkou najviac 500 znakov.

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 Odpoveď bola odoslaná alebo ide o bezpečný replay rovnakého stavu.

{"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 Business odpoveď je bezpečne prijatá a čaká v doručovacej fronte.

{"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

200Odpoveď bola odoslaná alebo ide o bezpečný replay rovnakého stavu.
202Business odpoveď je bezpečne prijatá a čaká v doručovacej fronte.
404Prijatý dokument nie je dostupný pre dané customerRef.
409Schválená firma alebo jej Connector mailbox momentálne nie je pripravený.
413Telo prekračuje 32 KiB; pošlite iba status a krátku voliteľnú note.
422Neplatný stav, príliš dlhá note, neznáme pole alebo pokus zmeniť už finálnu odpoveď.
503Doručenie odpovede je dočasne nedostupné; zopakujte rovnaký request neskôr.

GET/api/v1/connector/webhook

Načítať Connector webhook

Natívny Connector webhook je jeden pre celý integrátorský účet a pushuje rovnakú business event položku ako GET /connector/events. customerRef v koreňovej úrovni určí schválenú firmu; voliteľné data.customerRef je iba deprecated compatibility alias a payload neobsahuje Peppol ani transportné polia. Connector ho podpisuje cez HMAC-SHA256 v X-Webhook-Timestamp a X-Webhook-Signature nad timestamp + '.' + raw body. Deduplikujte podľa stabilného X-Webhook-Event-Id a 2xx vráťte až po bezpečnom prijatí. Pri dočasnej chybe vráťte 503: sieťové chyby a 408, 425, 429, 502, 503, 504 doručujeme najviac 10 pokusmi (1 prvotný + 9 opakovaní); 500 je terminálny. Polling ponechajte ako spoľahlivý checkpoint a reconciliation tok.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Príklady volania

cURL

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

Príklady odpovedí

200 Vráti webhook=null, ak ešte nie je nastavený, inak bezpečný konfiguračný pohľad bez secretu.

{"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

200Vráti webhook=null, ak ešte nie je nastavený, inak bezpečný konfiguračný pohľad bez secretu.
401Neautorizované.
403Prístup zamietnutý.

PUT/api/v1/connector/webhook

Vytvoriť alebo aktualizovať webhook

Idempotentne nastaví jediný webhook integrátora. url musí byť verejný HTTPS endpoint a celé JSON telo môže mať najviac 32 KB. Voliteľné events vyberá z presne siedmich Connector business udalostí; ak ho vynecháte, odoberáte všetkých sedem. Pri vytvorení sa secret zobrazí práve raz. Aktualizácia ho nemení — na zmenu použite rotate-secret.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
url	string (HTTPS URL)	REQ	Verejná HTTPS URL webhook receivera.
events	string[]	optional	Voliteľný filter. Vynechanie znamená všetkých sedem business udalostí. (povolené: `document.queued`, `document.delivered`, `document.received`, `document.processed`, `document.needs_attention`, `document.failed`, `document.cancelled`)

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"]}'

Príklady odpovedí

200 Existujúca konfigurácia bola aktualizovaná a pôvodný secret zostal platný.

{"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 bol vytvorený. secret uložte teraz; neskôr ho už nie je možné zobraziť.

{"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

200Existujúca konfigurácia bola aktualizovaná a pôvodný secret zostal platný.
201Webhook bol vytvorený. secret uložte teraz; neskôr ho už nie je možné zobraziť.
400Neplatné JSON telo.
401Neautorizované.
403Prístup zamietnutý.
413Telo presiahlo 32 KB.
422Neplatná URL alebo event filter.

DELETE/api/v1/connector/webhook

Odstrániť Connector webhook

Odstráni webhook integrátora a zastaví nové push doručenia. GET /connector/events naďalej funguje a zostáva cestou na reconciliation.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Príklady volania

cURL

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

Odpovede

204Webhook bol odstránený.
401Neautorizované.
403Prístup zamietnutý.

POST/api/v1/connector/webhook/rotate-secret

Otočiť podpisový secret

Nahradí HMAC signing secret webhooku. Nový secret sa zobrazí práve raz; po úspešnej rotácii ním overujte ďalšie doručenia.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

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 Nový secret zobrazený raz.

{"secret":"7c4a8d09ca3762af61e59520943dc26494f8941b7a8331369f7f16f2e19f6c21"}

Odpovede

200Nový secret zobrazený raz.
401Neautorizované.
404Webhook ešte nie je nastavený.

POST/api/v1/connector/webhook/test

Otestovať Connector webhook

Zaradí podpísané testovacie doručenie pre jednu schválenú firmu. customerRef určí firmu a test event má rovnaký business tvar ako produkčné udalosti, navyše test=true.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
customerRef	string	REQ	Vaš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/webhook/test" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"customerRef":"erp-acme"}'

Príklady odpovedí

202 Test bol zaradený.

{"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 bol zaradený.
401Neautorizované.
404Webhook alebo customerRef nie je dostupné.

GET/api/v1/connector/webhook/deliveries

História webhook doručení

Vráti cursor-paged históriu doručení naprieč customerRef hodnotami integrátora. Slúži na diagnostiku pushu; GET /connector/events používajte na business reconciliation.

Hlavičky

Názov	Typ	Povinné	Popis
Authorization	string	REQ	Bearer JWT získaný z integrátorského sk_int_* kľúča cez POST /api/v1/auth/token. Connector endpointy sú na úrovni integrátora; cieľovú schválenú firmu určujete cez customerRef, ktoré ste si nastavili v Integrátorskom portáli.

Parametre

Názov	Typ	Povinné	Popis
cursor	string	optional	Nepriehľadný cursor.
limit	integer	optional	Počet doručení na stránku. (default: `50`)
status	string	optional	Voliteľný filter stavu doručenia. (povolené: `PENDING`, `SUCCESS`, `FAILED`, `RETRYING`)

Príklady volania

cURL

curl "https://dev.epostak.sk/api/v1/connector/webhook/deliveries?limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Príklady odpovedí

200 Stránka webhook doručení.

{"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

200Stránka webhook doručení.
401Neautorizované.
403Prístup zamietnutý.

Pokročilé (voliteľné)

Otvorte až vtedy, keď potrebujete vlastné mapovanie vstupu alebo technický balík pre support či audit. Bežný send, príjem a polling ich nevyžaduje.

Pokročilé nástroje

Mapper a dôkazové operácie zostávajú v plnej Enterprise referencii.

Mapper Support packet Enterprise referencia Enterprise OpenAPI — pokročilý spoločný kontrakt