API Changelog

Podľa § 74 ods. 1 písm. a) a b) zákona o DPH je IČO povinnou náležitosťou, ak bolo subjektu pridelené. Peppol BIS to nevynucuje, preto doteraz prešla aj faktúra bez neho. Od teraz kontrolujeme cac:PartyLegalEntity/cbc:CompanyID – BT-30 pri dodávateľovi a BT-47 pri odberateľovi.

Kontrola sa spúšťa len pri slovenskej strane, ktorá má IČ DPH. Subjektov bez IČ DPH sa netýka – tí IČO pridelené mať nemusia (v registri Finančnej správy je takých 11,5 %, typicky prenajímatelia). Zahraničné strany neobmedzuje vôbec.

Týka sa odosielania a validácie; na prijaté doklady sa nevzťahuje, takže príjem od iných poskytovateľov zostáva nedotknutý.

Udalosť sa od teraz zapisuje nezávisle od toho, či a komu sa podarila doručiť, takže prežije aj vyčerpanie všetkých pokusov o doručenie. Po výpadku vášho endpointu si zmeškané udalosti stiahnete sami: zapamätáte si najvyššie sequence z dávky a ďalším volaním pýtate ?since=<to číslo>. Poradie je vzostupné, udalosti uchovávame 30 dní. Partnerský kľúč dostane aj udalosti klientskych firiem – rozlíšite ich podľa tenantId.

Na vyžiadanie odošleme konkrétnu udalosť ešte raz na všetky zapnuté endpointy, ktoré daný typ odoberajú – hodí sa po oprave chyby na vašej strane, keď nechcete čakať na ďalšie automatické opakovanie. Cudzia udalosť vráti 404.

Pri opakovanom pokuse sa telo webhooku omylom zabalilo do ďalšej obálky – v poli data ste namiesto dát dostali celú pôvodnú správu ako reťazec. Opravené: opakovanie posiela bajtovo identické telo vrátane pôvodnej časovej pečiatky, pretože ide o ten istý pokus o doručenie tej istej udalosti.

Namiesto 3 pokusov v okne 6 minút teraz opakujeme 7-krát s odstupmi 1, 5, 15, 60, 180 a 360 minút (okno ~10 hodín), s rozptylom ±20 %, aby po návrate vášho endpointu nedorazilo všetko naraz. Po vyčerpaní pokusov sa doručenie označí ako mŕtve; po 20 mŕtvych doručeniach za sebou endpoint automaticky vypneme – zapnete ho späť cez PATCH /api/v1/webhooks/{id}. Udalosti medzitým nezanikajú, zostávajú vo fronte.

Pribudli X-Webhook-Id, X-Webhook-Sequence, X-Webhook-Attempt, X-Webhook-Timestamp a X-Webhook-Signature-V2 (HMAC-SHA256 nad timestamp.telo, chráni pred opakovaným prehratím odchytenej požiadavky). Tvar tela {event, timestamp, tenantId, data} aj pôvodná hlavička X-Webhook-Signature zostávajú bez zmeny – existujúce integrácie netreba upravovať.

Vo fronte /api/v1/enterprise/webhook-queue sa doteraz nepotvrdené udalosti nemazali vôbec. Od teraz platí v oboch frontách rovnaká retencia: udalosti staršie ako 30 dní mažeme bez ohľadu na to, či ste ich potvrdili. Ak vám integrácia vypadne na dlhšie, staršie udalosti už nedobehnete – pri bežnej prevádzke sa vás to nedotkne, keďže doručovanie aj tak opakujeme len ~10 hodín.

Na dobehnutie zmeškaných udalostí existujú dve cesty a pre nové integrácie odporúčame tú novú. GET /api/v1/webhooks/events pracuje s kurzorom – pýtate si udalosti od posledného spracovaného poradového čísla, nič nepotvrdzujete a udalosti u nás držíme 30 dní. Staršia GET /api/v1/enterprise/webhook-queue stojí na potvrdzovaní: vráti nepotvrdené a vy ich po spracovaní odACKujete; nepotvrdené záznamy sa v nej hromadia, kým to neurobíte. Obe zostávajú podporované a nič nemusíte prerábať – nepoužívajte ich však naraz, každá sleduje priebeh po svojom a tú istú udalosť by ste spracovali dvakrát.

GET /api/v1/webhooks/{id}/deliveries zapisovala pri úspechu natvrdo 200 bez ohľadu na to, čo endpoint vrátil. Teraz je tam skutočný kód, takže sa na históriu dá spoľahnúť ako na auditovateľný záznam.

Pole payloadEncoding sa dovtedy nečítalo a payload sme vždy brali ako čisté XML – kto poslal base64 podľa špecifikácie SAPI-SK, dostal mätúcu hlášku o nerozparsovateľnom XML. Teraz base64 dekódujeme. Ak payload nezačína na < a dá sa dekódovať na XML, zvládneme to aj bez uvedeného kódovania. Nový kód SAPI-VAL-006 hovorí, že bolo deklarované base64, ale výsledok nie je XML (typicky skrátený reťazec). Limit 10 MB sa teraz meria na XML po dekódovaní, nie na prenosovom reťazci – veľké doklady tak zbytočne nenarazia na SAPI-VAL-007. Posielanie čistého XML funguje bez zmeny.

Biznis odpoveď na prijatý doklad (AP = akceptované, RE = zamietnuté) sa teraz odosiela ako plnohodnotný Invoice Response (urn:fdc:peppol.eu:poacc:trns:invoice_response:3) namiesto transportného MLS. Pre protistranu je to štandardná, korelovateľná odpoveď. Request aj response formát endpointu sa nemení; text v message teraz znie „Invoice Response … naplánovaný na odoslanie".

Transportné potvrdenie (MLS AB) posiela náš Access Point automaticky hneď pri prijatí dokladu – nie je to biznis odpoveď príjemcu. Použite AP alebo RE. Kódy IP/UQ/CA/PD zatiaľ vracajú 501 (bez zmeny). Rovnako POST /invoices/inbound/{id}/confirm teraz namiesto MLS odosiela Invoice Response AP/RE. Endpointy /documents/inbox/{id}/acknowledge a /inbound/documents/{id}/ack fungujú bez zmeny requestu: default AB = idempotentné potvrdenie prevzatia dokladu (bez sieťovej správy), AP/RE odošlú Invoice Response.

Ak protistrana odpovie na vami odoslaný doklad biznis Invoice Response-om s iným kódom než AB/AP/RE, stav sa korektne uloží a propaguje (status endpointy, inbox, webhook invoice.mls_status_changed). Predtým sa takáto odpoveď nespracovala.

Ak sa MLS (AB/RE) k prijatému dokladu nepodarí doručiť (výpadok SMP alebo AS4 protistrany), doručenie sa automaticky opakuje. Bez zmeny API kontraktu – zvyšuje spoľahlivosť potvrdení pre odosielateľov.

Opakovaný acknowledge už potvrdeného dokladu vracal 500 (SAPI-PROC-002, retryable: true) — klient rešpektujúci retryable tak retryoval donekonečna. Teraz vráti 200 ACKNOWLEDGED. Neexistujúci dokument zároveň vracia deklarovanú 404 (SAPI-NOT-001) namiesto 500.

Ak predchádzajúci pokus o POST /sapi/document/send skončil v stave FAILED, nový pokus s tým istým dokladom prejde čisto. Doklad, ktorý už bol úspešne odoslaný, vráti 409 (SAPI-CONF-001, resp. DUPLICATE_DOCUMENT v Enterprise API) so zrozumiteľnou správou – pre opravu vystavte doklad s novým číslom.

Po potvrdení cez /document/receive/{id}/acknowledge sa doklad presunie zo status=RECEIVED pod status=ACKNOWLEDGED. Predtým sa stav odvodzoval len zo sieťového MLS, takže potvrdený doklad sa vracal opakovane.

Opakované POST /sapi/document/send s tým istým Idempotency-Key (v rámci 24 h) už dokument neodošle znova – vráti pôvodnú odpoveď s hlavičkou Idempotency-Replayed: true. Bezpečné opakovanie po výpadku siete bez rizika duplicitnej PEPPOL transmisie.

Token sa dá obnoviť cez POST /sapi/auth/renew (rotácia refresh tokenu). Pole refresh_token berte ako voliteľné – pri client_credentials si access token kedykoľvek vyžiadate aj znova cez /auth/token.

Hlavička v POST /sapi/document/send akceptuje ľubovoľný unikátny reťazec (1–200 znakov), takže môžete použiť napríklad číslo faktúry. UUID naďalej platí.

Pri nenájdení účastníka vrátia GET /enterprise/peppol/participants/{scheme}/{id}, POST /enterprise/peppol/capabilities a GET /enterprise/company/lookup/{ico} s parametrom soft404=true HTTP 200 s found=false (bez parametra ostáva 404, ktoré tiež nesie found=false v tele).

POST /enterprise/documents/validate, /enterprise/public/validate a /enterprise/documents/preflight prijímajú JSON telo { "payload": "<XML>", "payloadFormat": "XML" } popri pôvodnom application/xml. Konzistentné so /document/send.