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ú viditeľná voliteľná cesta v Connector Studiu.

  1. Otestovať export v Connector StudiuMapovanie, 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":"YOUR_CLIENT_ID","client_secret":"sk_int_test_...","scope":"documents:send documents:read documents:write webhooks:read webhooks:write"}'

Prihlásenie

NázovTypPovinnéPopis
grant_typestringánoPevná hodnota pre server-to-server prihlásenie.
client_idstringánoID prideleného integrátorského kľúča.
client_secretstringánoPridelený kompatibilný sk_int_* secret; držte ho iba na serveri.
scopestringnieVoliteľ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.

Ď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 doklad zaradí na odoslanie; delivery=stage ho uloží na neskoršie uvoľnenie.

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ť

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  "variableSymbol": "20260042",
18  "buyerReference": "OBJ-1042",
19  "lines": [{
20    "description": "Mesačná licencia",
21    "quantity": 1,
22    "unit": "C62",
23    "unitPrice": 100,
24    "vatRate": 23,
25    "taxTreatment": "standard",
26    "discount": 5
27  }],
28  "prepayments": [{ "amountWithVat": 20, "vatRate": 23, "settlementDate": "2026-07-10" }],
29  "attachments": [{ "fileName": "objednavka.pdf", "mimeType": "application/pdf", "content": "JVBERi0xLjQ..." }]
30}

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.
recipientobjectánocountry a aspoň jedno správne business ID.
lines[]arrayánoAspoň jedna položka.

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ť export v Connector Studiu

Ak ERP ešte nevie vytvoriť kanonický Connector JSON, vložte vlastný JSON alebo CSV export do Studia. 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 Connector Studio z panelu alebo týmto odkazom.
  2. 02Vložte 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ť

Vstup do Studia

curl
1# UI: /integrator/connector?tool=studio#connector-studio
2# 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

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 info@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 quickstartToken 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ť udalostiPotvrdiť spracovanieOdoslať 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ť webhookHistó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ázovTypPovinnéPopis
Content-TypestringREQapplication/json

Parametre

NázovTypPovinnéPopis
grant_typestringREQPevná hodnota pre server-to-server prihlásenie. (default: client_credentials) (povolené: client_credentials)
client_idstringREQID prideleného integrátorského kľúča.
client_secretstringREQPridelený kompatibilný sk_int_* secret; držte ho iba na serveri.
scopestringoptionalVoliteľ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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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-KeystringREQStabilný retry kľúč. Rovnaký kľúč a payload nikdy neodošle doklad dvakrát.

Parametre

NázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
externalIdstringREQStabilné ID dokladu vo vašom ERP.
deliverystringoptionalsend doklad odošle, stage ho iba bezpečne uloží. (default: send) (povolené: send, stage)
typestringoptionalBusiness typ dokladu. (default: invoice) (povolené: invoice, credit_note, self_billing_invoice, self_billing_credit_note)
numberstringREQČíslo dokladu.
precedingDocumentNumberstringoptionalPovinné číslo pôvodného dokladu pri dobropise.
recipientobjectREQPríjemca s country a aspoň jedným z companyId, taxId alebo vatId.
recipient.countrystringREQDvojpísmenový kód krajiny.
recipient.namestringoptionalObchodné meno príjemcu. Connector ho overí alebo doplní podľa identity firmy.
recipient.companyIdstringoptionalIČO alebo ekvivalent v danej krajine.
recipient.taxIdstringoptionalDIČ alebo lokálne daňové ID.
recipient.vatIdstringoptionalIČ DPH alebo VAT ID.
recipient.networkIdstringoptionalVoliteľná presná sieťová identita, ak ju ERP už pozná. Bežný Connector tok ju nepotrebuje; preferujte firemné alebo daňové ID.
recipient.addressobjectoptionalVoliteľná adresa príjemcu, používaná pri tvorbe dokladu a kontrole identity.
recipient.address.streetstringoptionalUlica a číslo.
recipient.address.citystringoptionalMesto alebo obec.
recipient.address.postalCodestringoptionalPSČ, najviac 32 znakov.
issueDatedateoptionalDátum vystavenia YYYY-MM-DD. Pri odovzdaní na odoslanie sa musí zhodovať s aktuálnym dňom v časovej zóne Europe/Bratislava.
dueDatedateoptionalDátum splatnosti YYYY-MM-DD.
taxPointDatedateoptionalDátum vzniku daňovej povinnosti (Peppol BT-7) vo formáte YYYY-MM-DD.
deliveryDatedateoptionalSkutočný dátum dodania celého dokladu (Peppol BT-72) vo formáte YYYY-MM-DD.
documentDiscountPercentnumberoptionalCelková zľava dokladu v percentách od 0 do 100. Prenáša sa ako Peppol dokumentová zľava BG-20 a kombinuje sa s prípadnými riadkovými zľavami.
currencystringoptionalTrojpísmenový kód meny. (default: EUR)
notestringoptionalPoznámka na doklade, najviac 5 000 znakov.
ibanstringoptionalIBAN pre úhradu.
paymentMethodstringoptionalBusiness spôsob úhrady z ERP.
variableSymbolstringoptionalVariabilný symbol platby.
buyerReferencestringoptionalReferencia kupujúceho, napríklad číslo objednávky alebo zákazky. Parser ju pri stage prijme ako voliteľnú, ale pri odoslaní faktúry ju uveďte; bez nej doklad neprejde Peppol validáciou.
prepaidAmountnumberoptionalUž uhradená suma vrátane DPH, minimálne 0.
linesarrayREQAspoň jedna položka dokladu.
lines[].descriptionstringREQPopis položky.
lines[].quantitynumberREQKladné množstvo pre štandardný riadok; záporné pre lineType=advance_deduction. Nula nie je povolená.
lines[].unitstringoptionalKód mernej jednotky, napríklad C62.
lines[].unitPricenumberREQJednotková cena bez DPH.
lines[].vatRatenumberREQSadzba DPH v percentách.
lines[].taxTreatmentstringoptionalBusiness daňový režim; technické kódy doplní ePošťák. (povolené: standard, zero_rated, reverse_charge, exempt, intra_community_supply, export, out_of_scope)
lines[].discountnumberoptionalZľava položky v percentách od 0 do 100.
lines[].deliveryDatedateoptionalDátum dodania položky vo formáte YYYY-MM-DD.
lines[].lineTypestringoptionalTyp položky. advance_deduction vyžaduje záporné množstvo a advanceInvoiceReference. (povolené: standard, advance_deduction)
lines[].advanceInvoiceReferencestringoptionalReferencia zálohovej faktúry pre odpočtovú položku.
lines[].customsTariffCodestringoptionalColný sadzobník položky.
lines[].commodityClassificationCodestringoptionalKód klasifikácie tovaru alebo služby.
lines[].commodityClassificationListIdstringoptionalIdentifikátor použitého klasifikačného zoznamu.
lines[].reverseChargeParagraphLetterstringoptionalPísmeno paragrafu pri prenose daňovej povinnosti.
lines[].controlStatementTypestringoptionalTyp položky kontrolného výkazu.
lines[].controlStatementQuantitynumberoptionalMnožstvo pre kontrolný výkaz, minimálne 0.
lines[].controlStatementUnitstringoptionalMerná jednotka pre kontrolný výkaz.
prepaymentsarrayoptionalŠtruktúrované uhradené preddavky; 1 až 100 položiek.
prepayments[].advanceInvoiceRefstringoptionalReferencia zálohovej faktúry.
prepayments[].taxDocumentRefstringoptionalReferencia daňového dokladu k prijatej platbe.
prepayments[].settlementDatedateoptionalDátum úhrady vo formáte YYYY-MM-DD.
prepayments[].amountWithoutVatnumberoptionalUhradená suma bez DPH, minimálne 0.
prepayments[].vatAmountnumberoptionalSuma DPH preddavku, minimálne 0.
prepayments[].amountWithVatnumberREQUhradená suma vrátane DPH, minimálne 0.
prepayments[].vatRatenumberoptionalSadzba DPH preddavku od 0 do 100.
prepayments[].taxTreatmentstringoptionalBusiness daňový režim preddavku. (povolené: standard, zero_rated, reverse_charge, exempt, intra_community_supply, export, out_of_scope)
attachmentsarrayoptionalNajviac 20 príloh dokladu.
attachments[].fileNamestringREQNázov súboru vrátane prípony.
attachments[].mimeTypestringREQMIME typ súboru, napríklad application/pdf.
attachments[].contentbase64 stringREQObsah súboru zakódovaný v base64.
attachments[].descriptionstringoptionalVoliteľný popis prílohy, najviac 1 000 znakov.

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","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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
directionstringoptionalSmer dokladu. (povolené: inbound, outbound)
statestringoptionalBusiness stav. (povolené: queued, sending, delivered, received, processed, needs_attention, failed, cancelled)
typestringoptionalJeden zo štyroch verejných business typov dokladu. (povolené: invoice, credit_note, self_billing_invoice, self_billing_credit_note)
createdAfterstringoptionalVráti doklady vytvorené po zadanom ISO 8601 date-time.
cursorstringoptionalNepriehľadný cursor.
limitintegeroptional1 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID dokumentu z odpovede POST /connector/documents, zo zoznamu dokladov alebo z 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 "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 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID staged dokumentu, ktorého links obsahuje send.
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 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID staged dokumentu, ktorého links obsahuje cancel.
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 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID prijatého dokladu.
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
referencestringREQReferencia 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
cursorstringoptionalNepriehľadný cursor z predchádzajúcej odpovede `nextCursor`.
limitintegeroptionalMaximálny počet vrátených udalostí. (default: 100)

Príklady volania

cURL
curl "https://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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
documentIduuidREQID prijatej faktúry, na ktorú odpovedáte.
customerRefstring (query)REQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
statusstringREQBusiness stav, ktorý sa odošle protistrane. (povolené: received, in_process, under_query, conditionally_accepted, rejected, accepted, paid)
notestringoptionalVoliteľ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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
urlstring (HTTPS URL)REQVerejná HTTPS URL webhook receivera.
eventsstring[]optionalVoliteľ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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
customerRefstringREQVaš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. Filtrovať môžete presnú firmu, udalosť, stav, testovacie dáta a najviac 90-dňový interval. Detail doručenia ukáže presné podpísané body, každý pokus, príčinu a bezpečný replay. GET /connector/events zostáva business reconciliation checkpoint.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer 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ázovTypPovinnéPopis
cursorstringoptionalNepriehľadný cursor.
limitintegeroptionalPočet doručení na stránku. (default: 50)
statusstringoptionalVoliteľný filter stavu doručenia. (povolené: PENDING, SUCCESS, FAILED, RETRYING)
customerRefstringREQVaše stabilné customerRef nastavené pre schválenú firmu; v kanonickom Connector toku ho pošlite presne raz.
typestringoptionalTyp business udalosti.
testbooleanoptionaltrue iba testy, false iba reálne dáta.
from / todate-timeoptionalISO-8601 interval najviac 90 dní.

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 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ý.
GET/api/v1/connector/webhook/deliveries/{deliveryId}

Detail doručenia udalosti

Vráti presné podpísané body, bezpečnú adresu endpointu, zrozumiteľnú príčinu a každý skutočný pokus. Staršia história otvorene uvedie, že podrobné pokusy nemá; nič sa spätne nevymýšľa.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token> · scope webhooks:read

Parametre

NázovTypPovinnéPopis
deliveryIduuidREQID doručenia zo zoznamu.

Príklady volania

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

Odpovede

  • 200Dôkazy a časová os doručenia.
  • 404Udalosť neexistuje alebo už k jej firme nemáte aktuálny prístup.
POST/api/v1/connector/webhook/deliveries/{deliveryId}/replay

Zopakovať presné doručenie

Po oprave endpointu vytvorí nové doručenie s novým delivery ID a podpisom, ale zachová pôvodné event ID, customerRef aj presné body. Prijímač preto musí deduplikovať podľa event ID. Úspešné reálne doručenie vyžaduje confirmSuccessfulReplay=true.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token> · scope webhooks:write
Idempotency-KeystringREQNový stabilný kľúč jedného zámerného replay kliknutia.

Parametre

NázovTypPovinnéPopis
deliveryIduuidREQTerminálne doručenie.
confirmSuccessfulReplaybooleanoptionalPovinné true iba pri úspešnom reálnom doručení. (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

  • 202Replay je bezpečne uložený; prípadný výpadok fronty sa obnoví automaticky.
  • 200Rovnaký idempotentný replay už bol prijatý.
  • 409Zdroj ešte nie je terminálny, replay už prebieha alebo sa kľúč použil inak.
POST/api/v1/connector/webhook/test-suite

Spustiť sedem testov prijímača

Overí úspech, stabilné event ID a body pri replayi, 503, 429/Retry-After, terminálnu 422, timeout a prijatie podpísanej požiadavky cez rovnaký produkčný doručovací kód. Internú deduplikáciu ani samotný výpočet HMAC vo vašom endpoint handleri ePošťák nevidí. Test používa tri pokusy v čase 0, 5 a 30 sekúnd a nemení produkčný circuit breaker.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token> · scope webhooks:write
Idempotency-KeystringREQStable diagnostic-run key.

Parametre

NázovTypPovinnéPopis
customerRefstringREQSchválená firma, na ktorej sa overí aktuálny prístup.
eventstringoptionalObchodný typ testovacej udalosti. (default: document.queued)
scenariosarrayoptionalVoliteľný výber; bez poľa sa spustí všetkých sedem.

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

  • 202Diagnostika bola prijatá.
  • 409Iný test ešte prebieha alebo sa kľúč použil s iným telom.
  • 429Najviac päť nových diagnostík za hodinu.
GET/api/v1/connector/webhook/test-suite/{testRunId}

Sledovať diagnostický test

Vráti výsledok každého scenára. Deduplikačný test sa po prvom úspechu zastaví a vyžiada replay dodaného deliveryId s rovnakým event ID.

Hlavičky

NázovTypPovinnéPopis
AuthorizationstringREQBearer <access_token> · scope webhooks:read

Parametre

NázovTypPovinnéPopis
testRunIduuidREQID prijaté pri štarte.

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

  • 200RUNNING, ACTION_REQUIRED, COMPLETED alebo EXPIRED.

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.