API Changelog

Keď v POST /api/v1/invoices/create alebo PUT /api/v1/invoices/{id} variableSymbol nepošlete, uloží sa z číslic čísla faktúry – najviac posledných 10, napr. FA260454 → 260454. Je to ten istý VS, aký PDF a QR kód PAY by square tlačili už doteraz; nový je v UBL (cbc:PaymentID, BT-83), v odpovedi API a v exportoch. Zadaný VS sa nemení, dobropisy ostávajú bez zmeny.

Príde, keď je faktúra úplne uhradená – súčet úhrad dosiahol sumu na úhradu (spárovanie s bankovým pohybom, ručná úhrada, pokladňa, označenie cez API alebo webom). Čiastočná úhrada ju nespustí, opakované označenie už uhradenej faktúry tiež nie; doklady uhradené ešte pred importom do Fakturixu sa neohlasujú. Dáta: invoiceId, invoiceNumber, direction (OUTBOUND/INBOUND), invoiceTypeCode, paidAt (deň úhrady, ktorou faktúra dosiahla sumu na úhradu), paidAmount, amountDue, totalAmount, currency. Prihlásite sa pridaním invoice.paid do eventTypes webhooku; udalosť je aj v pull fronte GET /enterprise/webhook-queue. Odosiela sa až po uložení úhrady.

GET /sapi/document/receive aj GET /sapi/document/receive/{documentId} uvádzali pri každom prijatom doklade typ dokumentu faktúry (Invoice-2::Invoice##…:poacc:billing:3.0::2.1) a proces urn:fdc:peppol.eu:2017:poacc:billing:01:1.0, aj keď išlo o dobropis alebo doklad vyhotovený odberateľom. Teraz ich určuje prijatý doklad, rovnako ako v Peppol obálke: typ dokumentu koreňový element UBL a cbc:CustomizationID (BT-24), proces cbc:ProfileID (BT-23). Dobropis má CreditNote-2::CreditNote##…:poacc:billing:3.0::2.1, doklad podľa Peppol BIS Self-Billing …:poacc:selfbilling:3.0::2.1 s procesom urn:fdc:peppol.eu:2017:poacc:selfbilling:01:1.0. Platí aj pre doklady prijaté skôr. Obsah dokladu v payload sa nemení – vždy to bolo pôvodné prijaté XML.

Zoznam prijatých dokladov obmedzíte na obdobie, napríklad za rok 2025: creationFrom=2025-01-01&creationTo=2025-12-31. Hodnota je xs:dateTime (2025-01-01T00:00:00, so zónou +01:00 alebo Z) alebo xs:date, bez zóny platí čas na Slovensku. Obe hranice sú vrátane: hodnota bez zlomkov sekundy zahŕňa celú sekundu a samotný dátum celý deň. Porovnáva sa creationDateTime, pri zapnutom vydaní až po schválení čas rozhodnutia. Parametre fungujú spolu so status aj s pageToken, neplatná hodnota vráti 400 SAPI-VAL-012. Bez nich sa nič nemení. Ide o rozšírenie Fakturixu, SAPI-SK v1.0.0 ich nemá.

Ak má firma v profile vyplnený zápis v obchodnom alebo živnostenskom registri, e-faktúra vystavená vo Fakturixe ho nesie v cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyLegalForm. Prázdny údaj sa nevypĺňa, pri samofakturácii (firma je kupujúci) sa neuvádza. Pri e-faktúre, ktorú posielate vlastným UBL (SAPI, /invoices/send), sa nič nemení.

Zápis dodávateľa v registri (BT-33): pri faktúre vystavenej vo Fakturixe z profilu firmy v čase vystavenia, pri prijatej faktúre a pri faktúre odoslanej vlastným UBL z cbc:CompanyLegalForm. Ak údaj chýba, pole sa nevracia. Doterajšie polia sa nemenia.

Bločky idú ako výdavkové pokladničné doklady s rozpisom DPH podľa sadzieb (POHODA, Money S3, KROS Omega – import T00), do MRP ako prijaté faktúry (pokladničné doklady MRP z XML neimportuje). Obdobie ako pri faktúrach (year, month, dateFrom + dateTo); nastavenia programu cashAccount, accounting, vatClassification, pre KROS povinné krosEvidence a krosSeries. Bez bločkov v období odpoveď 204, hlavička X-Export-Count = počet bločkov v súbore. CSV je UTF-8 s BOM, s desatinnou čiarkou, dátumom dd.MM.rrrr a novými stĺpcami (ID eKasa, adresa predajne, DPH podľa sadzieb, položky, stredisko, schválenie, upozornenia). Zoznam formátov a stav overenia: GET /api/v1/export/receipts/formats.

POHODA dostávala celú sumu s DPH ako základ v základnej sadzbe, Money S3 a MKsoft neexistujúce prvky. MKsoft pokladničné doklady zo súboru neimportuje – pre MKsoft použite CSV.

ID zákazky – referencia projektu (BT-11). V e-faktúre ide ako cac:ProjectReference, v dobropise ako cac:AdditionalDocumentReference s DocumentTypeCode 50 (Peppol BIS 3.0). Tlačí sa aj v PDF a GET /api/v1/invoices/outbound podľa neho hľadá (q). Referencia zmluvy (BT-12, contractReference) ostáva samostatným poľom.

Nové pole projectReference pri vytvorení a úprave dokladu (ponuka, objednávka, zálohová faktúra, dodací list). Pri prevode ponuka → objednávka → dodací list → faktúra sa prenáša ďalej. Zoznam dokladov má nový parameter q – hľadá v čísle dokladu, názve a IČO odberateľa a v ID zákazky.

Odoslanie cez SAPI-SK vyžaduje rovnaké oprávnenie ako POST /api/v1/invoices/send: kľúč s rolou Účtovník odošle doklad len so zapnutým nastavením firmy „Účtovník smie odosielať faktúry cez PEPPOL“, rola Len čítanie nikdy. Potvrdiť prijatý doklad nesmie rola Len čítanie. Inak odpoveď 403 s kódom SAPI-AUTH-002 (kategória AUTH, retryable=false). Doteraz SAPI-SK rolu API kľúča nekontroloval.

Do kompletného exportu firmy pribudli opakované faktúry, upomienky, sklad (sklady, zásoby, šarže, sériové čísla, skladové doklady, pohyby, inventúry), príplatky a cenové pravidlá produktov, používatelia a roly, AS4 potvrdenia (zoznam aj XML pri doklade), odpovede na faktúry, hlásenia Finančnej správe, účtovníctvo, pripojenia bánk a e-mailových schránok, metadáta API kľúčov a OAuth2 klientov, predplatné a použitie služby, logo a podpis firmy, obrázky produktov a nahraté dokumenty. Heslá, prístupové kódy, tokeny a API kľúče sa neexportujú.

Podmienky použitia štandardu PAY by square (Slovenská banková asociácia) vyžadujú, aby bol každý platobný QR kód označený logom PAY by square podľa dizajn manuálu. S parametrom logo=true dostanete PNG s oficiálnym rámikom a logom (pomer strán 64 : 75, obrázok nedeformujte, QR vrátane tichej zóny má mať pri tlači aspoň 30 mm). Bez parametra endpoint vracia samotný QR ako doteraz – logo PAY by square k nemu potom treba doplniť podľa manuálu. QR má odteraz tichú zónu 4 moduly a úroveň korekcie L podľa špecifikácie PAY by square 1.2.0. QR na PDF faktúrach je s logom vo všetkých šablónach.

salesOrderReference (číslo objednávky u dodávateľa, BT-14), despatchDocumentReference (číslo dodacieho listu, BT-16), receiptDocumentReference (číslo príjemky, BT-15), deliveryLocationId a deliveryLocationScheme (identifikátor miesta dodania, BT-71; predvolená schéma 0088 = GLN). Všetky sú nepovinné a prenášajú sa do e-faktúry Peppol BIS 3.0.

buyersItemId (kód položky odberateľa, BT-156), standardItemId (GTIN, BT-157, schéma 0160), originCountry (krajina pôvodu, BT-159, dvojpísmenový kód) a itemProperties – zoznam {name, value} (doplnkové vlastnosti položky, BT-160/161), napríklad item_type alebo delivery_date podľa odporúčania GS1 Slovakia. Údaje sa zobrazujú aj v PDF faktúry pod názvom položky a GET /api/v1/invoices/{id}/lines ich vracia v buyersItemId, standardItemId a ublExtras (originCountry, attributes).

Firma si v Profile firmy (karta Prístup pre účtovníka) môže zapnúť, aby účtovný program dostal prijatú faktúru až po jej schválení alebo zamietnutí vo Fakturixe. Kým faktúra čaká na schválenie alebo sa rieši, v zozname nie je. Pri zapnutom nastavení je zoznam zoradený a stránkovaný podľa času rozhodnutia, takže klient s uloženým kurzorom neskôr schválenú staršiu faktúru nepreskočí. Predvolene je nastavenie vypnuté a správanie API sa nemení.

Partnerská dokumentácia a GET /api/v1/enterprise/sandbox/info uvádzali, že sandbox sa rozlišuje kľúčom s predponou sk_sandbox_. Sandbox v skutočnosti určuje firma: API kľúč alebo OAuth2 klient vytvorený v testovacej (sandbox) firme pracuje v sandboxe a kľúče žiadnu predponu nemajú. Sandbox je dvojica testovacích firiem – odosielateľ a príjemca – s vymyslenými IČO a Peppol ID (0245:99999999xx). Postup: zaregistrujte si účet (zadarmo), napíšte na support@fakturix.sk, dvojicu pripojíme k vášmu účtu a kľúč si vytvoríte sami v Nastaveniach na karte API kľúč. Správanie API sa nemení.

Pole testParticipants namiesto zdieľaných demo firiem opisuje odosielateľa a príjemcu vášho sandboxu (presné Peppol ID dostanete so sandboxom), sandboxRateLimit uvádza plán sandbox firmy (zvyčajne Enterprise, nie Free) a quickstart zodpovedá postupu vyššie; kľúč overíte cez GET /api/v1/enterprise/account. Štruktúra odpovede ostáva rovnaká.

Ak má firma v profile vyplnenú kontaktnú osobu, telefón alebo e-mail pre odpovede, e-faktúra vystavená vo Fakturixe ich nesie v cac:AccountingSupplierParty/cac:Party/cac:Contact (cbc:Name, cbc:Telephone, cbc:ElectronicMail). Prázdne údaje sa nevypĺňajú a web firmy je len na PDF (pravidlo UBL-CR-143). Pri e-faktúre, ktorú posielate vlastným UBL (SAPI, /invoices/send), sa nič nemení.

Ku každému nášmu odoslaniu (faktúra, MLS odpoveď, Invoice Response) vracia podpísané AS4 potvrdenie (Receipt), ktorým prístupový bod príjemcu potvrdil prevzatie správy: transmissionId, signal (RECEIPT alebo ERROR), receivedAt, endpointUrl, accessPointCertificate, sha256 a samotné XML (xml, v envelope xmlBase64). Potvrdenia ukladáme od 6. 10. 2026, staršie odoslania od mája 2026 sú doplnené. Doterajšie polia sa nemenia.

Udalosti AS4_SENT a MLS_SENT v GET /api/v1/invoices/{id}/peppol-history majú nové pole as4Receipt (id, signal, receivedAt, accessPoint, endpointUrl, sha256). Podľa id sa podpísané potvrdenie stiahne ako XML.

Pole to možno vynechať — e-mail ide na adresu odberateľa z faktúry. Bez subject a body (alebo s useTemplate: true) sa použije šablóna firmy v jazyku faktúry, inak predvolený text. Premenné ako {{cislo}}, {{suma}}, {{splatnost}} alebo {{odkaz}} (odkaz na faktúru online) sa doplnia aj vo vlastnom texte. bccSelf pošle skrytú kópiu na e-mail firmy (vynechané = nastavenie firmy). Doterajšie volania fungujú bez zmeny.

Neplatná adresa vráti 400 s kódom INVALID_RECIPIENT, viac ako 10 príjemcov (Komu, Kópia a skrytá kópia spolu) TOO_MANY_RECIPIENTS. Firma môže odberateľom poslať najviac 500 e-mailov za hodinu a 2 000 za deň, potom 429 EMAIL_LIMIT. Chyby majú popri error aj pole code; chyba poštového servera je 502 SEND_FAILED (predtým 500 s textom servera).

Pri faktúre v cudzej mene od slovenského platiteľa DPH (POST /api/v1/invoices/create, /validate, /send, POST /api/v1/enterprise/documents/convert) Fakturix určí kurz podľa § 26 ods. 1 zákona o DPH: referenčný kurz ECB vyhlásený v deň pred dňom dodania (cez víkend a sviatok posledný vyhlásený, dobropis a ťarchopis s číslom pôvodnej faktúry v poli billingReference preberá jej kurz). UBL potom obsahuje cbc:TaxCurrencyCode = EUR (BT-6) a druhý cac:TaxTotal bez rozpisu s DPH spolu v eurách (BT-111, § 74 ods. 1 písm. i)). DPH v eurách sa počíta zo základu prepočítaného kurzom, rovnako na PDF.

Doteraz takáto faktúra neprešla validáciou (chyba §74/BT-6). Ak kurz ešte nie je vyhlásený (dodanie v budúcnosti, ECB zverejňuje kurzy v pracovné dni okolo 16:00) alebo ECB pre menu kurz nevyhlasuje, vytvorenie skončí 400 s vysvetlením. Faktúry v eurách a faktúry neplatiteľov sa nemenia.

Kurz ECB, ktorým sa DPH faktúry v cudzej mene prepočítala na eurá (jednotiek meny za 1 EUR), a deň jeho vyhlásenia. Pri faktúre v eurách polia chýbajú.

Pri faktúre s uloženým kurzom (taxCurrencyRate) používajú výkazy aj exporty (/api/v1/export/**) ten istý kurz a tú istú DPH v eurách ako faktúra. Ostatné faktúry sa prepočítavajú ako doteraz.

Pole receivedAt teraz uvádza čas, keď doklad prešiel validáciou a prevzali sme ho na doručenie — rovnakú hodnotu, akú uvádza stav dokladu (GET /api/v1/enterprise/documents/{id}/status), s presnosťou na mikrosekundy. Doteraz to bol čas odoslania odpovede, teda až po pokuse o doručenie (o niekoľko sekúnd neskôr). Čas odoslania odpovede ostáva v poli timestamp. Formát (ISO 8601) sa nemení.

Predvolený limit ostáva 10 MB na doklad (UBL XML). Ak potrebujete väčšie doklady, napr. s rozsiahlymi prílohami, limit pre vaše konto na požiadanie zvýšime, najviac na 50 MB. Platí pre POST /sapi/document/send (meria sa XML po dekódovaní base64), POST /api/v1/invoices/send a /validate, každý súbor v POST /api/v1/enterprise/documents/send/batch, POST /api/v1/enterprise/peppol-documents/{typ}/send a /api/v1/enterprise/documents/validate, /preflight a /parse (tieto tri doteraz limit nemali).

Prekročenie: SAPI-SK 400 SAPI-VAL-007 so správou, aký limit má vaše konto; ostatné endpointy 413 s code: DOCUMENT_TOO_LARGE a maxBytes (predtým 400). Hromadné odoslanie: najviac 50 súborov a 75 MB na požiadavku (predtým 20 MB).

Doklady nad 10 MB spracúvame s obmedzenou súbežnosťou. Ak sa iný veľký doklad spracúva dlhšie ako 20 s, dostanete 503 s hlavičkou Retry-After — v SAPI-SK SAPI-TEMP-001 (TEMPORARY, retryable=true), inde code: DOCUMENT_PROCESSING_BUSY. Bežných dokladov sa to netýka.

Telo väčšie ako 75 MB (strop pre 50 MB doklad v base64) odmietneme hneď 413, bez čítania. Verejná validácia bez prihlásenia ostáva na 5 MB dokumentu. Doteraz SAPI payload dlhší ako 20 miliónov znakov (base64 asi 15 MB dokladu) skončil všeobecnou chybou 400 Neplatné telo požiadavky namiesto SAPI-VAL-007.

POST /api/v1/invoices/{id}/attachments: prílohy sa do UBL vkladajú v base64 (o tretinu väčšie), preto spolu s faktúrou musia ostať pod limitom dokladu — pri 10 MB je to 7,1 MB príloh spolu (predtým 10 MB na súbor a 15 MB spolu, čo by vyrobilo doklad nad 20 MB). S vyšším limitom konta úmerne viac; najviac 5 príloh.

GET /enterprise/peppol/participants/{scheme}/{identifier} aj hromadný POST /enterprise/peppol/participants/batch pri nájdenom účastníkovi vracajú názov firmy a dátum registrácie z jeho vizitky v sieti Peppol (Business Card) — na kontrolu, že faktúra pôjde správnej firme. Vizitka je nepovinná: ak ju účastník nemá, pri slovenskom DIČ (0245) doplníme názov z registra finančnej správy a registeredDate vynecháme. Nové registrácie sa vo vyhľadávaní zobrazia hneď (výsledok „nenájdený“ sa pamätá najviac 10 minút).

Parameter scope je nepovinný. Hodnoty podľa SAPI-SK document:send (odosielanie) a document:receive (príjem) sa už neodmietajú; v odpovedi vrátime scope v rovnakom tvare, v akom bol požadovaný. Doterajšie invoices:write invoices:read platia ďalej. Neznámy scope vráti 400 invalid_scope (predtým 401 invalid_client).

Kontroly zákona o DPH sme zosúladili s tabuľkou finančnej správy „Validačné pravidlá“ (v1.11). Dátum dodania patrí do cbc:TaxPointDate (BT-7) a uvádza sa, ak sa líši od dátumu vyhotovenia — ak chýba, validácia vráti len upozornenie (predtým chyba pri slovenskej faktúre bez BT-7 aj BT-72). cac:Delivery/cbc:ActualDeliveryDate (BT-72) ani obdobie fakturácie (BT-73/74) ho nenahrádzajú. Dátum splatnosti (cbc:DueDate, BT-9) už nevyžadujeme; pri sume na úhradu platí štandardné pravidlo BR-CO-25 (splatnosť alebo platobné podmienky). Druhá suma DPH v eurách (BT-111) sa pri faktúre v inej mene vyžaduje len od slovenského platiteľa DPH a IČ DPH dodávateľa sa nevyžaduje, ak je uvedený daňový zástupca.

Okrem konceptu (DRAFT) sa dá zmazať aj vystavená PDF faktúra (ISSUED, nie e-faktúra), ak je posledná vo svojom číselnom rade, nikam neodišla (Peppol, e-mail, odkaz, upomienka, e-shop) a nemá úhradu, pohyb na sklade ani dobropis. Číslovanie sa vráti späť, takže v rade nevznikne diera, a ponuka, z ktorej faktúra vznikla, sa vráti do stavu pred prevodom. Inak odpoveď 400 s dôvodom; takú faktúru opravte dobropisom.

Stav oznámenia údajov z e-faktúry finančnej správe podľa § 85o zákona o DPH: NONE (nevyžaduje sa, napr. dodávateľ nie je platiteľ DPH, alebo ešte nenastalo), PENDING, SENT, ACCEPTED, REJECTED, FAILED. Pri odoslanej faktúre ide o hlásenie dodávateľa, pri prijatej o hlásenie odberateľa. Pole je v GET /api/v1/enterprise/documents/{id}/status (spolu s taxReportSentAt, taxReportConfirmedAt a pri odmietnutí taxReportRejectReason), v zoznamoch /enterprise/outbound/documents, /enterprise/inbound/documents, v hromadnom stave /enterprise/documents/status/batch, v dokladoch spravovaných firiem a v detaile faktúry /api/v1/invoices/{id}. Kým finančná správa nespustí produkčný príjem hlásení, hlásenia sa nevytvárajú a stav je NONE.

Udalosť fs_sr.reported príde, keď finančná správa hlásenie prijme; fs_sr.failed, keď ho odmietne alebo sa ho nepodarí odoslať ani po opakovaných pokusoch. Obsah: invoiceId, invoiceNumber, direction, taxReportStatus, pri odmietnutí reason. Rovnaké záznamy pribudli aj do časovej osi GET /api/v1/enterprise/documents/{id}/events (plus fs_sr.sent pri odovzdaní).

E-faktúru pre Slovenskú informačnú službu (IČO 00826847, DIČ 2020879608) odmietneme skôr, než sa uloží: neodošle sa cez Peppol a nevznikne z nej hlásenie finančnej správe. SAPI vráti 400 SAPI-VAL-100, REST API 400 s vysvetlením, že faktúru treba vystaviť v inej forme; e-shop API ju vystaví v PDF. Vojenské spravodajstvo spadá pod Ministerstvo obrany SR a vlastné identifikátory nemá zverejnené, preto ho rozpoznáme podľa názvu alebo adresy odberateľa; bežné faktúry ministerstvu sa neblokujú. Plnenie spojené s utajovanou skutočnosťou pre iného odberateľa musí posúdiť vystavovateľ a takú faktúru neposielať ako e-faktúru.

Príznak patril pôvodnému hláseniu do IS EFA, ktoré sa už nepoužíva, takže vracal false bez ohľadu na skutočný stav hlásenia. Pole ostáva kvôli spätnej kompatibilite; stav hlásenia čítajte z taxReportStatus.

Validácia doteraz pustila len tvar „2 písmená + 8 až 12 číslic“, takže odmietla napr. rakúske ATU12345678, holandské NL123456789B01, španielske, írske a cyperské IČ DPH (odpoveď 400). Teraz platí: kód štátu (Grécko EL, Severné Írsko XI), za ním 2 až 13 znakov A–Z, 0–9, + alebo *, aspoň jedna číslica. Všetko, čo prešlo doteraz, prejde aj naďalej. Platí pre POST /api/v1/invoices/create, PUT /api/v1/invoices/{id} a POST /api/v1/eshop/invoices.

Kód štátu spotreby (2 písmená, napr. AT; Grécko GR aj EL). Faktúra sa vystaví v osobitnej úprave pre Úniu (§ 68b zákona o DPH): položky v kategórii S so sadzbou DPH štátu spotreby platnou k dátumu dodania – aj u neplatiteľa DPH (sadzba sa nemení na O/0 %). Na faktúre je IČ DPH firmy, a ak ho nemá, IČ DPH pridelené na účely OSS.

Podmienky: firma má v Profile firmy nastavenú registráciu v OSS (od dátumu; bez vlastného IČ DPH aj IČ DPH pre OSS), odberateľ nemá IČ DPH, mena EUR, faktúra ako PDF (einvoice nie je true), štát spotreby je iný ako Slovensko a zhoduje sa s krajinou dodacej adresy (deliveryAddress.country), inak s krajinou odberateľa (customerCountry). Inak odpoveď 400 s popisom. Dobropis (POST /api/v1/invoices/create-credit-note) preberá štát spotreby z pôvodnej faktúry. Odpoveď nesie ossCountry (Grécko ako EL). Faktúry v OSS sa nezahŕňajú do priznania DPH, kontrolného výkazu ani exportov pre účtovné programy – patria do priznania OSS.

Rovnaké pravidlá ako vyššie; štát spotreby sa musí zhodovať s customerCountry. Položky musia mať taxRate – platnú sadzbu DPH štátu spotreby (taxCategoryCode predvolene S). Predvolených 23 % ani nulovanie u neplatiteľa sa pri OSS nepoužijú.

Faktúru pre slovenskú firmu (s IČO) teraz odošleme aj cez sieť Peppol, ak je odberateľ v Peppol registrovaný (adresujeme ju na 0245:DIČ – z customerDic, inak z customerVat). Od 1. 1. 2027 posiela platiteľ DPH faktúry tuzemským firmám cez Peppol vždy, ako to vyžaduje zákon. Faktúry pre fyzické osoby a zahraničných odberateľov ostávajú v PDF. Pole peppolStatus nesie stav odoslania (SENT, DELIVERED…; null = len PDF), nové pole peppolMessage dôvod, prečo faktúra cez Peppol nešla (napr. vaša firma ešte nie je registrovaná na odosielanie). Ak dobrovoľné odoslanie zlyhá, faktúra sa vystaví v PDF. E-mail zákazníkovi pri e-faktúre odchádza až po odoslaní. To isté platí pre /eshop/invoices/batch a Shoptet.

Okrem documentIds (UUID, napr. providerDocumentId z /sapi/document/send) môžete poslať pole invoiceNumbers – čísla faktúr z vášho ERP (cbc:ID v UBL, spravidla rovnaké ako metadata.documentId). Hľadá sa medzi odoslanými dokladmi; ak má rovnaké číslo viac dokladov (napr. odmietnutý a znovu odoslaný), vrátia sa všetky, najnovší prvý. Nenájdené číslo vráti položku {"invoiceNumber": "…", "found": false}. Obe polia sa dajú kombinovať, spolu najviac 100 položiek.

Nové voliteľné parametre issueDateFrom a issueDateTo (ISO dátum, vrátane) – napr. ?issueDateFrom=2026-09-28&issueDateTo=2026-09-28 vráti dnešné doklady so stavom odoslania. Stránkovanie cez cursor funguje ako doteraz; pri ďalších stránkach posielajte rovnaký filter.

Bearer token firmy, ktorej účet je deaktivovaný, vracal na všetkých endpointoch 500 Internal Server Error. Teraz vráti 401 s {"error": "invalid_token", "error_description": "Company account is deactivated"} a POST /sapi/auth/token pre takýto účet token nevydá (401 invalid_client).

Tuzemskú e-faktúru platiteľa DPH na príjemcu, ktorý nie je registrovaný v Peppol (SML), neodmietame: uložíme ju so stavom FAILED a údaje z nej sa podľa § 85o zákona o DPH oznámia Finančnej správe (FAQ FS k eFaktúre, príklad č. 9) – povinnosť odosielateľa je splnená odovzdaním doručovacej službe. POST /sapi/document/send to však vracal ako 400 SAPI-VAL-100 bez identifikátora dokladu, čo vyzeralo ako odmietnutie.

Teraz vráti 202 so status: ACCEPTED a providerDocumentId ako pri bežnom prijatí (podľa SAPI-SK 202 potvrdzuje len technické prijatie, nie doručenie). Výhradu nesie nové pole warnings: [{"code": "SAPI-WARN-001", "message": "Príjemca … nie je registrovaný v Peppol …"}]. Odberateľovi doručte faktúru iným kanálom (napr. PDF e-mailom); stav dokladu je FAILED (GET /api/v1/invoices/{id}/status, webhook invoice.send_failed). Bez výhrady pole warnings v odpovedi nie je. Pri neplatiteľovi DPH (dodávateľovi) a pri cezhraničnej faktúre (bez oznamovacej povinnosti) sa doklad neukladá a odpoveď ostáva 400 SAPI-VAL-100. Text upozornenia radí doručiť faktúru iným kanálom ako XML Peppol BIS 3 a PDF – faktúrou platiteľa DPH je e-faktúra, PDF je len jej vizualizácia.

Sandbox doteraz prijal doklad na akéhokoľvek príjemcu. Teraz pred odoslaním overí v produkčnom Peppole (SML/SMP), či je príjemca registrovaný – nič pritom neodosiela a nič neoznamuje Finančnej správe. Príjemca mimo Peppolu dostane rovnakú odpoveď ako v produkcii (platiteľ DPH: 202 s SAPI-WARN-001 a textom doplneným o „Sandbox: nič sa neodosiela ani neoznamuje.“; neplatiteľ: 400 SAPI-VAL-100). Doklad, v ktorom odberateľ nemá Peppol identifikátor (DIČ ani EndpointID), sandbox odmietne rovnako ako produkcia. Registrovaný príjemca dostane bežné 202. Doklady na sandbox účastníkov Fakturixu (0245:99999999xx) sa doručujú ako doteraz. Či je vaša sandbox firma platiteľ DPH, určuje nastavenie v Profile firmy (vatPayerSetting).

UBL, ktoré generuje Fakturix, malo pri poznámke cbc:Note atribút languageID. Syntaktické pravidlá EN 16931 ho v UBL nepripúšťajú, preto validátory, aj u príjemcu, hlásili pri každom takom doklade varovanie [UBL-DT-19]. Doklad bol napriek tomu platný. Odteraz atribút neposielame, text poznámky ostáva. Týka sa faktúr a dobropisov vytvorených v aplikácii alebo cez /api/v1/invoices (POST /api/v1/invoices/{id}/validate už toto varovanie nevracia) a výstupu POST /api/v1/enterprise/documents/convert. Doklady, ktoré posielate ako vlastné UBL (SAPI, POST /api/v1/invoices/send), sa zmena netýka.

Pole language ďalej určuje jazyk PDF a e-mailu, v UBL sa neprenáša.

Peppol BIS 3.0 dĺžku textových polí ani identifikátorov neobmedzuje, my sme ich však ukladali do stĺpcov s pevnou dĺžkou. Platný doklad s dlhším popisom položky (BT-154) alebo poznámkou k položke (BT-127) preto POST /sapi/document/send neprijal: najprv s chybou 409, od 25. 9. s 422 SAPI-VAL-011. Teraz ukladáme celé hodnoty všetkých textových polí a identifikátorov z UBL (názov, popis a kódy položky, poznámky, čísla objednávky, zmluvy a projektu, referencia platby, názvy a identifikátory strán, dôvody oslobodenia a zliav), takže SAPI-VAL-011 by sa pri nich už nemal vyskytnúť. Platí pre SAPI, /invoices/send, enterprise dávky aj doklady prijaté cez Peppol. Doklady odmietnuté s SAPI-VAL-011 môžete poslať znova.

Ak by uloženie odosielaného dokladu predsa zlyhalo, zistíme to ešte pred odoslaním do siete Peppol: doklad sa neodošle, takže opakovanie požiadavky u príjemcu nevytvorí duplikát.

Niektoré polia prijatých dokladov sme pri ukladaní potichu skracovali: referenciu platby (BT-83, variabilný symbol) na 50 znakov, referenciu zmluvy a projektu (BT-12, BT-11) a názov účtu (BT-85) na 200, právnu formu dodávateľa (BT-33) na 500 a údaje daňového zástupcu, príjemcu platby (BT-59 až BT-63) a kódy položky (BT-156, BT-157) na 30 až 200 znakov. Odteraz sa ukladajú celé, v Enterprise API, v aplikácii, PDF aj exportoch. SAPI /document/receive/{documentId} vracia ako doteraz pôvodné UBL. Už uložené doklady ostávajú bez zmeny.

Každý prijatý dokument spracúvame samostatne: chyba pri spracovaní jedného už nezdrží ostatné, problematický sa skúša znova s narastajúcim odstupom.

Podľa SAPI-SK („ascending order by received date, oldest first“) sú doklady zoradené od najstaršieho podľa času prijatia. Doteraz sme vracali najnovšie prvé a pageToken bolo číslo stránky, takže doklad prijatý počas stránkovania posunul ostatné: klient niektorý videl dvakrát a iný mohol preskočiť. nextPageToken je teraz nepriehľadný kurzor – pošlite ho späť ako pageToken, nič z neho neskladajte. Posledná stránka nextPageToken nemá. Starý číselný token (aj 0 z príkladu v dokumentácii) začne zoznam od začiatku, chybu nevráti.

Filter status sa uplatňuje pred stránkovaním, takže každá stránka obsahuje až limit zodpovedajúcich dokladov (doteraz mohla prísť aj prázdna stránka s nextPageToken). Neplatná hodnota status vráti 400 SAPI-VAL-008 namiesto prázdneho zoznamu. Zoznam obsahuje len doklady prijaté cez Peppol, teda s UBL payloadom (rovnako ako PEPPOL Schránka). Ručne zadané a naskenované prijaté faktúry payload nemajú, a preto v ňom už nie sú.

V metadátach je receiverParticipantId vyplnený vždy (doteraz býval null) a senderParticipantId sa berie z Peppol identifikátora dodávateľa v doklade (EndpointID) namiesto skladania 0245:<IČO>.

Odporúčaný postup: pýtajte sa so status=RECEIVED, doklad spracujte a potvrďte cez /acknowledge. Potvrdené doklady zo zoznamu vypadnú.

SAPI-SK mapuje HTTP 409 na kategóriu PROCESSING. SAPI-CONF-001 sme doteraz vracali s kategóriou CONFLICT, ktorá v enume SAPIError.category nie je, takže klient vygenerovaný zo špecifikácie takú odpoveď nemusel vôbec načítať. SAPI-CONF-002 (Idempotency-Key s iným obsahom) mal VALIDATION. Obe majú teraz PROCESSING. Kódy a retryable ostávajú: už odoslaný doklad retryable: false, súbežná požiadavka na ten istý doklad retryable: true.

Doklad s textom dlhším, než vieme uložiť (napr. popis alebo poznámka položky nad 1000 znakov), dostával chybne 409 „skúste o chvíľu znova“ s retryable: true, hoci opakovanie nemohlo pomôcť. Teraz dostane 422 SAPI-VAL-011 (kategória VALIDATION, retryable: false).

Špecifikácia vyžaduje, aby checksum, ak ho posielate, bol SHA-256 payloadu (64 znakov, malé písmená) a aby X-Peppol-Participant-Id bolo Peppol ID vašej organizácie: pri odoslaní zhodné s metadata.senderParticipantId (ak ho posielate), pri príjme zhodné s príjemcom dokladu. Doteraz sme to neoverovali. Od tohto nasadenia výsledok len zaznamenávame, požiadavky neodmietame.

Odmietať ich začneme až po ohlásení termínu tu a e-mailom. Potom checksum, ktorý nesedí, vráti 400 SAPI-VAL-009. Hlavička inej organizácie vráti 403 SAPI-AUTH-001 (kategória AUTH) a nezhoda s metadata.senderParticipantId vráti 400 SAPI-VAL-010. Uznáme odtlačok veľkými písmenami a pri payloadEncoding: "base64" odtlačok dekódovaného XML aj prenášaného base64 reťazca. Ak checksum nepočítate, pole vynechajte.

POST /sapi/document/send doteraz porovnával len kľúč: iný doklad odoslaný s už použitým kľúčom dostal 202 s providerDocumentId pôvodného dokladu a nič sa neodoslalo. Podľa SAPI-SK teraz porovnávame celé telo požiadavky – metadata (vrátane creationDateTime), payload, payloadFormat, payloadEncoding a checksum.

Rovnaký kľúč s rovnakým telom do 24 h vráti pôvodnú odpoveď s hlavičkou Idempotency-Replayed: true. Rovnaký kľúč s iným telom vráti 409 s kódom SAPI-CONF-002 (kategória VALIDATION, retryable: false) a v details je providerDocumentId pôvodného dokladu. Pri opakovaní po výpadku spojenia posielajte identickú požiadavku, nový alebo opravený doklad s novým kľúčom.

Pri slovenských faktúrach s kategóriou E sme vždy vyžadovali aj textový dôvod (BT-120 cbc:TaxExemptionReason), takže doklad s kódom VATEX bez textu skončil chybou BT-120/SK. Teraz platí EN 16931 (BR-E-10: kód alebo text) a odporúčanie FS SR používať primárne BT-121. Text ostáva povinný tam, kde § 74 ods. 1 zákona o DPH predpisuje konkrétnu slovnú informáciu: pri kategórii AE („prenesenie daňovej povinnosti“) a pri kódoch úpravy zdaňovania prirážky VATEX-EU-F, VATEX-EU-I a VATEX-EU-J („úprava zdaňovania prirážky – použitý tovar“, „– umelecké diela“, „– zberateľské predmety a starožitnosti“).

Popisy POST /sapi/document/send, /enterprise/documents/validate, /preflight a /public/validate odkazujú na štruktúru Peppol BIS Billing 3.0 (faktúra, dobropis) a majú vložené platné vzory (faktúra aj dobropis, v SAPI aj ako base64). Overené vzory na stiahnutie: faktúra 380, dobropis 381. POST /enterprise/documents/convert má zdokumentovanú schému tela (ConvertRequest s objektom invoice) a príklady pre oba smery.

Riadok so zľavou (lines[].discount) mal v UBL zníženú sumu, ale chýbal mu cac:AllowanceCharge, takže výsledok neprešiel validáciou (PEPPOL-EN16931-R120). Teraz ho convert vytvorí rovnako ako vystavenie faktúry. Typ dokladu sa berie z invoiceTypeCode tela, a ak chýba, z invoice.invoiceTypeCode (predtým sa ignoroval a vždy vzniklo 380).

Zľavy a prirážky na celý doklad v POST /api/v1/invoices/create, POST /api/v1/invoices/create-credit-note a PUT /api/v1/invoices/{id} sa doteraz ignorovali – faktúra vznikla v plnej sume. Od teraz sa uložia a znížia (zvýšia) základ dane svojej skupiny DPH (BT-116 = ∑ BT-131 − BT-92 + BT-99), sumu BT-107/108 a BT-109 a prenesú sa do UBL, PDF, exportov aj TDD – v súlade s transpozíciou Peppol BIS v1.11 (FS SR, 11. 9. 2026).

Nové nepovinné polia baseAmount (BT-93) a percentage (BT-94): ak sú uvedené obe, amount sa musí rovnať baseAmount × percentage / 100 (tolerancia 0,02, PEPPOL-EN16931-R040). Pole taxCategoryCode je potrebné, ak má faktúra položky s viacerými sadzbami DPH; kategória a sadzba musia patriť niektorej položke faktúry. Inak odpoveď 400 s popisom.

Pri PUT: pole vynechané = uložené zľavy/prirážky ostanú; pole so zoznamom (aj prázdnym) ich nahradí. V detaile faktúry majú položky documentAllowancesCharges navyše taxCategoryCode, baseAmount a percentage.

Pri faktúrach vytvorených cez API alebo formulár obsahovalo allowanceTotal súčet riadkových zliav. Podľa EN 16931 patria do BT-107 len zľavy na úrovni dokladu – riadkové zľavy sú už v čistých sumách riadkov (lineExtensionAmount, BT-131). Hodnota je opravená aj pri existujúcich faktúrach; sumy faktúr (základ, DPH, celkom) sa nemenia. Riadkové zľavy nájdete v discountAmount jednotlivých riadkov.

UBL e-faktúry odoslanej cez POST /api/v1/invoices/{id}/send teraz obsahuje uhradenú zálohu (BT-113, PayableAmount už po jej odpočte), platobné podmienky (BT-20) a názov účtu (BT-85). taxRepresentative (BG-11) z requestu sa ukladá a je v UBL; pri PUT vynechané pole = ponechať, objekt = nahradiť, prázdny objekt = odstrániť.

V /api/v1/documents sa ukladá riadková zľava lines[].discount (suma v €, rovnako ako pri faktúre) a nové pole discountPercent (zľava na celý doklad v %). Doklad vracia discountPercent a allowanceTotal; pri prevode na faktúru sa zľavy prenesú.

Platí pre POST /api/v1/invoices/send a /api/v1/invoices/validate, pre každý súbor v POST /api/v1/enterprise/documents/send/batch a pre POST /api/v1/enterprise/peppol-documents/{typ}/send. Limit sa meria na XML súbore. SAPI-SK (/sapi/document/send) mal limit 10 MB už doteraz, takže oba kanály sú teraz rovnaké.

Pri hromadnom odoslaní ostáva najviac 50 súborov a 20 MB na jednu požiadavku. Validácia bez prihlásenia (/api/v1/invoices/validate bez tokenu a /api/v1/enterprise/public/validate) ostáva na 5 MB.

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.