Č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. V produkcii platíte len za skutočne spracované dokumenty podľa objemových cien — od €0,06 za dokument pri vyšších objemoch. Žiadny fixný mesačný poplatok.

Ako získam prístup do sandbox prostredia?

Kontaktujte nás na info@epostak.sk alebo cez kontaktný formulár. Sandbox prostredie s plným prístupom k API vytvoríme do 24 hodín. Testovacie API kľúče a OAuth credentials dostanete ihneď.

Podporuje ePošťák API Peppol sieť?

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

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

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

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

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

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

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

Peppol Certified Access Point

Enterprise API

Začnite integrovať hneď. Od vás potrebujeme len JSON, UBL XML alebo PDF/sken — naše OCR z neho vyextrahuje Peppol BIS 3.0 faktúru. Všetko okolo Peppolu — generovanie UBL, validácia, podpis, doručenie cez AS4 a MLR — riešime my. Vy sa sústredíte na svoj produkt, my doručíme faktúru na druhom konci. Enterprise API je pre ERP výrobcov, účtovné platformy a integrátorov spravujúcich viacero firiem z jedného účtu; SDK je dostupné v 6 jazykoch (TypeScript, Python, PHP, Java, C#, Ruby).

15-minútový ERP Test Lab Onboarding klienta Demo testovacie účty SDK na GitHube (6 jazykov)Autentifikácia Odoslať prvú faktúru

Demo testovacie účty

Tieto demo účty sú zdieľané medzi všetkými integrátormi. Použite client_id + client_secret na získanie JWT cez POST /api/v1/auth/token. Pri volaniach cez integrátorský kľúč (sk_int_*) priložte HTTP hlavičku X-Firm-Id, ktorej hodnotou je Firm UUID cieľovej firmy (uvedený v karte Test Odosielateľ alebo Test Prijímateľ nižšie).

Test Odosielateľ (Participant 1)

0245:0000000001

client_id

487d008a-b3a5-49d0-be3e-ba45cc9c4ffe

client_secret

sk_live_••••••••••••••••1eac

X-Firm-Id

f2cea3cf-f29e-4ea2-9e76-b06a312ec9ab

Test Prijímateľ (Participant 2)

0245:0000000002

client_id

b6649c59-2f9d-4ae2-a750-af257c455478

client_secret

sk_live_••••••••••••••••6733

X-Firm-Id

b1022d80-5016-4dad-a8d2-53685cab1701

Demo Integrátor (ERP)

integrátor

client_id

8924a11d-a93c-4d5a-b54b-1f1ff246152c

client_secret

sk_int_t••••••••••••••••c282

Integrátorský kľúč je naviazaný na obe demo participantské firmy vyššie. Cieľovú firmu určujete v každom volaní pomocou HTTP hlavičky X-Firm-Id, kam doplníte Firm UUID — buď f2cea3cf-f29e-4ea2-9e76-b06a312ec9ab (Test Odosielateľ, 0245:0000000001) alebo b1022d80-5016-4dad-a8d2-53685cab1701 (Test Prijímateľ, 0245:0000000002).

Onboarding klienta

Pre koho je Enterprise API a ako napojíte prvého klienta — od jeho registrácie u Finančnej správy, cez OAuth consent, až po prvú faktúru. Detailné endpointy, scopes a webhook signature sú nižšie v sekciách Authentication, Endpoints a Webhooks.

Časový rámec. Voľba digitálneho poštára na portáli Finančnej správy SR sa plánuje spustiť koncom mája 2026, kedy začína obdobie dobrovoľnej elektronickej fakturácie. Od 1. januára 2027 je elektronická fakturácia povinná pre všetkých platiteľov DPH na Slovensku.

Krok 1: Klient si zvolí ePoštáka. Váš klient sa prihlási na portál Finančnej správy SR a v zozname certifikovaných poskytovateľov doručovacej služby si zvolí ePoštáka (Kaja Solutions s.r.o.). Následne si u nás vytvorí konto. My ho automaticky zaregistrujeme do centrálneho SMP a vytvoríme mu Peppol ID v tvare 0245:DIČ. Týmto sa stáva viditeľným v celej európskej Peppol sieti. Detailne sme to opísali v článku Ako si zvoliť digitálneho poštára.

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

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

Pred produkciou si všetko overte na našich zdieľaných sandbox účtoch (sekcia Demo testovacie účty vyššie). Pre produkčné kľúče je potrebná podpísaná zmluva — napíšte na info@epostak.sk. Krok-za-krokom sprievodca aj s code snippetmi je v článku Ako integrovať digitálneho poštára do vášho ERP.

Autentifikácia

OAuth 2.0 client_credentials — vymeňte API kľúč za krátkodobý JWT. API kľúče (sk_live_* / sk_int_*) nie sú priamo použiteľné ako bearer. Slúžia ako client_secret v POST /api/v1/auth/token, ktorý vráti JWT (eyJ...). JWT používate ako Authorization: Bearer na všetkých Enterprise aj SAPI routách.

Životnosť tokenov. POST /api/v1/auth/token vráti dva tokeny: access_token (JWT, RS256) s platnosťou 15 minút (expires_in: 900) a refresh_token (rt_…) s platnosťou 30 dní. Refresh token rotujete cez POST /api/v1/auth/renew — server vám vráti novú dvojicu, starý refresh sa okamžite invaliduje (one-shot, replay → 401).

Cachovanie tokenu. Nikdy nevolajte /auth/token pred každým API requestom — minete rate-limit (200/min) a zaťažíte si latenciu o ~100 ms na každú operáciu. Cachujte access_token v pamäti (alebo v zdieľanom Redis-e pri viacerých workeroch) a používajte ho do expirácie. Refreshujte buď proaktívne ~1 minútu pred uplynutím expires_in, alebo reaktívne pri prvej 401 odpovedi (skúste raz získať nový token a request zopakovať). Pri rotácii sa SDK štandardne stará o cache automaticky; pri vlastnej implementácii pamätajte, že refresh_token je one-shot.

Zneplatnenie. Token môžete kedykoľvek zneplatniť cez POST /api/v1/auth/revoke — pri access tokene sa jeho jti pridá do Redis blocklistu na zvyšok jeho TTL, pri refresh tokene sa zmaže server-side stav. Endpoint je idempotentný (vždy 200). Pri rotácii kľúča (POST /auth/rotate-secret) sa všetky aktívne tokeny okamžite zneplatnia.

GET/api/v1/auth/status

Introspekcia kľúča

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

Odpovede

200OK
401Unauthorized
403Forbidden / insufficient scope
404Not Found

POST/api/v1/auth/rotate-secret

Rotovať API kľúč

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

Odpovede

200OK
401Unauthorized
403Forbidden
404Not Found

GET/api/v1/account

Info o konte

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

Odpovede

200OK
400Bad Request
401Unauthorized
404Not Found

GET/api/v1/audit

Audit log firmy

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

Parametre

Názov	Typ	Povinné	Popis
limit	integer	optional	1–100, default 20.
event	string	optional	Presná zhoda názvu eventu (napr. `jwt.issued`, `webhook.created`).
actor_type	string	optional	Jeden z: `user`, `apiKey`, `integratorKey`, `system`.
since	string	optional	ISO 8601 timestamp dolnej hranice (inkluzívne).
until	string	optional	ISO 8601 timestamp hornej hranice (exkluzívne).
cursor	string	optional	Opaque cursor z predošlej odpovede (`next_cursor`).

Odpovede

200OK
401Neplatný alebo chýbajúci token.
403Plán nepovoľuje tento endpoint. Vyžaduje `audit:read` scope a API prístup (`api-enterprise` priamo alebo `integrator-managed` cez spravujúceho integrátora).

POST/api/internal/integrator/oauth/clients

Registrovať OAuth klienta

Registrácia nového OAuth klienta pre integrátora. Vráti client_id a client_secret. Auth: integrátorský JWT (sk_int_* kľúč).

Parametre

Názov	Typ	Povinné	Popis
name	string	REQ	Názov OAuth klienta
redirect_uris	string[]	REQ	Povolené redirect URI (HTTPS alebo localhost)
logo_url	string	optional	URL loga zobrazené na consent obrazovke

Odpovede

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

GET/oauth/authorize

Autorizačná URL

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

Parametre

Názov	Typ	Povinné	Popis
client_id	string	REQ	ID vášho OAuth klienta
redirect_uri	string	REQ	Registrovaná callback URL
response_type	string	REQ	code (povolené: `code`)
scope	string	optional	firms:manage documents:send documents:read — ak je prázdne, použije sa celý rozsah klienta
state	string	optional	odporúčané pre CSRF ochranu — náhodný reťazec
code_challenge	string	REQ	PKCE code challenge (SHA-256) (43–128 znakov)
code_challenge_method	string	REQ	S256 (povolené: `S256`)

Odpovede

302Redirect
400Bad Request

POST/api/oauth/token

Výmena kódu za kľúč

Vymení autorizačný kód za nový sk_int_* client_secret a metadata firmy. Content-Type: application/x-www-form-urlencoded (odporúčané podľa RFC 6749) alebo application/json.

Parametre

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

Odpovede

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

Dokumenty

Odosielanie a príjem faktúr, sledovanie stavu, sťahovanie evidencie/PDF/UBL, OCR extrakcia, validácia a konverzia formátov.

Tri integračné cesty — vyberte podľa potrieb. ePošťák ponúka tri rovnocenné spôsoby, ako konzumovať udalosti a dokumenty. Nemusíte si vybrať jeden — väčšina integrátorov používa kombináciu.

1. Webhooky (POST /api/v1/webhooks + push doručenia) — najnižšia latencia, server-to-server push. Vyžaduje, aby ste mali verejný HTTPS endpoint s HMAC verifikáciou. Vhodné, ak máte ops/IT schopnosť hostovať webhook receiver. HMAC-SHA256 podpis, SSRF guard, encrypted secret-at-rest, auto-disable po 20 terminálnych zlyhaniach, status-code-aware retry (~44h okno pre retryable kódy). Zachované ako mature feature pre súčasných klientov.

2. Webhook queue (GET /api/v1/webhook-queue + ack) — pull-alternatíva k webhookom pre klientov, ktorí <em>nemôžu</em> hostovať receiver. Server nesie stav cez acknowledged=false/true — pollujete, čo nie je ack-nuté, urobíte ack a riadok zmizne z fronty. Server-side state management = klient nemusí trackovať cursor. Cross-firm variant /api/v1/webhook-queue/all pre integrátorov.

3. Inbound / Outbound pull API (GET /api/v1/inbound/documents, GET /api/v1/outbound/documents) — plný dokumentačný prístup. Cursor-based stránkovanie s replay-safe semantikou, list + detail + surový UBL XML, polymorphic naprieč celým Peppol scope-om (Invoice, CreditNote, Order, DespatchAdvice, Catalogue, …). Vhodné, ak potrebujete dokumenty (nie len signály), kompletné historické čítanie, alebo pokrytie non-billing doctypes mimo billing endpointov /documents/inbox a /documents/outbox.

Plus: lifecycle eventy (GET /api/v1/outbound/events) — cursor-based stream interných document_events. Granulárnejší pohľad ako webhook queue (per-attempt resolution, transport vs application layer rozlíšenie). Aktuálne pokrýva billing-backed outbound; non-billing je v roadmape.

Decision matrix:<ul><li>Mám HTTPS endpoint a chcem push → Webhooky</li><li>Nemám HTTPS endpoint a chcem len eventy → Webhook queue</li><li>Chcem dokumenty (nie len signály) → Inbound/Outbound pull API</li><li>Robím audit/dashboard a chcem detailný lifecycle → Outbound events</li></ul>Plan-eligibility: všetky firemné API endpointy fungujú pre api-enterprise priamo alebo pre integrator-managed firmu cez spravujúci integrátorský token.

POST/api/v1/documents/send

Odoslať dokument

Odosle dokument cez Peppol siet. Podporuje JSON mode a raw UBL XML mode. Pre odoslaním overíme cez SMP, či je príjemca v Peppol sieti. Ak nie, vrátime 422 a nič sa nefakturuje. Voliteľná hlavička Idempotency-Key (alebo X-Idempotency-Key) — prvé volanie sa uloží, opakovanie s rovnakým telom vráti cache (200/201), kolízia v priebehu vráti 409. Ak sa SHA-256 hash tela líši od uloženého, vráti 422 IDEMPOTENCY_KEY_MISMATCH (telo je pred hashovaním kanonizované — kľúče zoradené rekurzívne).

Parametre

Názov	Typ	Povinné	Popis
receiverPeppolId	string	REQ	Peppol ID prijemcu
items	array	REQ	Položky faktúry (max 999)
items[].description	string	REQ	Popis polozky
items[].quantity	number	REQ	Mnozstvo
items[].unitPrice	number	REQ	Cena za jednotku bez DPH
items[].vatRate	number	REQ	Sadzba DPH v % — povolené: 0, 5, 10, 19, 23 (povolené: `0`, `5`, `10`, `19`, `23`)
items[].discount	number	optional	Zlava v %
items[].unit	string	optional	UN/ECE Rec 20 kód jednotky (default C62) (default: `C62`)
invoiceNumber	string	optional	Číslo faktúry — auto ak prázdne
issueDate	string	optional	ISO 8601 date
dueDate	string	optional	ISO 8601 date
currency	string	optional	EUR (default) (default: `EUR`)
paymentMethod	string	optional	UNCL4461 kód, napr. "30" (prevod)
variableSymbol	string	optional	Variabilný symbol platby
buyerReference	string	optional	Referencia kupujúceho (napr. číslo objednávky)
note	string	optional	Poznamka
iban	string	optional	IBAN
receiverName	string	optional	Meno prijemcu
receiverIco	string	optional	ICO
receiverDic	string	optional	DIČ príjemcu
receiverIcDph	string	optional	IČ DPH príjemcu
receiverAddress	string	optional	Adresa príjemcu
receiverCountry	string	optional	ISO krajina príjemcu (default SK) (default: `SK`)
attachments	array	optional	Prílohy (BG-24) vložené ako base64 do UBL XML — prijímateľ ich vidí priamo vo faktúre
attachments[].fileName	string	REQ	Názov súboru
attachments[].mimeType	string	REQ	application/pdf, image/png, image/jpeg, text/csv, xlsx, ods
attachments[].content	string	REQ	Base64-encoded obsah (bez data: prefixu)
attachments[].description	string	optional	Krátky popis prílohy (max 100 znakov)
xml	string	optional	UBL XML mode — Raw UBL XML string (alternatíva k JSON poliam vyššie). Max 5 MB per raw XML payload.

Odpovede

200Cached/Duplicate
201Sent
202Accepted (async dispatch — status SENT_DB_PENDING; poll /status for delivery confirmation)
401Unauthorized
403API plan required
409Duplicate Invoice / Idempotency Conflict
422Three distinct error codes share 422 — branch on `error.code` to handle correctly: `VALIDATION_ERROR` = input schema rejection (your JSON / XML failed Zod or XSD; fix the payload and retry). `VALIDATION_FAILED` / `UBL_VALIDATION_ERROR` = Peppol schematron rejection (UBL is well-formed but breaks a BIS3/CEN business rule; the `details[]` array carries `rule` IDs like `BR-CO-26` to identify the failure). `IDEMPOTENCY_KEY_MISMATCH` = the same `Idempotency-Key` was reused with a different request body. Generic `VALIDATION_ERROR` retry will silently swallow schematron failures, so always branch on the code.
502Peppol send failed (retryable)
503VALIDATION_UNAVAILABLE — validation service temporarily unreachable, retry with backoff

POST/api/v1/documents/send/batch

Hromadné odoslanie max 50

Odošle až 50 faktúr v jednom volaní. Každá položka má vlastný voliteľný idempotencyKey. Endpoint vždy vráti 200 — chyby sú per-item v poli results. Maximálna veľkosť tela 20 MB.

Parametre

Názov	Typ	Povinné	Popis
items	array	REQ	Pole max 50 položiek — rovnaká schéma ako POST /documents/send
items[].idempotencyKey	string	optional	Voliteľný kľúč pre idempotentné opakovanie položky

Odpovede

200OK
401Unauthorized
403API plan required
413Payload too large
422Validation Error

GET/api/v1/inbound/documents

Pull: zoznam prijatych dokumentov

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

Parametre

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

Odpovede

200OK
400INVALID_CURSOR (kurzor je poškodený alebo nepodporovaná verzia), alebo BAD_REQUEST pre neplatný `limit`/`kind`.
401Unauthorized
403FORBIDDEN — API access vyžaduje api-enterprise priamo alebo integrator-managed cez spravujúceho integrátora.
429RATE_LIMIT_EXCEEDED

GET/api/v1/inbound/documents/{id}

Pull: detail dokumentu

Vráti ten istý tvar ako jedna položka zo zoznamu. 404 keď dokument neexistuje ALEBO patrí inej firme — ten istý response v oboch prípadoch (tenant izolácia, neúnik existencie).

Odpovede

200OK
401Unauthorized
403FORBIDDEN
404Dokument neexistuje alebo patrí inej firme (rovnaký response).

GET/api/v1/inbound/documents/{id}/ubl

Pull: surový UBL XML

Vráti UBL XML payload v presne takej podobe, v akej sme ho prijali z Peppol siete — bez transformácie, bez kanonikalizácie. Prílohy sú v UBL ako `<cbc:EmbeddedDocumentBinaryObject>` (base64) podľa BIS Billing 3.0; parsujte ich klientsky.

Odpovede

200OK, Content-Type: application/xml; charset=utf-8
401Unauthorized
403FORBIDDEN
404Dokument nenájdený, patrí inej firme, alebo nemá uložený raw XML (napr. dashboard-importovaný riadok).

POST/api/v1/inbound/documents/{id}/ack

Pull: explicitné potvrdenie spracovania

VOLITEĽNÉ. Väčšina klientov toto nepotrebuje — implicitný ack je posun kurzora cez `GET /inbound/documents`. Explicit ack existuje pre klientov, ktorí chcú zaznamenať „úspešne spracované u nás" oddelene od „úspešne stiahnuté". Idempotentné: druhé volanie prepíše timestamp a `client_reference`.

Parametre

Názov	Typ	Povinné	Popis
client_reference	string	optional	Voliteľný klientsky identifikátor (napr. interné číslo faktúry), max 256 znakov. V tele požiadavky ako JSON `{"client_reference": "..."}`. Prázdne telo je tiež platné.

Odpovede

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

GET/api/v1/outbound/documents

Pull: zoznam odoslaných dokumentov

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

Parametre

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

Odpovede

200OK
400INVALID_CURSOR alebo BAD_REQUEST (neplatný `limit`, `kind`, `status` alebo `business_status` skombinovaný s non-billing kind).
401Unauthorized
403FORBIDDEN — API access vyžaduje api-enterprise priamo alebo integrator-managed cez spravujúceho integrátora.
429RATE_LIMIT_EXCEEDED

GET/api/v1/outbound/documents/{id}

Pull: detail odoslaného dokumentu

Detail odoslaného dokumentu vrátane histórie pokusov (`attempt_history`). 404 keď dokument neexistuje ALEBO patrí inej firme ALEBO ide o smerom inbound — rovnaký response v každom prípade (tenant izolácia).

Odpovede

200OK
401Unauthorized
403FORBIDDEN
404Dokument neexistuje, patrí inej firme, alebo nie je outbound (rovnaký response).

GET/api/v1/outbound/documents/{id}/ubl

Pull: surový UBL XML odoslaného dokumentu

Vráti UBL XML presne v takej podobe, v akej sme ho odoslali na Peppol sieť. Bez transformácie. Billing dokumenty: `invoices.ubl_xml_path`; non-billing: `peppol_documents.raw_xml_path`. 404 keď neexistuje, patrí inej firme, alebo nemá uložený payload.

Odpovede

200OK, Content-Type: application/xml; charset=utf-8
401Unauthorized
403FORBIDDEN
404Not found / no stored payload

GET/api/v1/outbound/documents/{id}/mdn

Surová AS4 MDN doručenka

Vráti surovú AS4 signal-message doručenku (MDN/receipt) pre odoslaný dokument, ak bola forward-retained v archíve. Endpoint je určený pre audit/dispute scenáre; bežný stav doručenia sledujte cez `transport_status`, `delivered_at` alebo webhook/eventy. 404 keď dokument neexistuje, patrí inej firme, nie je outbound, alebo preň ešte nemáme zachovanú MDN doručenku.

Odpovede

200OK, raw AS4 receipt bytes. Headers obsahujú `X-MDN-Message-Id`, `X-MDN-Ref-To-Message-Id`, `X-MDN-SHA256` a `X-MDN-Received-At`.
401Unauthorized
403FORBIDDEN — vyžaduje API plán (`api-enterprise` priamo alebo `integrator-managed` cez spravujúceho integrátora).
404Document not found / no retained MDN receipt.
500MDN evidence integrity check failed — hash v DB nesedí s bytes v archíve.

GET/api/v1/outbound/events

Pull: stream udalostí (lifecycle)

Cursor-based stream udalostí zo `document_events` tabuľky. Vracia status-transitions oldest-first (postupuje časom dopredu). LIMITÁCIA: aktuálne pokrýva LEN fakturačné outbound dokumenty (invoice, credit_note, self_billing*); non-billing (Order, DespatchAdvice…) sa zatiaľ trackuje pollovaním `GET /api/v1/outbound/documents`. Polymorphic event log je na roadmape — viď `docs/operations/known-inconsistencies.md`.

Parametre

Názov	Typ	Povinné	Popis
since	string	optional	Opaque kurzor z `next_cursor` predchádzajúcej odpovede.
limit	integer	optional	1-500. Hodnoty nad 500 sa orezú na 500. (default: `100`)
document_id	string	optional	Filter len na udalosti jedného dokumentu (UUID).

Odpovede

200OK
400INVALID_CURSOR or BAD_REQUEST
401Unauthorized
403FORBIDDEN

GET/api/v1/documents/inbox

Zoznam prijatých fakturačných dokumentov

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

Parametre

Názov	Typ	Povinné	Popis
limit	integer	optional	Max 100 (default: `20`)
offset	integer	optional	Offset pre stránkovanie. Pre stabilné stránkovanie vo veľkom objeme použite cursor namiesto offset. (default: `0`)
cursor	string	optional	Opaque kurzor zo `nextCursor` predchádzajúcej odpovede. Stabilné stránkovanie aj keď sa medzitým pridajú nové dokumenty.
status	string	optional	Filter podľa stavu (povolené: `RECEIVED`, `ACKNOWLEDGED`, `ACCEPTED`, `REJECTED`, `PAID`, `VALIDATION_FAILED`, `FAILED`)
peppolMessageId	string	optional	Vyhľadanie dokumentu podľa Peppol message ID (max 100 znakov)
since	string	optional	ISO 8601 dátum — filtruje createdAt >= since pre inkrementálnu synchronizáciu

Odpovede

200OK
401Unauthorized
403API plan required
422Validation Error

GET/api/v1/documents/inbox/{id}

Detail dokumentu

Vrati detail prijateho dokumentu vratane UBL XML payloadu.

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

POST/api/v1/documents/inbox/{id}/acknowledge

Potvrdiť prijatie

Oznaci dokument ako spracovany. Telo požiadavky nie je potrebne. Funguje iba pre inbound dokumenty v stave received. Opakované volanie alebo iný stav vráti 422.

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found
422Invalid state transition

GET/api/v1/documents/{id}/status

Stav dokumentu

Vráti úplný životný stav dokumentu vrátane histórie stavov a výsledku validácie. Limit 400 req/min na API kľúč. Pri pravidelnom kontrolovaní viacerých dokumentov použite hromadný endpoint POST /api/v1/documents/status/batch — jedným volaním získate stav až 100 dokumentov.

Odpovede

200OK
401Unauthorized
403Forbidden
404Not Found

POST/api/v1/documents/status/batch

Hromadný stav až 100 dokumentov

Vráti stav až 100 dokumentov v jednom volaní. Výsledky sú v rovnakom poradí ako vstupné ids. Dokumenty, ktoré nepatria volajúcej firme alebo neexistujú, sú v odpovedi označené { "error": "not_found" } — endpoint nikdy nevráti 404 pre celé volanie ani neprezradí existenciu dokumentov inej firmy. Limit 300 req/min na API kľúč (až 30 000 stavov za minútu). Pre jednotlivé dokumenty použite GET /api/v1/documents/{id}/status (limit 400 req/min).

Parametre

Názov	Typ	Povinné	Popis
ids	string[]	REQ	1 až 100 ID dokumentov. Duplicitné ID sa zlúčia, poradie odpovede zachová poradie vstupu.

Odpovede

200OK
401Unauthorized
403API plan required
413Payload too large (> 64 KB)
422Validation Error (ids[] missing, prázdne, viac ako 100, alebo non-string)
429Too Many Requests

GET/api/v1/documents/{id}/evidence

AS4 potvrdenie a MLR

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

Odpovede

200OK
401Unauthorized
403Forbidden
404Not Found

GET/api/v1/documents/{id}/evidence-bundle

Dôkazový ZIP balík

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

Odpovede

200application/zip — manifest.json, evidence.json and available document/evidence artifacts
401Unauthorized
403API plan required
404Not Found — document missing or not yours
500MDN evidence integrity check failed

GET/api/v1/documents/{id}/envelope

AS4 envelope (WORM archív)

Vráti podpísaný AS4 multipart payload dokumentu z 10-ročného WORM archívu (S3 Object Lock COMPLIANCE). Payload je identický s tým, čo prešlo cez Peppol sieť — podpísaný, časovo razítkovaný, tamper-evident. Odpoveď má hlavičky X-Envelope-Archived-At (ISO 8601) a X-Envelope-Direction (inbound/outbound). 404 sa vracia, ak dokument neexistuje, nepatrí vám, alebo jeho envelope ešte nebol archivovaný (nové dokumenty sa archivujú za niekoľko minút).

Odpovede

200application/octet-stream — raw AS4 envelope bytes
401Unauthorized
403API plan required
404Not Found — document missing, not yours, or envelope not yet archived

GET/api/v1/documents/{id}/events

Lifecycle udalosti dokumentu

Vráti chronologický zoznam lifecycle udalostí pre daný dokument. Kombinuje reálne DocumentEvent záznamy s udalosťami syntetizovanými z historických stavov faktúry (created, status_changed, sent, delivered, mlr_received, response_sent/received, paid, fs_reported). Cursor-based stránkovanie, default 20, max 100.

Parametre

Názov	Typ	Povinné	Popis
limit	integer	optional	Max 100 (default: `20`)
cursor	string	optional	Opaque cursor from pagination.nextCursor

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

GET/api/v1/documents/{id}/responses

Invoice response história

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

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

GET/api/v1/documents/{id}/pdf

Stiahnuť PDF

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

Odpovede

200application/pdf
401Unauthorized
403Forbidden
404Not Found

GET/api/v1/documents/{id}/ubl

Stiahnuť UBL XML

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

Odpovede

200application/xml
401Unauthorized
403Forbidden
404Not Found

POST/api/v1/documents/{id}/respond

Odoslať odpoved na fakturu

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

Parametre

Názov	Typ	Povinné	Popis
status	string	REQ	AB (accepted billing), IP (in process), UQ (under query), CA (conditionally accepted), RE (rejected), AP (accepted), PD (paid) (povolené: `AB`, `IP`, `UQ`, `CA`, `RE`, `AP`, `PD`)
note	string	optional	Voliteľná poznámka — max 500 znakov, dlhší text sa skráti

Odpovede

200Úspech
202Accepted-queued
401Unauthorized
403Forbidden
404Not Found
422Validation Error

POST/api/v1/documents/{id}/mark

Označiť stav dokumentu

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

Parametre

Názov	Typ	Povinné	Popis
state	string	REQ	delivered \| processed \| failed \| read (povolené: `delivered`, `processed`, `failed`, `read`)
note	string	optional	Voliteľná poznámka

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found
422Invalid state

POST/api/v1/extract

Extrahovať jeden súbor

Extrahuje dáta faktúry z PDF alebo obrázku pomocou AI. Pri prijatej/inbound faktúre vráti Peppol BIS 3.0 UBL XML s validáciou. Pri vystavenej/outbound štandardnej faktúre neodosiela priamo z OCR, ale vráti direction=outbound a send_payload — návrh JSON tela pre POST /api/v1/documents/send, ktorý musí integrátor skontrolovať, doplniť chýbajúce polia (najmä receiverPeppolId, ak sa nedá vyriešiť) a poslať ako samostatnú požiadavku s Idempotency-Key. Pre outbound typy mimo JSON send flow (napr. dobropis) vráti extrakciu na kontrolu bez send_payload; odošlite validné UBL XML cez /documents/send. Samofakturácia je podporovaná ako typ dokladu: OCR ju rozpozná z povinnej slovnej informácie (napr. vyhotovenie faktúry odberateľom / self-billing) a pri chybnej klasifikácii ju môžete nastaviť cez multipart fields {"document_type":"self_billing"}. Max 20 MB. Polia missing_fields, field_sources a next_action tvoria checklist pre integrátora: čo doplniť, odkiaľ hodnota pochádza a čo spraviť ďalej. Ak OCR niečo neprečíta, pošlite rovnaký súbor znova a pridajte multipart field fields ako JSON, napr. {"vendor_dic":"2020123456","vendor_ic_dph":"SK2020123456","iban":"SK..."}. Rate limit: 10 extrakcií / minúta na firmu.

Parametre

Názov	Typ	Povinné	Popis
file	File	REQ	PDF, JPEG, PNG, WebP (max 20 MB)
fields	JSON string	optional	Optional OCR overrides. Examples: vendor_ico, vendor_dic, vendor_ic_dph, iban, payment_means_code, invoice_number, due_date, document_type=self_billing.

Odpovede

200OK
400Bad Request
401Unauthorized
403API plan required
422Extraction failed or generated inbound UBL failed validation. Issued/outbound PDFs return 200 with direction=outbound; standard invoices include send_payload for review.
429Rate Limited
503Service Unavailable

POST/api/v1/extract/batch

Batch extrakcia max 50

Spracuje az 50 suborov naraz. Chyba jedneho neblokuje ostatne. Kazdy uspesny riadok vracia rovnaky review checklist ako POST /api/v1/extract: missing_fields, field_sources a next_action. Rate limit: 3 požiadavky / minúta na firmu. Celková veľkosť max 200 MB na požiadavku.

Parametre

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

Odpovede

200OK
400Bad Request
401Unauthorized
403API plan required
413Payload Too Large
429Rate Limited
503Service Unavailable

POST/api/v1/documents/validate

Validovať dokument

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

Parametre

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

Odpovede

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

POST/api/v1/documents/preflight

Kontrola pred odoslaním

Dry-run odoslania bez vytvorenia dokladu a bez účtovania spotreby. Overí UBL validáciu, Peppol účastníka, presný SMP routing pre `documentTypeId + processId`, endpoint URL a certifikačné metadata. Endpoint vracia 200 aj pri blokovanom výsledku — rozhodnutie čítajte z `decision`, `canSend`, `errors[]` a `checks[]`. Integrátorský vstup používa `senderParticipantId`, `receiverParticipantId`, `documentTypeId`, `processId`, `ublDocument`; podporované sú aj aliasy `receiverPeppolId`, `xml` a `invoice`. Pri UBL XML vstupe sa kontroluje, či sa Peppol ID dodávateľa v XML zhoduje s autentifikovanou firmou — nesúlad vráti 422.

Parametre

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

Odpovede

200OK — sendable, blocked, or retryable decision is encoded in the JSON body
401Unauthorized
403API plan required
413Payload Too Large
422Validation Error — includes UBL_VALIDATION_ERROR with rule field on schematron failure; 422 SENDER_MISMATCH when XML supplier Peppol ID differs from authenticated firm

POST/api/v1/documents/convert

Konverzia formátov

Konvertuje dokument medzi JSON a UBL XML formátmi. Podporovaná konverzia: json→ubl a ubl→json. Maximum tela požiadavky 6 MB. Pri output_format: ubl je document reťazec s XML dokumentom (nie objekt).

Parametre

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

Odpovede

200OK
400Bad Request
401Unauthorized
403API plan required
413Payload Too Large
422Conversion failed

POST/api/v1/documents/parse

Rozobrať UBL XML na JSON

Rozoberie UBL XML na normalizovaný JSON bez odoslania. Užitočné pri migrácii z iného AP alebo pre príchodzie doklady z mimo-Peppol kanála (email, SFTP). Prijíma Content-Type: application/xml (raw telo) alebo application/json s poľom xml. Maximum 10 MB.

Parametre

Názov	Typ	Povinné	Popis
xml	string	REQ	UBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Odpovede

200OK
401Unauthorized
403API plan required
413Payload Too Large
422Validation Error
500Parse Error

GET/api/v1/documents/inbox/all

Cross-firm inbox

Vráti dokumenty zo všetkých spravovaných firiem v jednej odpovedi. Vyžaduje JWT získané zo sk_int_* kľúča. Vysledky su obmedzene na dokumenty s createdAt >= integratorFirm.createdAt — integratori vidia len dokumenty dorucene po tom, ako bol integrator priradeny k danej firme. Priame dashboard sessions (bez integratorského kontextu) zobrazia vsetky dokumenty bez tohto obmedzenia.

Parametre

Názov	Typ	Povinné	Popis
since	string	optional	ISO 8601 — dokumenty od dátumu
status	string	optional	Filter podľa stavu — predvolene všetky (parameter vynechajte). Hodnoty sa porovnávajú case-insensitive. (povolené: `RECEIVED`, `ACKNOWLEDGED`, `ACCEPTED`, `REJECTED`, `PAID`, `VALIDATION_FAILED`, `FAILED`)
firm_id	string	optional	Filtrovať podľa firmy
offset	number	optional	Posunutie pre stránkovanie
limit	number	optional	Max výsledkov (default 50, max 200) (default: `50`)

Odpovede

200OK
401Unauthorized
403Forbidden

Webhooks

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

Push vs pull — Každá subscription je buď push (POST na vašu URL) alebo pull (event v queue, ktorú periodicky čítate cez GET /api/v1/webhook-queue). Subscription s url je push-only; subscription bez url (null) je pull-only. Jedna subscription = jeden kanál; ak chcete oba, vytvorte dve subscriptiony. Push deliveries sa nezapisujú do pull queue a naopak — kanály sú navzájom oddelené.

Tvar payloadu (v1) — Telo POSTu / item v pull queue obsahuje obálku { event, event_version: "1", webhook_id, webhook_event_id, timestamp, data }. event_version je verzia schémy. webhook_id je per-delivery (push only, null v pull queue). webhook_event_id (od 2026-05-12) je VŽDY UUID — stabilná identifikácia per-logical-event, rovnaká hodnota cez všetky retry-e tej istej delivery aj cez push+pull rozdelenie. Použite ju ako primárny dedup key na strane receiveru (INSERT ON CONFLICT DO NOTHING). Pre pull subscription je to zároveň ack key (DELETE /api/v1/webhook-queue/{id}). data závisí od event-u — pre billing eventy obsahuje document_id, document_number, direction, doctype_key, status, previous_status, total_amount, currency, issue_date, due_date, sender_peppol_id, receiver_peppol_id. Per-event extras: sent_at (document.sent), received_at (document.received), delivered_at + as4_message_id (document.delivered), rejected_at + response_code + response_reason + responder (document.rejected), responded_at + response_code + response_reason (document.response_received), failure_reason + attempts (document.delivery_failed).

Hlavičky a overenie podpisu — Každý webhook obsahuje HMAC-SHA256 podpis (kontrakt sa nemenil). Z hlavičiek si vezmite X-Webhook-Timestamp a X-Webhook-Signature, spojte timestamp + "." + raw body, vypočítajte HMAC-SHA256 so svojím webhook secretom a porovnajte s hodnotou z hlavičky. Odmietnite požiadavku, ak je timestamp starší ako 5 minút (ochrana proti replay útokom). Ďalšie hlavičky (od 2026-05-12): X-Webhook-Event-Id (UUID, dedup key, identická cez všetky retry — odporúčaný primárny dedup), X-Webhook-Id (per-delivery, identifikuje konkrétny webhook_deliveries riadok), X-Webhook-Event (typ event-u), X-Webhook-Attempt (1-based číslo pokusu, mení sa medzi retry-mi), X-Webhook-Max-Attempts (celkový počet pokusov v retry okne).

GET/api/v1/webhooks

Zoznam webhookov

Vrati vsetky webhooky pre vashu firmu.

Odpovede

200OK
401Unauthorized
403API plan required

POST/api/v1/webhooks

Vytvoriť webhook

Vytvori novy webhook. URL je voliteľná: ak ju vynecháte alebo dáte null, vytvoríte pull-only subscription (eventy v queue čítate cez GET /api/v1/webhook-queue). Ak URL zadáte, musí mať HTTPS. Secret pre overenie podpisu je zobrazený iba raz.

Parametre

Názov	Typ	Povinné	Popis
url	string \| null	optional	HTTPS URL pre push, alebo null/omit pre pull-only
events	string[]	optional	Predvolene vsetky udalosti

Odpovede

201Created
401Unauthorized
403API plan required
413Payload too large
422Validation Error

GET/api/v1/webhooks/{id}

Detail + doručenia

Vrati detail webhooku a poslednych 20 pokusov o dorucenie.

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

PATCH/api/v1/webhooks/{id}

Upraviť webhook

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

Parametre

Názov	Typ	Povinné	Popis
url	string	optional	HTTPS URL
events	string[]	optional	Nove udalosti
isActive	boolean	optional	Aktivovat/deaktivovat

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found
422Validation Error

DELETE/api/v1/webhooks/{id}

Zmazať webhook

Natrvalo zmaze webhook a vsetky zaznamy o doruceni.

Odpovede

204No Content — webhook bol zmazaný
401Unauthorized
403API plan required
404Not Found

POST/api/v1/webhooks/{id}/test

Poslať testovaciu udalosť

Pošle testovaciu udalosť na URL webhooku s platným HMAC podpisom. Predvolený mode=direct odošle syntetické POSTy okamžite a vráti agregovaný výsledok. mode=queued vytvorí reálne pending delivery riadky a doručenie nechá na produkčný webhook worker s retry/backoff politikou; odpoveď 202 obsahuje testRunId na sledovanie v histórii doručení. URL je znovu validovaná voči SSRF allowliste pred každým testom. Typ udalosti možno zadať buď ako query parameter ?event= (preferované) alebo v tele { event }. Parameter count (query alebo body) odošle viac test udalostí; povolený rozsah je 1..1000. Platné typy: document.sent, document.received, document.delivered, document.delivery_failed, document.rejected, document.response_received.

Parametre

Názov	Typ	Povinné	Popis
event	string	optional	Query param (preferred) or body field. Valid values: document.sent \| document.received \| document.delivered \| document.delivery_failed \| document.rejected \| document.response_received. Default: document.sent. (default: `document.sent`) (povolené: `document.sent`, `document.received`, `document.delivered`, `document.delivery_failed`, `document.rejected`, `document.response_received`)
count	integer	optional	Query param or body field. Number of synthetic webhook POSTs to send in one test run. Valid range: 1..1000. Default: 1. (default: `1`)
mode	string	optional	direct sends immediately and waits for aggregate results. queued creates delivery rows and lets the production webhook worker process them. Valid: direct \| queued. Default: direct. (default: `direct`) (povolené: `direct`, `queued`)

Odpovede

200OK (200 sa vráti aj keď testovacie doručenie zlyhá — skontrolujte pole success a error)
202Queued test accepted. Poll deliveriesUrl or GET /webhooks/{id}/deliveries?testRunId=... for worker results.
401Unauthorized
403API plan required
404Not Found
422Validation Error

GET/api/v1/webhooks/{id}/deliveries

História doručení

Stránkovaná história pokusov o doručenie pre jeden webhook — status kódy, odpovede, počet pokusov, čas ďalšieho opakovania. Užitočné pri debuggovaní.

Parametre

Názov	Typ	Povinné	Popis
limit	number	optional	1–100 (default: `20`)
offset	number	optional	Začiatok od (predvolene 0) (default: `0`)
cursor	string	optional	Opaque cursor from nextCursor in the previous response. Use instead of offset for stable pagination over large history.
status	string	optional	PENDING \| SUCCESS \| FAILED \| RETRYING (povolené: `PENDING`, `SUCCESS`, `FAILED`, `RETRYING`)
event	string	optional	Filter podľa typu udalosti
testRunId	string	optional	Filter deliveries created by POST /webhooks/{id}/test?mode=queued.
includeResponseBody	boolean	optional	When true, includes the responseBody field on each delivery record. Omitted by default to reduce payload size. Alias: include=responseBody. (default: `false`)

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

GET/api/v1/webhook-dead-letter

Webhook dead-letter queue

Vracia nevyriešené terminálne zlyhané push doručenia naprieč webhookmi vašej firmy. Použite na ERP runbooky: čo treba replaynúť alebo manuálne označiť ako vyriešené.

Parametre

Názov	Typ	Povinné	Popis
limit	number	optional	1–100 (default: `20`)
offset	number	optional	Začiatok od (predvolene 0) (default: `0`)
event	string	optional	Filter podľa typu udalosti
subscriptionId	string	optional	Filter na konkrétnu webhook subscription
includeResponseBody	boolean	optional	Ak true, vráti aj poslednú odpoveď ERP endpointu. (default: `false`)

Odpovede

200OK
401Unauthorized
403API plan required

POST/api/v1/webhook-dead-letter/{deliveryId}/replay

Replay zlyhaného webhooku

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

Parametre

Názov	Typ	Povinné	Popis
deliveryId	string	REQ	ID z GET /api/v1/webhook-dead-letter

Odpovede

202Accepted
401Unauthorized
403API plan required
404Not Found
422Validation Error

POST/api/v1/webhook-dead-letter/{deliveryId}/resolve

Označiť webhook zlyhanie ako vyriešené

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

Parametre

Názov	Typ	Povinné	Popis
deliveryId	string	REQ	ID z GET /api/v1/webhook-dead-letter
reason	string	optional	Krátka poznámka, max 500 znakov

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

POST/api/v1/webhooks/{id}/rotate-secret

Rotovať podpisový secret

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

Odpovede

200OK
401Unauthorized
403API plan required
404Not Found

GET/api/v1/webhook-queue

Stiahnuť udalosti

Vráti nepotvrdené udalosti (oldest-first). Po spracovaní potvrď každú udalosť pomocou DELETE alebo batch-ack.

Parametre

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

Odpovede

200OK
401Unauthorized
403API plan required

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

Potvrdiť udalost

Označí jednotlivú udalosť ako spracovanú (acknowledged). Vráti 200 s telom { acknowledged: true }.

Odpovede

200OK
401Unauthorized
403Forbidden
404Not Found

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

Batch potvrdenie

Hromadne potvrdí viaceré udalosti. Max 1000 ID v jednej požiadavke. Vráti 200 s telom { acknowledged: N }.

Parametre

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

Odpovede

200OK
401Unauthorized
403API plan required
422Validation Error

GET/api/v1/webhook-queue/all

Cross-firm webhook queue

Vráti webhook udalosti naprieč všetkými firmami. Vyžaduje JWT získané zo sk_int_* kľúča. Auth: withIntegratorNoFirm — sk_int_* povinné, X-Firm-Id sa ignoruje.

Parametre

Názov	Typ	Povinné	Popis
limit	number	optional	Max výsledkov (default 100, max 500) (default: `100`)
since	string	optional	ISO 8601 — filter udalostí vytvorených po tomto čase

Odpovede

200OK
401Unauthorized
403Forbidden — caller is not an sk_int_* integrator

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

Hromadné potvrdenie udalostí

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

Parametre

Názov	Typ	Povinné	Popis
event_ids	string[]	REQ	Pole ID udalostí na potvrdenie (UUID, max 1000)

Odpovede

200OK
400Bad Request
401Unauthorized

Peppol

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

GET/api/v1/peppol/participants/{scheme}/{identifier}

SMP Lookup

Overí, či je účastník registrovaný v Peppol sieti cez DNS/SMP lookup. Výsledky sú cachované 24 hodín.

Parametre

Názov	Typ	Povinné	Popis
scheme	string	REQ	4-ciferný ISO 6523 kód napr. 0245
identifier	string	REQ	Identifikátor účastníka

Odpovede

200Found
400Invalid params
401Unauthorized
404Not found in Peppol

GET/api/v1/peppol/participants/resolve

Resolve firmy na Peppol účastníka

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

Parametre

Názov	Typ	Povinné	Popis
ico	string	optional	Slovak IČO, 6-8 digits. Mutually exclusive with other identifiers.
dic	string	optional	Slovak DIČ, 10 digits. Mutually exclusive with other identifiers.
icDph	string	optional	VAT ID, e.g. SK2020123456. Mutually exclusive with other identifiers.
peppolId	string	optional	Direct Peppol participant ID, e.g. 0245:2020123456.
scheme	string	optional	ISO 6523 scheme when using scheme+identifier instead of peppolId.
identifier	string	optional	Participant identifier when using scheme+identifier instead of peppolId.
documentTypeId	string	optional	Peppol document-type URN. Default is BIS Billing 3.0 Invoice.
processId	string	optional	Peppol process ID. Default is BIS Billing 3.0.

Odpovede

200OK
400Invalid or ambiguous query
401Unauthorized
403API plan required
404Company or participant candidate not found

GET/api/v1/peppol/directory/search

Hľadať v adresári

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

Parametre

Názov	Typ	Povinné	Popis
q	string	REQ	Hľadaný výraz min 2 znaky
country	string	optional	ISO kod krajiny napr. SK
page	integer	optional	Stranka vysledkov
page_size	integer	optional	Max 50

Odpovede

200OK
400Query too short
401Unauthorized

GET/api/v1/company/lookup/{ico}

Info o firme + Peppol status

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

Odpovede

200OK
400Invalid ICO
401Unauthorized
404Not Found

POST/api/v1/peppol/capabilities

Zistiť podporované dokumenty

Sonduje Peppol SMP účastníka — vráti zoznam akceptovaných typov dokumentov a transportných profilov. Ak je zadaný documentType, vráti aj matchedDocumentType ako URN matchnutého typu (alebo null, ak ho účastník nepodporuje) na presné overenie pred odoslaním.

Parametre

Názov	Typ	Povinné	Popis
participant	object	REQ	Objekt { scheme, identifier }. scheme = 4-ciferný ISO 6523 kód (napr. 0245), identifier = identifikátor účastníka
documentType	string	optional	Konkrétny Peppol document-type URN pre overenie
processId	string	optional	Voliteľný BIS 3 process ID

Odpovede

200OK
400Invalid params
401Unauthorized
404Not Found (participant not registered in Peppol)

POST/api/v1/peppol/participants/batch

Hromadné overenie max 100

Hromadné overenie až 100 Peppol účastníkov v jednom volaní. Vhodné na dávkovú validáciu zoznamu odberateľov pred odoslaním faktúr.

Parametre

Názov	Typ	Povinné	Popis
participants	array	REQ	Pole max 100 položiek { scheme, identifier }

Odpovede

200OK
401Unauthorized
403API plan required
422Validation Error

POST/api/validate

Peppol BIS 3.0 validácia (verejné)

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

Parametre

Názov	Typ	Povinné	Popis
xml	string	REQ	UBL XML dokument (pri application/json) alebo raw telo (pri application/xml)

Odpovede

200OK
400Invalid XML
413Too Large
429Rate Limited

Firmy

Správa firiem priradených k vášmu integrátorskému účtu. Správa prístupu k firmám pre integrátorské kľúče (sk_int_*).

GET/api/v1/firms

Zoznam prístupných firiem

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

Odpovede

200OK
401Unauthorized

GET/api/v1/firms/{id}

Detail firmy

Vráti úplný detail firmy vrátane adresy, DIČ, IČ DPH a Peppol stavu.

Odpovede

200OK
401Unauthorized
403Forbidden
404Not Found

GET/api/v1/firms/{id}/documents

Dokumenty firmy

Vráti stránkovaný zoznam dokumentov firmy. Integrátori môžu pristupovať k dokumentom spravovaných klientov. Integratori vidia len dokumenty s createdAt >= integratorFirm.createdAt — teda dokumenty dorucene az po priradeni integrátora k firme. Priame dashboard sessions (bez integratorského kontextu) zobrazia vsetky dokumenty.

Parametre

Názov	Typ	Povinné	Popis
page	integer	optional	Stranka (default: `1`)
page_size	integer	optional	Max 100 (default: `20`)
direction	string	optional	inbound \| outbound (povolené: `inbound`, `outbound`)
status	string	optional	Filter podľa stavu
from	string	optional	ISO 8601 date
to	string	optional	ISO 8601 date

Odpovede

200OK
400Validation Error
401Unauthorized
403Forbidden

POST/api/v1/firms/{id}/peppol-identifiers

Registrovat Peppol ID

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

Parametre

Názov	Typ	Povinné	Popis
scheme	string	REQ	ISO 6523 kód napr. 0245
identifier	string	REQ	Identifikátor firmy. Pre scheme 0245 musí byť rovný firm.dic (slovenské DIČ, NIE IČO).

Odpovede

201Created
400Validation Error
401Unauthorized
403Forbidden
404Firm not found

POST/api/v1/firms/assign

Priradiť firmu podľa IČO

Aktivuje firmu pre integrátorský účet podľa IČO. Vyžaduje JWT získané z sk_int_* kľúča. DÔLEŽITÉ: Priame priradenie cez IČO funguje iba vtedy, keď už existuje neodvolaná IntegratorFirm väzba vytvorená po OAuth súhlase vlastníka alebo admina firmy. Plán firmy nie je súhlas konkrétnemu integrátorovi. Každé prvotné priradenie musí prejsť cez OAuth authorization_code flow, kde majiteľ alebo admin firmy explicitne klikne "Súhlasím". Bez existujúceho súhlasu endpoint vráti 403 CONSENT_REQUIRED.

Parametre

Názov	Typ	Povinné	Popis
ico	string	REQ	IČO firmy (8 číslic)

Odpovede

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

POST/api/v1/firms/assign/batch

Hromadné priradenie firiem

Hromadne aktivuje až 50 firiem k integrátorskému účtu podľa IČO. Rovnaké obmedzenia ako pri /firms/assign: táto cesta funguje iba pre firmy s existujúcou neodvolanou IntegratorFirm väzbou po OAuth súhlase. Prvotné priradenie vždy vyžaduje OAuth authorization_code flow.

Parametre

Názov	Typ	Povinné	Popis
icos	string[]	REQ	Pole IČO (max 50)

Odpovede

200OK
401Unauthorized
403Forbidden
422Validation Error

GET/api/v1/integrator/keys

Zoznam integrátorských kľúčov

Vráti integrátorské API kľúče pre aktuálny sk_int_* JWT. Bez X-Firm-Id — endpoint je na úrovni integrátora. Použite ho na nájdenie id alebo keyPrefix kľúča vydaného cez /api/oauth/token.

Odpovede

200OK
401Unauthorized
403Forbidden — missing firms:manage scope

DELETE/api/v1/integrator/keys

Zneplatniť integrátorský kľúč

Zneplatní aktívny integrátorský API kľúč. Pošlite buď keyId z GET /api/v1/integrator/keys, alebo client_id/keyPrefix vrátený z /api/oauth/token. Endpoint nenechá zneplatniť posledný aktívny kľúč integrátora.

Parametre

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

Odpovede

200OK
400Bad Request — invalid body, already inactive, or last active key
401Unauthorized
403Forbidden — missing firms:manage scope
404API key not found

GET/api/v1/integrator/licenses/info

Plán a agregovaná spotreba

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

Parametre

Názov	Typ	Povinné	Popis
offset	integer	optional	Posun pre stránkovanie zoznamu firiem (default: `0`)
limit	integer	optional	Max 100 — počet firiem v firms (default: `50`)
period	string	optional	Aktuálne fakturačné obdobie vo formáte YYYY-MM (SK časová zóna). [response field]
nextResetAt	string	optional	ISO 8601 — kedy sa počítadlá vynulujú (1. deň ďalšieho mesiaca, SK polnoc v UTC). [response field]
billable.outboundCharge	number	optional	Tarifný náklad za odoslané dokumenty — sadzby aplikované na outboundCount ako agregát. [response field]
billable.totalCharge	number	optional	Súčet outbound + inbound API. Zaokrúhlené na centy. [response field]
sandbox.totalCharge	number	optional	Neúčtovaný sandbox odhad pri aktuálnej sandbox prevádzke. [response field]
productionEstimate.totalCharge	number	optional	Odhad ceny, ak by sandbox integrator-managed firmy bežali v produkcii. [response field]
exceedsAutoTier	boolean	optional	true keď billable produkčný outbound alebo inbound prekročí contactThreshold. Auto-billing sa zastaví, obchod riadi manuálne. [response field]
contactThreshold	integer	optional	Hranica (5 000) nad ktorou sa vyžaduje individuálna zmluva. [response field]
firms[].managed	boolean	optional	true = firma je integrator-managed. Kombinujte s firms[].sandbox alebo firms[].billable na odlíšenie účtovaných a testovacích firiem. false = patrí do nonManaged. [response field]
firms[].sandbox	boolean	optional	true = firma je sandbox a neúčtuje sa. [response field]
firms[].billable	boolean	optional	true = firma je integrator-managed produkcia a počíta sa do aktuálne účtovanej prevádzky. [response field]

Odpovede

200OK
401Unauthorized
403Forbidden
404Integrator not found

Reporty

Štatistiky a prehľady o odoslaných a prijatých dokumentoch.

GET/api/v1/reporting/statistics

Štatistiky dokumentov

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

Parametre

Názov	Typ	Povinné	Popis
period	string	optional	month \| quarter \| year (default: `month`) (povolené: `month`, `quarter`, `year`)
from	string	optional	Začiatok obdobia ISO 8601
to	string	optional	Koniec obdobia ISO 8601

Odpovede

200OK
401Unauthorized

GET/api/v1/reporting/submissions

História reportov pre FS SR

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

Parametre

Názov	Typ	Povinné	Popis
limit	number	optional	Max 100 (default: `20`)
offset	number	optional	Posun pre stránkovanie (default: `0`)
report_type	string	optional	EUSR \| TSR (povolené: `EUSR`, `TSR`)

Odpovede

200OK
401Unauthorized
403API plan required

Referencia

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

Cenník

Transparentné ceny bez skrytých poplatkov.

Sandbox

Testovacie prostredie pre integráciu.

Objem	Cena
Neobmedzene	zadarmo

Odoslané

Cena za dokument odoslaný cez Peppol.

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

Prijaté cez API

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

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

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

Rate limity

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

Pravidlá

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

Hlavičky odpovede (HTTP 429)

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

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

Chybové kódy

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

Status	Kód	Popis
400	`BAD_REQUEST`	Neplatné JSON telo alebo chýbajúce pole
400	`INVALID_PARAM`	Neplatná hodnota query parametra
401	`UNAUTHORIZED`	Chýbajúci alebo neplatný API kľúč
403	`FORBIDDEN`	Nedostatočný scope alebo prístup k cudzej firme; alebo firma nemá API-eligible plán
404	`NOT_FOUND`	Prostriedok neexistuje alebo nepatrí vašej firme
409	`CONFLICT`	Duplikát (OAuth klient, priradenie firmy, idempotency in-flight)
413	`PAYLOAD_TOO_LARGE`	Telo požiadavky presahuje povolený limit
422	`VALIDATION_ERROR / UNPROCESSABLE_ENTITY`	Sémantická validácia (UBL, schematron, idempotency mismatch) zlyhala
429	`RATE_LIMITED`retryable	Prekročený rate limit
500	`INTERNAL_ERROR`retryable	Neočakávaná chyba servera
502	`SEND_FAILED`retryable	Odoslanie cez Peppol AP zlyhalo
503	`IDEMPOTENCY_STORE_UNAVAILABLE / VALIDATION_SERVICE_UNAVAILABLE`retryable	Závislosť dočasne nedostupná

Uchovávanie dát

Trvalý archív

Enterprise API ukladá všetky dokumenty trvalo — obsah (UBL/XML), štruktúrované dáta faktúr aj transportné metadata (Peppol message ID, časové pečiatky, AS4 potvrdenia, MLR). Endpointy /documents/{id} a /documents/{id}/ubl sú dostupné bez časového obmedzenia počas aktívneho predplatného. SLA 99,5 % uptime, podpora 24/7.

Uchovávanie dát

Dvojvrstvové uchovávanie: 10-ročný WORM archív signovaných AS4 obálok ako infraštruktúra Access Pointu + prístup k vlastným dokumentom viazaný na aktívne predplatné. Každá signovaná AS4 obálka — prijatá aj odoslaná — sa automaticky ukladá do WORM MinIO bucketu s S3 Object Lock v režime COMPLIANCE na 10 rokov. Platí pre všetky firmy, nezávisle od plánu. Po ukončení kontraktu — 30 dní grace, potom sa API prístup uzatvára.

10-ročná zákonná archivácia

Zákonná povinnosť uchovávať daňové doklady 10 rokov (zákon 431/2002 §35) je na vystaviteľovi/príjemcovi faktúry. Ako Peppol Access Point poskytujeme spoľahlivú WORM infraštruktúru, ktorá túto povinnosť pokrýva, ale formálne ju neprenášame na seba — ste stále vlastníkom dokumentov.