ePodatelna24 — Outbox Ingestion API — príručka pre integráciu ERP

Kompletný návod, ako z ľubovoľného ERP systému (nezáleží na technológii — .NET, Java, PHP, Python, Node…) odovzdať Peppol faktúru do ePodatelna24 na odoslanie do siete Peppol.

Tento repozitár je zároveň referenčná implementácia (Next.js/TypeScript), ale API je obyčajné HTTP + XML — nasledujúci návod stačí na to, aby ste klienta postavili vo svojom jazyku. Všetko, čo tu vidíte, komunikuje výlučne cez verejný HTTP kontrakt: /api-docs (OpenAPI: /api-docs/openapi.yaml).

Tok v skratke

ERP len odovzdá platné XML a dostane potvrdenie o prevzatí. Samotné odoslanie do siete Peppol aj uloženie potvrdenia o doručení už zabezpečí ePodatelna24.

Vykresľujem diagram…

Obsah

1. Ako to funguje (model)
2. Predpoklady
3. Prostredia a základné URL
4. Autentifikácia
5. Kľúčové koncepty
6. Endpointy
7. Dátové štruktúry
8. Stavové kódy a spracovanie chýb
9. Postup integrácie krok za krokom
10. Príklady (curl)
11. Rozhodovacia logika (pseudokód)
12. Kontrolný zoznam pred spustením
13. Časté chyby

1. Ako to funguje (model)

ERP odovzdá jednu faktúru (UBL XML). ePodatelna24 ju synchrónne overí, skontroluje odosielateľa aj príjemcu, zarezervuje poplatok za odoslanie a prevezme za ňu zodpovednosť (custody). Jediná odpoveď na požiadavku hovorí, či bola faktúra prijatá.

Model verzie 1 je „odovzdaj a zabudni":

• 202 = prevzali sme zodpovednosť a faktúru odošleme. ERP už nemusí nič sledovať.
• 4xx = faktúra bola odmietnutá (dôvod je v tele odpovede).

Keďže je odpoveď jediná spätná väzba, pred vrátením 202 sa skontroluje všetko, čo sa skontrolovať dá:

1. bezpečnosť XML (žiadne DOCTYPE/entity/XXE),
2. odosielateľ (DIČ vo faktúre) je v Peppol aktívna spoločnosť pod danou peňaženkou,
3. faktúra prejde Peppol BIS 3.0 / EN 16931 schematronom (validácia),
4. príjemca je dosiahnuteľný v sieti Peppol (SMP vyhľadanie),
5. peňaženka pokryje poplatok za odoslanie.

202 teda znamená: „overené, odosielateľ aktívny, príjemca dosiahnuteľný, poplatok zarezervovaný — počítame s doručením."

Doručenie nesledujete. Vo verzii 1 neexistuje webhook ani dopytovanie stavu doručenia. Po 202 preberá doručenie ePodatelna24; používateľ ho vidí v nástenke eP24.

2. Predpoklady

• API token vygenerovaný v eP24 (viď Autentifikácia).
• Odosielajúca spoločnosť (podľa DIČ vo faktúre) je v eP24 registrovaná a Peppol-aktivovaná, a patrí pod peňaženku, ku ktorej token patrí.
• Peňaženka má dostatok kreditu na poplatok za odoslanie.
• Faktúra je platné UBL 2.1 (Invoice alebo CreditNote) podľa profilu Peppol BIS Billing 3.0.

3. Prostredia a základné URL

Integráciu vždy najprv postavte a otestujte v sandboxe. Token z jedného prostredia v druhom nefunguje.

4. Autentifikácia

Schéma

Každá požiadavka nesie API token v hlavičke Authorization so schémou Token (rovnaká schéma, akú eP24 používa voči svojmu prístupovému bodu — nie Bearer):

Authorization: Token ep24api_prod_XXXXXXXXXXXXXXXXXXXXXXXX

Ako získať token

V eP24: prihláste sa ako vlastník peňaženky (hlavný správca) → Peňaženka → API prístup → Nový token. Token sa zobrazí iba raz — ihneď ho bezpečne uložte (na strane eP24 je uložený len jeho hash).

Rozsah tokenu

Token je na úrovni peňaženky a platí pre celú peňaženku: jedným tokenom odošlete faktúry za ktorúkoľvek spoločnosť pod danou peňaženkou. Konkrétny odosielateľ sa určí z DIČ vo faktúre — do požiadavky netreba dávať žiadny identifikátor spoločnosti.

Pre účtovnícke firmy: jedna peňaženka spravuje všetkých klientov (spoločnosti) účtovníckej firmy, takže jeden token pokryje všetkých.

Bezpečnostné pravidlá (dôležité)

• API je server-to-server. Volajte ho z backendu svojho ERP, nikdy z prehliadača. API nemá CORS a token sa nesmie dostať do prehliadača.
• Token považujte za tajomstvo (ako heslo). Neukladajte ho do klientskej aplikácie, logov ani do verzovacieho systému.
• Kompromitovaný token zneplatnite v eP24 (Peňaženka → API prístup) a vygenerujte nový.

5. Kľúčové koncepty

5.1 Idempotencia (povinná)

Každé odoslanie musí niesť hlavičku Idempotency-Key — UUID, ktoré vygeneruje a uloží váš ERP ku konkrétnej faktúre.

• Nový kľúč = nová faktúra.
• Rovnaký kľúč = bezpečné opakovanie. Ak odoslanie zopakujete s rovnakým kľúčom (napr. po timeoute), dostanete pôvodné potvrdenie namiesto druhého odoslania.
• Kľúč sa „zaviaže" až pri úspešnom 202. Zamietnutie (4xx) kľúč nespotrebuje — po oprave a opätovnom odoslaní tej istej faktúry použite rovnaký kľúč. (Aj 402 kľúč uvoľní: po dobití peňaženky zopakujte s rovnakým kľúčom a dostanete čerstvé 202, nie opakovanie.)
• Režim je prísny. Rovnaký kľúč s bajtovo iným telom vráti 409 idempotency_conflict — nič sa neuloží, nič sa neúčtuje a pôvodný dokument zostáva nedotknutý. Zhoda sa určuje z sha256 surových bajtov požiadavky, takže stačí jediná zmenená medzera. Kľúče nikdy nerecyklujte medzi dokumentmi.
• Opakovanie sa validuje znova. Zopakovaná požiadavka prejde celou vstupnou kontrolou (XML, odosielateľ, jeho aktivácia, schematron, dosiahnuteľnosť príjemcu), takže môže vrátiť 4xx aj vtedy, keď pôvodné odoslanie uspelo. Nevyhodnocuje sa len zostatok peňaženky — 402 preto pri opakovaní nikdy nenastane.

Prakticky: vo svojej DB majte tabuľku (id_faktúry → idempotency_key, document_id, stav). Kľúč vytvorte raz pri prvom pokuse a používajte ho pri všetkých opakovaniach tej istej faktúry.

5.2 Odosielateľ

Odosielateľ sa určí z DIČ (10 číslic) v bloku AccountingSupplierParty. Poradie je záväzné:

1. prvý cbc:CompanyID v poradí dokumentu — v bežnej faktúre je to PartyTaxScheme/CompanyID, teda IČ DPH (napr. SK2020123456);
2. ak jeho hodnota nekončí na 10 číslic, použije sa cbc:EndpointID.

Z víťaznej hodnoty sa berie posledných 10 číslic. Slovenské IČ DPH je SK + DIČ, takže krok 1 vráti DIČ. CompanyID má prednosť pred EndpointID — ak sa líšia, EndpointID sa ignoruje.

Pozor na dlhé identifikátory. PartyLegalEntity/CompanyID nesie IČO (8 číslic) — to je neškodné, lebo neprejde testom na 10 číslic a prepadne sa na EndpointID. Nebezpečný je identifikátor s viac než 10 číslicami, napr. 13-miestny GLN (schemeID="0088"): pravidlo „posledných 10 číslic" z neho vyrobí neplatné DIČ, ktoré navyše zatieni správne EndpointID. Výsledkom je 403 sender_not_found s DIČ, ktoré ste nikdy nevideli. Uistite sa, že prvý CompanyID v bloku odosielateľa je daňový identifikátor.

Toto DIČ musí zodpovedať aktívnej spoločnosti pod peňaženkou tokenu, inak dostanete 403. Pri samofaktúrach (SelfBilledInvoice alebo CustomizationID so „selfbilling") je odosielateľom odberateľ (AccountingCustomerParty).

5.3 Príjemca

Príjemca sa určí z AccountingCustomerParty — z cbc:EndpointID s atribútom schemeID, ktorý tvorí Peppol identifikátor schéma:hodnota, napr. 0208:0987654321. Príjemca musí byť registrovaný a dosiahnuteľný v sieti Peppol (overuje sa SMP vyhľadaním), inak dostanete 422 receiver_unreachable.

5.4 Validácia

Faktúra sa validuje voči vendorovanému Peppol BIS 3.0 / EN 16931 schematronu (rovnaké pravidlá ako oficiálny Peppol validátor). Chyby sa vracajú po jednotlivých pravidlách (id pravidla, závažnosť, XPath umiestnenie, popis). Dokument je platný len ak má nula chýb závažnosti error/fatal (varovania neblokujú).

5.5 Limity a formát

• Content-Type: application/xml, kódovanie UTF-8, telo = surové UBL XML.
• Maximálna veľkosť: 10 MB.
• Rate limit: cca 120 požiadaviek/min na token (429 + Retry-After).
• Timeout klienta: validácia + SMP + odoslanie môžu trvať niekoľko sekúnd — nastavte timeout HTTP klienta veľkoryso (napr. 60 s).

6. Endpointy

Základná cesta: /api/v1/outbox.

6.1 POST /api/v1/outbox/documents — odoslať faktúru (prevzatie zodpovednosti)

Overí, prevezme zodpovednosť a zaradí faktúru na odoslanie.

Hlavičky

Telo: surové UBL XML (Invoice alebo CreditNote).

Odpovede

6.2 POST /api/v1/outbox/documents/validate — nezáväzná validácia (dry-run)

Rovnaké kontroly ako odoslanie, ale bez prevzatia zodpovednosti, bez rezervácie a bez odoslania. Ideálne na testovanie počas integrácie.

Hlavičky: Authorization (povinná), Content-Type: application/xml. Idempotency-Key sa neuplatňuje.

Telo: surové UBL XML.

Odpovede

7. Dátové štruktúry

7.1 CustodyReceipt

Potvrdenie o prevzatí zodpovednosti (odpoveď 202/200). Uložte si documentId na spárovanie s vašou faktúrou.

{
  "documentId": "0b8c7d1e-2f34-4a56-8b9c-1d2e3f4a5b6c", // ID dokumentu v eP24 (uuid)
  "status": "accepted",
  "idempotencyKey": "5980895f-56b6-4a09-a069-e118a146e622",
  "senderDic": "1234567890",
  "receiver": { "scheme": "0208", "value": "0987654321" },
  "documentType": "Invoice",             // "Invoice" | "CreditNote"
  "acceptedAt": "2026-07-08T09:15:06Z"   // ISO 8601 UTC
}

7.2 ValidationReport

Výsledok nezáväznej validácie (odpoveď 200 z /validate).

{
  "valid": false,                         // true len ak errors je prázdne
  "senderDic": "1234567890",              // alebo null
  "senderActive": true,                   // je odosielateľ aktívna spoločnosť pod peňaženkou?
  "receiver": { "scheme": "0208", "value": "0987654321" }, // alebo null
  "receiverReachable": true,              // nájdený v Peppol (SMP)?
  "documentType": "Invoice",              // alebo null
  "errors": [ /* ValidationIssue */ ],
  "warnings": [ /* ValidationIssue */ ]
}

7.3 ValidationIssue

Jedno porušené pravidlo Peppol/EN 16931.

{
  "rule": "PEPPOL-EN16931-R010",          // id pravidla (napr. BR-CO-15, BR-16)
  "severity": "error",                    // "fatal" | "error" | "warning"
  "location": "/Invoice/cac:AccountingSupplierParty/cac:Party/cbc:EndpointID", // XPath alebo null
  "message": "Buyer electronic address MUST be provided."
}

7.4 Problem (RFC 7807)

Chybová odpoveď (application/problem+json). Vetvite podľa poľa code (stabilné, strojovo čitateľné).

{
  "type": "https://www.epodatelna24.sk/errors/insufficient_funds",
  "title": "Insufficient funds",
  "status": 402,
  "code": "insufficient_funds",           // stabilný kód — viď tabuľka nižšie
  "detail": "Wallet balance 0.12 EUR is below the send fee 0.22 EUR."
}

Možné hodnoty code: invalid_xml, unauthorized, insufficient_funds, sender_not_found, sender_not_active, idempotency_conflict, missing_idempotency_key, too_large, validation_failed, receiver_unreachable, rate_limited, upstream_unavailable.

7.5 Problem pri 422

Pri 422 nesie Problem navyše zoznam porušených pravidiel:

{
  "type": "https://www.epodatelna24.sk/errors/validation_failed",
  "title": "Peppol validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The document violates 2 Peppol BIS 3.0 rules.",
  "valid": false,
  "errors": [ /* ValidationIssue */ ],
  "warnings": [ /* ValidationIssue */ ]
}

8. Stavové kódy a spracovanie chýb

Pravidlo: 429 a 503 (a 402 po dobití) sú opakovateľné s rovnakým kľúčom. 400/401/403/422 vyžadujú opravu — neopakuj bezo zmeny.

9. Postup integrácie krok za krokom

1. Vygeneruj token v eP24 (sandbox) a ulož ho bezpečne na serveri.
2. Priprav UBL XML faktúry (Peppol BIS 3.0). Uisti sa, že DIČ odosielateľa a Peppol identifikátor príjemcu sú správne (viď 5.2, 5.3).
3. (Voliteľné, odporúčané počas vývoja) zavolaj POST …/documents/validate a skontroluj valid, senderActive, receiverReachable. Oprav chyby z errors[].
4. Vygeneruj Idempotency-Key (UUID) a ulož ho vo svojej DB spolu s ID faktúry (stav = pending).
5. Zavolaj POST …/documents s hlavičkami Authorization, Content-Type: application/xml, Idempotency-Key a telom = XML. Timeout klienta ~60 s.
6. Vetvi podľa stavu (tabuľka v kap. 8):
   • 202/200 → ulož documentId, stav = accepted. Hotovo.
   • 429/503/402 → naplánuj opakovanie s rovnakým kľúčom (backoff).
   • 422 → zobraz chyby, oprav faktúru, opakuj s rovnakým kľúčom.
   • 400/401/403 → chyba konfigurácie/dát; vyrieš a až potom opakuj.
7. Doručenie nesleduj. Po 202 je faktúra v rukách eP24; stav doručenia používateľ vidí v nástenke eP24.

Tip na spoľahlivosť: ak vám klient spadne po odoslaní a neviete, či požiadavka prešla, jednoducho ju zopakujte s rovnakým kľúčom — dostanete buď pôvodné 200, alebo (ak sa prvý pokus vôbec nespracoval) čerstvé 202.

10. Príklady (curl)

Nezáväzná validácia

curl -X POST "https://epodatelna24-sandbox.vercel.app/api/v1/outbox/documents/validate" \
  -H "Authorization: Token ep24api_test_XXXXXXXX" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

Odoslanie (prevzatie zodpovednosti)

curl -X POST "https://epodatelna24-sandbox.vercel.app/api/v1/outbox/documents" \
  -H "Authorization: Token ep24api_test_XXXXXXXX" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: 5980895f-56b6-4a09-a069-e118a146e622" \
  --data-binary @invoice.xml

Úspech (202):

{ "documentId": "0b8c7d1e-…", "status": "accepted", "senderDic": "1234567890",
  "receiver": { "scheme": "0208", "value": "0987654321" },
  "documentType": "Invoice", "acceptedAt": "2026-07-08T09:15:06Z" }

Neplatná faktúra (422):

{ "code": "validation_failed", "status": 422,
  "detail": "The document violates 1 Peppol BIS 3.0 rule(s).",
  "valid": false,
  "errors": [ { "rule": "BR-16", "severity": "error",
    "location": "/Invoice/cac:InvoiceLine",
    "message": "An Invoice must have at least one Invoice line." } ] }

Bezpečné opakovanie (rovnaký kľúč → 200)

# rovnaká faktúra, rovnaký Idempotency-Key → pôvodné potvrdenie, nie druhé odoslanie
curl -X POST "https://epodatelna24-sandbox.vercel.app/api/v1/outbox/documents" \
  -H "Authorization: Token ep24api_test_XXXXXXXX" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: 5980895f-56b6-4a09-a069-e118a146e622" \
  --data-binary @invoice.xml

11. Rozhodovacia logika (pseudokód)

function odosli(faktura):
    kluc = faktura.idempotency_key or nove_uuid()   # vytvor raz, ulož
    uloz(faktura.id, kluc, stav="pending")

    odpoved = HTTP_POST(base + "/api/v1/outbox/documents",
                        headers = { Authorization: "Token " + TOKEN,
                                    "Content-Type": "application/xml",
                                    "Idempotency-Key": kluc },
                        body = faktura.xml,
                        timeout = 60s)

    switch odpoved.status:
        case 202, 200:
            uloz_document_id(faktura.id, odpoved.body.documentId, stav="accepted")
            return HOTOVO
        case 422:
            zobraz_chyby(odpoved.body.errors)        # oprav XML, potom odosli() znova (rovnaký kľúč)
            return OPRAV
        case 429, 503:
            pockaj(odpoved.headers["Retry-After"] or backoff())
            return odosli(faktura)                    # rovnaký kľúč
        case 402:
            upozorni_dobit_penazenku()                # opakuj neskôr, rovnaký kľúč
            return CAKA
        case 400, 401, 403:
            zaloguj_chybu(odpoved.body.code, odpoved.body.detail)  # vyrieš konfiguráciu/dáta
            return CHYBA

Hotová referenčná implementácia tejto logiky je v lib/ep24-client.ts (funkcie submitDocument, validateDocument, classifySubmit). Serverový proxy (vzor „backend ERP volá API") je v app/actions.ts.

Generovanie klienta: OpenAPI špecifikácia je na …/api-docs/openapi.yaml. Vo väčšine jazykov z nej viete vygenerovať typového klienta (napr. openapi-generator, NSwag pre .NET, openapi-python-client).

12. Kontrolný zoznam pred spustením

• Token uložený bezpečne na serveri, volania idú z backendu (nie z prehliadača).
• Idempotency-Key sa generuje raz na faktúru a je uložený vo vašej DB.
• Ošetrené všetky stavové kódy z kap. 8.
• Opakovania pri 429/503/402 používajú rovnaký kľúč a backoff.
• Timeout HTTP klienta ≥ 60 s.
• documentId z 202/200 je uložené a spárované s vašou faktúrou.
• Otestované v sandboxe end-to-end pred prepnutím na produkciu.
• Produkčný token má prefix ep24api_prod_, sandbox ep24api_test_.

12a. Prostredia v simulátore

Simulátor má prepínač Sandbox / Produkcia / Vlastná URL. Pri každom prostredí zobrazí odkaz na vytvorenie tokenu (Peňaženka → API prístup → Nový token) a očakávaný prefix; ak token prefixu nezodpovedá, upozorní ešte pred odoslaním (token z iného prostredia vráti 401).

Poistky v produkcii

V produkcii sa platná faktúra reálne doručí cez sieť Peppol, prevezme sa zodpovednosť a peňaženka sa zaťaží poplatkom — nedá sa to vziať späť. Preto:

• Simulátor vždy štartuje v Sandboxe a voľbu prostredia neukladá — návrat na stránku, ktorá si potichu pamätá „Produkcia", je presne to, ako sa omylom odošle skutočná faktúra.
• Zobrazí sa výrazný červený banner a v hlavičke červený štítok PRODUKCIA.
• Testovacie scenáre sú vypnuté — ich vzorové faktúry by sa reálne odoslali.
• „Odoslať" je zamknuté, kým používateľ nezaškrtne potvrdenie. Jedno potvrdenie = jedno odoslanie: po odoslaní (aj po načítaní iného dokumentu) sa zaškrtnutie zruší.
• „Odoslať" je červené a premenované na „Odoslať naozaj (produkcia)"; „Validovať" sa stáva primárnou akciou — je nezáväzné, nepreberá zodpovednosť a nič neúčtuje.

12c. Demo firmy vo vyhradenom sandbox tenante

Sandbox vyhradzuje pre simulátor pevný tenant. Voči nemu je nasledujúcich šesť DIČ konštantných — po každom POST /api/sandbox/reset sa obnovia bajt po bajte a sú stabilné aj naprieč nasadeniami.

Vlastná fakturačná identita eP24 (rovnaká pre každý tenant): IČO 54000111, DIČ 2120000111.

Pravidlá

1. Hardcodujte len týchto šesť hodnôt. DIČ nikdy negenerujte — companies.dic je not null unique check (dic ~ '^\d{10}$'), takže neznáme DIČ nerozpozná žiadnu spoločnosť a kolidujúce zlyhá.
2. Len pod vyhradeným uid. Iná relácia (aj anonymná) dostane namespace odvodený z hashtext(uid) a tieto DIČ mať nebude.
3. Maximálne deväť klientov — DIČ je 9 číslic namespace + jednociferný index.
4. Reset je idempotentný, medzi scenármi ho môžete volať voľne.
5. Spoločnosti nevytvárajte priamo — seedujte cez sandbox, nech ostanú konzistentné väzby na členstvo, peňaženku a doručovanie.

Zatiaľ nie sú aktívne. Seed zmena ešte nie je zlúčená a servisné uid ešte nebolo vydané. Vzory preto stále používajú vlastného odosielateľa integrátora. Otvorené otázky (ako sa autentifikovať ako vyhradený tenant a ako demo firmu adresovať ako príjemcu v UBL) sú v MEMO_REPLY_TENANT.md.

Pozor na 9999999997–9999999999. Sú to platné indexy klientov 7–9 vo vyhradenom namespace, dnes neobsadené. Vzor pre sender_not_found preto nepoužíva 9999999999, ale 8888888888 — inak by po doseedovaní troch klientov namiesto 403 vrátil skutočné 202.

12b. Testovacie scenáre v simulátore

Simulátor obsahuje rozbaľovací výber „Testovací scenár“, ktorý načíta vzorové XML (public/invoice.xml a public/samples/) a — pri výsledkoch riadených hlavičkou alebo veľkosťou — pri odoslaní upraví požiadavku tak, aby priviedla presne k danému kódu. Vzory používajú existujúceho odosielateľa Kaviareň Luna s.r.o., DIČ 4706056521 (okrem scenára sender_not_found, ktorý má zámerne neregistrované DIČ). Pri každom scenári sa zobrazí očakávaný stav, code a miera reprodukovateľnosti:

Scenáre označené „deterministické" dajú vždy rovnaký výsledok.

Sandbox vie výsledky vynútiť. Sandbox prijíma hlavičku X-Ep24-Simulate: insufficient_funds | sender_not_active | upstream_unavailable | rate_limited, ktorá vynúti daný výsledok. Simulátor ju pri týchto štyroch scenároch posiela automaticky — takže v Sandboxe dostanete skutočnú odpoveď zo servera, nie lokálnu ukážku. Požiadavka najprv prejde bežnou kontrolou (auth, kľúč, telo) a odpoveď nesie hlavičku X-Ep24-Simulated. V produkcii sa hlavička vôbec nečíta, preto tam ostávajú tieto scenáre nevynútiteľné a odoslanie je pri nich vypnuté.

Pozor: openapi.yaml na sandboxe a v produkcii sa líšia — sandbox dokumentuje X-Ep24-Simulate, produkcia nie. Detaily v MEMO_REPLY.md.

Sandbox nemá register účastníkov (SMP). Mock vracia exists:true pre ľubovoľný identifikátor, takže dosiahnuteľnosť príjemcu sa nevyhodnocuje a 422 receiver_unreachable sa v sandboxe nedá vyvolať vôbec: bez schemeID poruší XML pravidlo BR-63 a validácia (ktorá beží skôr) vráti validation_failed; s platným identifikátorom prejde ako 202. Dôsledok: sandboxové 202 nie je dôkaz, že faktúra prejde v produkcii. Vzory si overujte priamo voči schematronu — npm run validate:fixtures.

Dve rôzne 413: nad ~4,5 MB odmietne telo platforma pred autentifikáciou (text/plain); 4–4,5 MB s platným tokenom vráti API vlastné 413 s telom Problem až po autentifikácii. Pri 413 preto vždy kontrolujte Content-Type, než telo parsujete ako JSON.

Štyri výsledky sa nedajú vynútiť požiadavkou — insufficient_funds (402), sender_not_active (403), rate_limited (429) a upstream_unavailable (503). Ich vzor je platná faktúra s aktívnym odosielateľom, takže skutočné odoslanie by skončilo ako 202 (prijaté) a prevzalo zodpovednosť — čo vyzerá ako falošný úspech. Preto je pri nich tlačidlo „Odoslať“ vypnuté a namiesto neho ponúkame „Zobraziť ukážkovú odpoveď“: telo Problem (RFC 7807) sa vykreslí lokálne, zreteľne označené ako SIMULOVANÉ, aby si ERP vývojár pozrel presný tvar odpovede, na ktorý má vetviť. Tlačidlo „Validovať“ zostáva aktívne — je nezáväzné a pri sender_not_active v poli senderActive priamo uvidíte stav odosielateľa.

13. Časté chyby

• 403 sender_not_found — DIČ odosielateľa nie je registrovaný pod vašou peňaženkou. Vzorové faktúry používajú existujúceho odosielateľa Kaviareň Luna s.r.o., DIČ 4706056521; ak patrí pod inú peňaženku než váš token, nahraďte ho vlastným DIČ. (Scenár „403 · sender_not_found“ používa zámerne neregistrované DIČ 9999999999.)
• Volanie z prehliadača zlyhá (CORS) — API je server-to-server. Volajte z backendu.
• Druhé odoslanie vytvorí duplicitu — nezabudnite posielať rovnaký Idempotency-Key pri opakovaní tej istej faktúry.
• Timeout na strane klienta — validácia + SMP + odoslanie trvajú pár sekúnd; zvýšte timeout na ~60 s.
• 422 receiver_unreachable — príjemca nie je registrovaný v Peppol; overte jeho identifikátor (schéma:hodnota, napr. 0208:…).

Referencie: interaktívna dokumentácia a OpenAPI — /api-docs · /api-docs/openapi.yaml

Otázky → tím ePodatelna24.