Ingest vydaných faktúr: kontrakt pre váš systém
Stav: pilot. Toto rozhranie nie je verejné, nie je v cenníku a nie je na webe. Kľúč k nemu vydávame menovite a vy ste prvý, kto ho má. Znamená to dve veci naraz: máte ho bez príplatku k predplatnému, a vaše pripomienky ho ešte stihnú zmeniť, kým sa jeho tvar ustáli.
Je to jednosmerný vstup: váš systém do Bezúčta zapisuje vydané faktúry. Čítať cezeň nejde nič, ani vaše vlastné doklady, a to je zámer, nie chýbajúca funkcia.
---
1. Čo to robí a čo nie
Jednosmerný vstup: cudzí systém po vystavení faktúry zavolá Bezúčto, doklad vznikne a zaúčtuje sa (rovnaké zápisy, aké vyrobí faktúra vystavená v appke: 311 / 604 alebo 602 / 343). Ktorý z výnosových účtov to bude, rozhoduje typ položky: tovar → 604, sluzba → 602. Keď typ nepošlete, berie sa sluzba a tržby vám sadnú na 602. Pre e-shop, ktorý predáva tovar, je to zlý riadok vo výkaze ziskov a strát. Od 18. 9. 2026 sa to už neudeje ticho: doklad vznikne, ale v odpovedi nájdete varovanie POLOZKA_BEZ_TYPU s číslami položiek, ktorých sa to týka. Neznámu hodnotu (typ: "shipping") odmietame rovno (400). Posielajte typ vždy.
| Vie | Nevie |
|---|---|
| založiť vydanú faktúru s vlastným číslom | čokoľvek prečítať (ani vlastné faktúry) |
| položkový rozpad | stornovať doklad |
| zaúčtovať doklad | poslať faktúru e-mailom odberateľovi |
spôsob úhrady (sposobUhrady) | čiastočnú úhradu, zápočet |
označiť doklad za zaplatený pri založení (uhradena) | prijaté doklady, banku, mzdy, nastavenia |
| ohlásiť úhradu neskôr, k vlastnému dokladu (sekcia 5) | siahnuť na doklad, ktorý vystavil iný, stále aktívny kľúč |
vystaviť dobropis k vlastnému dokladu: plný, alebo čiastočný s hlavičkou Idempotency-Key (sekcia 6) | dobropis k faktúre v režime OSS § 68b |
Pravý stĺpec má spoločný dôvod a stojí za to ho povedať raz: kľúč nesiaha na doklad, ktorý patrí inému aktívnemu kľúču, a nerobí rozhodnutia, len hlási fakty. Čiastočná úhrada a zápočet sú rozhodnutia o tom, ako sa doklad uzatvorí; tie patria človeku v aplikácii. Výber vrátených položiek pri dobropise je od 4. 11. 2026 fakt, ktorý poznáte vy (čo odberateľ vrátil), a kľúč ho smie nahlásiť, ale len s vaším jedinečným identifikátorom vratky (hlavička Idempotency-Key, sekcia 6): bez neho by zopakované volanie vystavilo druhý dobropis.
Úhradu, ktorá príde až po vystavení faktúry, páruje Bezúčto aj samo z bankového výpisu (CSV, SEPA XML camt.053, priebežne z notifikačných e-mailov internetbankingu) podľa variabilného symbolu, hlásiť ju cez rozhranie treba len tam, kde peniaze cez bankový účet neprejdú v podobe, ktorú viete spárovať (typicky súhrn z platobnej brány).
---
2. Prístupový kľúč
Vydáva sa volaním POST /api/agents so scope faktura_ingest, faktura_uhrada a faktura_dobropis a vráti sa jedenkrát: samotný token sa nikde neukladá a druhýkrát ho nezobrazíme. Pri strate sa vydáva nový a starý sa zruší; obnoviť pôvodný nie je cesta, ktorú by aplikácia ponúkala.
⛔ Oprávnenie k existujúcemu kľúču pridať nevieme, ani my. Rozsah je súčasťou podpísaného tokenu, ktorý ste dostali pri vydaní; zmena riadku v našej databáze by na ňom neurobila nič. Kľúč vydaný pred 18. 9. 2026 preto vie len zakladať faktúry a kľúč spred 19. 9. 2026 nevie dobropisovať, nech sa stane čokoľvek. Jediná cesta je vydať nový kľúč a starý zrušiť, a keď to robíte, urobte to raz a naraz, nie po jednom oprávnení (doklady starého kľúča nový kľúč prevezme až vtedy, keď starý zrušíte; viď sekciu 5).
Vydáva sa v aplikácii: Nastavenia → Prístupové kľúče. Panel kľúč vydá, vypíše ho jedenkrát, napíše, že neexpiruje, a dá ho zrušiť. Kľúč si vydáva majiteľ účtu sám. Účtovník, ktorý sa na účet pozerá cez klientsky prístup, kľúč vydať nevie a zoznam kľúčov sa mu ani nenačíta.
Kto radšej volá rozhranie priamo, volanie nižšie stále funguje a chce prihlasovací token majiteľa účtu.
POST /api/agents
{ "label": "e-shop peki.sk", "scope": ["faktura_ingest", "faktura_uhrada", "faktura_dobropis"] }
→ { "id": "ag_…", "token": "eyJ…", "expires_in_seconds": null, "expiruje": false }
- Kľúč neexpiruje (
expiruje: false). Server e-shopu pri sebe nemá človeka, ktorý by ho obnovoval; expirácia by integráciu raz v tichosti zabila a prázdna kniha nevyzerá ako porucha. Platí to pre tieto tri oprávnenia a len pre ne. Pridajte k nim čokoľvek ďalšie (napríkladwrite) a kľúč je zase na 24 h. - Odvoláva sa okamžite:
DELETE /api/agents/:id. Kontroluje sa v DB pri každom volaní. - Zmena hesla, zapnutie 2FA a „odhlásiť všade" kľúč tiež zabijú (claim
tv). Je to zámer: inak by odhlásenie nechalo nažive poverenie vydané počas kompromitácie. Odosielateľ vtedy dostane401s hláškou, že opakovanie nepomôže a treba vydať nový kľúč. ⚠ Taký kľúč pritom nie je odvolaný, len prestal platiť. V paneli ho ďalej uvidíte medzi aktívnymi, hoci volania s ním už neprejdú. Po zmene hesla si preto rovno vydajte nový a starý zrušte. Čas posledného použitia sa zapisuje až ZA touto kontrolou, takže mŕtvy kľúč sa nikdy netvári ako práve použitý. - Kľúč je viazaný na jeden účet. Neexistuje spôsob, ako ním siahnuť na cudzí.
Posiela sa v hlavičke: Authorization: Bearer <token>.
---
3. Endpoint
POST https://www.bezucto.sk/api/faktury
Authorization: Bearer <token>
Content-Type: application/json
⚠ Host je www.bezucto.sk, nie bezucto.sk. Apex odpovedá 301 na www a pri presmerovaní medzi dvoma rôznymi hostiteľmi väčšina klientov (vrátane curl bez --location-trusted) zahodí hlavičku Authorization. Volanie potom skončí na 401 a vyzerá to ako neplatný kľúč, hoci kľúč je v poriadku. Časť klientov navyše pri 301 prepne POST na GET, takže sa nič nezaloží a nič sa nenahlási. Zmerané 17. 9. 2026: POST https://bezucto.sk/api/faktury → 301 → https://www.bezucto.sk/api/faktury. Volaj www priamo a presmerovanie nenasleduj.
Príklad: tuzemská faktúra, dve položky
{
"cislo": "ESHOP/2026/000123",
"datum": "2026-09-17",
"datum_dodania": "2026-09-17",
"splat": "2026-10-01",
"mena": "EUR",
"odberatel": {
"nazov": "Kupujúci s.r.o.",
"ico": "12345678",
"dic": "2020123456",
"ic_dph": "SK2020123456",
"ulica": "Hlavná 1", "obec": "Bratislava", "psc": "81101", "krajina": "SK"
},
"dphSadzba": 23,
"sposobUhrady": "karta",
"uhradena": true,
"datum_uhrady": "2026-09-16",
"polozky": [
{ "nazov": "Tovar A", "mn": 2, "cena": 41.50, "dph": 23, "mj": "ks", "typ": "tovar" },
{ "nazov": "Doprava", "mn": 1, "cena": 4.90, "dph": 23, "mj": "ks", "typ": "sluzba" }
]
}
Príklad: faktúra v cudzej mene
Líši sa dvoma poľami navyše oproti prvému príkladu: mena a kurz. kurz je EUR za jednu jednotku cudzej meny; doklad ostane v korunách, účtovný zápis vznikne v eurách (suma × kurz), lebo účtovníctvo sa vedie v eurách: § 4 ods. 7 zákona č. 431/2002 Z. z. Ostatné polia sa riadia rovnako ako pri tuzemskej faktúre: odberatel.nazov je povinný aj tu (viď tabuľka nižšie) a polozky[].dph musí byť platná slovenská sadzba (23 tu, aj keď je faktúra v korunách). Cudziu sadzbu prijíma len režim oss_68b (sekcia 9), mena sama o sebe režim nemení. Príklad je tuzemské dodanie fakturované v cudzej mene. Dodanie tovaru platiteľovi v inom členskom štáte je oslobodené (§ 43 zákona č. 222/2004 Z. z.) a 23 % sa naň nevzťahuje.
{
"cislo": "ESHOP/2026/000124",
"datum": "2026-09-21",
"mena": "CZK",
"kurz": 0.0398,
"odberatel": { "nazov": "Odberateľ s.r.o." },
"polozky": [ { "nazov": "Tovar A", "mn": 1, "cena": 1000, "dph": 23, "mj": "ks", "typ": "tovar" } ]
}
Tisíc korún sa zaúčtuje ako 39,80 €. Keby ste do kurz poslali 25.1 (teda „1 EUR = 25,1 CZK"), vyšlo by z toho 25 100 €, preto to rozhranie odmietne skôr, než doklad vznikne.
Polia
| Pole | Povinné | Poznámka |
|---|---|---|
cislo | áno | Max. 50 znakov, bez medzery na začiatku a na konci (inak 400: číslo s medzerou a bez nej sú dva doklady s jedným variabilným symbolom). Inak sa prevezme PRESNE tak, ako príde. Neprečíslujeme, nedoplníme nuly, nezaradíme do nášho číselného radu (rad_id ostáva prázdne). Je to nosič párovania platieb cez VS a zároveň idempotenčný kľúč, viď 4. |
datum | áno | YYYY-MM-DD a nič iné: 2026-9-7 ani ISO časová pečiatka neprejdú (400). Databáza by ich prijala, ale pečiatka …T22:00:00.000Z sa uloží ako PREDOŠLÝ deň a 2026-9-7 rozbije rozpoznanie opakovaného doručenia. Musí to byť aj skutočný deň v kalendári, rok 2020 až 2035: 2026-02-30 vráti 400 (do 24. 9. 2026 prešiel tvarom a spadol až v databáze ako 500). Rovnako datum_dodania, splat a datum_uhrady. Dátum vyhotovenia. |
datum_dodania | odporúčané | Rozhoduje o zdaňovacom období (§ 19 zákona o DPH). Keď chýba, berie sa datum. |
splat | nie | Keď chýba, dopočíta sa z nastavení firmy. |
vs | nie, ale čítajte ďalej | Párovanie prijatej platby s vydanou faktúrou beží cez vs. Číslo dokladu hľadáme v texte platby len vtedy, keď výpis variabilný symbol nemá vôbec (Revolut, SEPA), a len celé číslo otvorenej faktúry s aspoň 5 znakmi a 4 číslicami. Platbu s VS, ktorý sa od faktúry líši, podľa textu nezachránime. Keď vs nepošlete, odvodíme ho z čísla dokladu (posledných 10 číslic; ESHOP/2026/000123 → 2026000123) a vrátime ho v odpovedi: porovnajte si ho s tým, čo dávate zákazníkovi do platobných údajov. Keď sa tie dve hodnoty rozídu, platba sa nespáruje a nikde to nebude vidieť. |
mena | nie | EUR (predvolené). Iná mena vyžaduje kurz (viď riadok nižšie), orientácia toho poľa je opačná, než akú väčšina systémov posiela. |
kurz | áno, ak mena nie je EUR | EUR za JEDNU jednotku cudzej meny: 1 CZK = 0.0398 EUR, teda "kurz": 0.0398. ⛔ Nie 1 EUR = 25.1 CZK. Kurzový lístok NBS aj bežná reč hovoria opačne, preto to píšeme takto natvrdo: zaúčtované sumy sú suma na doklade × kurz, takže obrátené číslo zaúčtuje faktúru na 1 000 CZK ako 25 100 € namiesto 39,80 €. Do 21. 9. 2026 sme každé kladné číslo prijali bez slova; odvtedy porovnávame s referenčným kurzom ECB/NBS k dňu dokladu a pri piatich a viac násobkoch doklad neprejde (ERR_KURZ_MIMO_ROZSAHU), pri rozdiele nad 10 % prejde s varovaním KURZ_MIMO_REFERENCIE. Referenčný kurz je ten podľa § 24 ods. 2 písm. a) zákona č. 431/2002 Z. z.: z dňa predchádzajúceho dňu účtovného prípadu. Ukladáme 6 desatinných miest. |
odberatel.nazov | áno | Ostatné polia sú voliteľné, ale bez ico/ic_dph sa doklad nezaradí do kontrolného výkazu tak, ako má. |
odberatel: adresa | áno, ak ste platiteľ DPH | Prijímame obidva tvary: hotový reťazec adresa, alebo diely ulica + obec (prípadne mesto) + psc + krajina. Keď adresa chýba, poskladáme ju z dielov ako ulica, PSČ obec a diely necháme (Peppol si ich číta priamo). Vlastná adresa má prednosť. § 74 ods. 1 písm. b) ZDPH žiada na faktúre meno a adresu príjemcu; do 18. 9. 2026 sa diely uložili, ale doklad ich netlačil, takže faktúra vyšla len s menom. |
polozky[] | áno | Kľúče sú nazov, mn (množstvo), cena (jednotková, bez dane), dph (sadzba v %), mj a typ. ⛔ Nie qty, nie pocet, nie dph_sadzba: iné meno sa ticho zahodí a položka vyjde na nulu. |
polozky[].typ | áno, ak predávate tovar | tovar → výnos na účte 604, sluzba → 602. Keď pole chýba, berie sa sluzba a v odpovedi príde varovanie POLOZKA_BEZ_TYPU; keď nesie neznámu hodnotu, doklad neprejde (400). Zmerané 18. 9. 2026 na produkcii: položka bez typ aj položka s typ: "sluzba" zaúčtovali 311 / 602, položka s typ: "tovar" zaúčtovala 311 / 604. Účet sa dá opraviť len prepísaním dokladu, takže pri stovkách faktúr mesačne to nie je detail. |
dphSadzba | nie | Záložná sadzba pre položku, ktorá vlastnú dph nenesie. Keď ju nepošlete, daň sa počíta z polozky[].dph, a keď ju nenesie ani položka, doklad neprejde (ERR_DPH_SADZBA_NEURCENA). Sadzbu si nedomýšľame; do 18. 9. 2026 sa v tomto prípade ticho počítalo 0 %. |
sposobUhrady | nie | prevod (predvolené), hotovost, karta, dobirka, inkaso. Píše sa na doklad a pri uhradena: true rozhoduje o peňažnom účte. dobierka prijímame ako alias pre dobirka; čokoľvek iné je 400 ERR_SPOSOB_UHRADY_NEZNAMY. Predvolenú hodnotu si za vás nevyberáme. |
uhradena | nie | true založí doklad rovno ako zaplatený a zaúčtuje úhradu. Prijímame ho len pre sposobUhrady: "karta": platba cez bránu ide na účet 261 „Peniaze na ceste" (brána posiela súhrn s odstupom, na 221 peniaze v ten deň nie sú). ⛔ Pri prevod, inkaso, hotovost a dobirka odmietame, viď nižšie. |
datum_uhrady | nie | YYYY-MM-DD, platí len s uhradena: true. Keď chýba, je ním deň vystavenia. Smie byť pred datum: pošlite skutočný deň platby, aj keď faktúru vystavujete až pri expedícii; viď „Platba prišla skôr, než ste vystavili faktúru" nižšie. Do 18. 9. 2026 sme taký dátum odmietali s 400. |
poznamka, objednavka_cislo, ss | nie | Prenesú sa na doklad. objednavka_cislo prijímame aj ako objednavkaCislo; do 18. 9. 2026 sa snake_case tvar ticho zahadzoval, hoci ho táto tabuľka sľubovala. objednavka_cislo má najviac 50 znakov; dlhšie vráti 400 (do 24. 9. 2026 sa ticho orezalo a doklad niesol iné číslo). |
repeatInterval | ⛔ Rozhranie ho neprijíma (400). Je to tlačidlo formulára „opakovať": opakovanú faktúru by potom vystavoval náš plánovač popri vašom systéme a tá istá tržba by sa zaúčtovala dvakrát. |
Kedy uhradena: true odmietneme
Rozhranie zapíše úhradu len tam, kde v deň vystavenia naozaj prebehla a kde ju vieme zaúčtovať bez toho, aby ten istý obnos skončil v knihách dvakrát.
| Situácia | Prečo nie |
|---|---|
sposobUhrady: "prevod" alebo "inkaso" | Ten istý pohyb príde do Bezúčta ešte raz, bankovým výpisom. Párovanie však berá do úvahy len faktúry v stave nezaplatená, takže doklad založený ako zaplatený sa s vlastnou platbou už nespáruje: pohyb ostane nezaradený a jeho zaúčtovanie zapíše na 221 druhý raz. Pošlite doklad bez uhradena; prevod spárujeme z výpisu podľa variabilného symbolu. Karta je iný prípad: brána posíla jeden súhrn za mnoho objednávok, takže druhýkrát tá istá suma nepríde. |
sposobUhrady: "hotovost" | Hotovosť prijatá na predajnom mieste je tržba podľa § 2 písm. u) zákona č. 384/2025 Z. z. a patrí cez eKasu do dennej uzávierky, ktorá ju zaúčtuje sama. Faktúra označená „zaplatená v hotovosti" by ten istý výnos zaúčtovala druhý raz. |
sposobUhrady: "dobirka" | V deň vystavenia zákazník ešte nezaplatil: platí kuriérovi pri doručení a zásielku môže odmietnuť. Zápis by pristál na nesprávny deň (§ 3 ods. 1 zákona č. 431/2002 Z. z.) a pri neprevzatí by sa musel rušiť, hoci pohľadávka nikdy nezanikla. Posielajte sposobUhrady: "dobirka" bez uhradena. |
| účet vedie jednoduché účtovníctvo | Úhrada patrí do peňažného denníka, ktorý zapisuje iná cesta; polovične zapísaný denník vyzerá ako úplný. |
| doklad je naviazaný na zálohovú faktúru | Krytie si odvodzuje z nej: dve tvrdenia o tom istom stĺpci naraz neprijímame. |
typ nie je faktura ani vyuctovacia | Zálohová ani proforma nemá otvorenú pohľadávku, ktorú by úhrada zatvárala. |
| obdobie je uzamknuté ku dňu úhrady alebo ku dňu vystavenia | 423, § 16 ods. 9 zákona o účtovníctve. Pri platbe prijatej pred vystavením vznikajú dva zápisy v dvoch dňoch, takže sa kontrolujú oba. |
Platba prišla skôr, než ste vystavili faktúru
Bežný tok e-shopu: zákazník zaplatí kartou pri objednávke, faktúra vznikne až pri expedícii o deň alebo dva. Pošlite skutočný dátum platby. Do 18. 9. 2026 sme taký doklad odmietli s 400 a pýtali si dátum, ktorý nebol pravdivý. To bola naša chyba, nie Vaša.
Zaúčtujeme to tak, ako to naozaj prebehlo. Platba prijatá pred dodaním je prijatý preddavok:
| Deň | Zápis |
|---|---|
deň platby (datum_uhrady) | MD 261 Peniaze na ceste / DAL 324 Prijaté preddavky |
deň vystavenia (datum) | MD 324 / DAL 311 Odberatelia: preddavok sa zúčtuje proti pohľadávke |
Vďaka tomu nevznikne záporná pohľadávka ani na jeden deň a súvaha sedí ku ktorémukoľvek dňu, aj keď platba a vystavenie padnú do dvoch rôznych mesiacov alebo rokov.
⚠ Jedna vec ostáva na Vás. Prijatím platby pred dodaním vzniká daňová povinnosť dňom prijatia platby (§ 19 ods. 4 zákona č. 222/2004 Z. z.), ale daňové priznanie počítame podľa dňa dodania (datum_dodania, inak datum). Keď platba príde pred dodaním a obe padnú do rôznych mesiacov, vrátime varovanie UHRADA_V_INOM_DANOVOM_OBDOBI: daň by sme inak vykázali o obdobie neskôr, než vznikla. Platba po dodaní varovanie nevyrobí: daňová povinnosť vtedy vznikla dodaním (§ 19 ods. 1 pri tovare, ods. 2 pri službe) a priznanie podľa dňa dodania je správne. Ak má pripadnúť do obdobia platby, pošlite datum_dodania rovné dátumu úhrady. Deň dodania si za Vás neprepíšeme; je to Vaše rozhodnutie o tom, čo sa kedy stalo.
⚠ Odvodený vs nie je zaručene jedinečný. Berie sa posledných 10 číslic čísla dokladu, takže ZF/2026/000123 a 2026/000123 dajú ten istý symbol. Párovanie v banke vtedy vezme najstaršiu otvorenú faktúru s tým symbolom, ktorej suma sedí, a druhá ostane nezaplatená bez akéhokoľvek hlásenia. Ak si čísla nedržia jednu schému, posielajte vs výslovne.
Sumy si počíta server z položiek; vaše subtotal/dphAmt/total doklad nikdy neprepíšu: jedna hodnota má jedného vlastníka. Posielajte ich však aj tak. Keď sa naša suma s vašou rozíde, vrátime rozdiel v drift_warnings[], a to je jediný kanál, ktorým sa o ňom dozviete strojovo. Neprázdne drift_warnings berte ako zlyhanie, nie ako poznámku.
⚠ Čísla posielajte s desatinnou bodkou (41.50) alebo ako číselný typ JSON. "41,50" odmietame (400), inak by sme ho orezali na 41 a doklad by niesol nižší základ aj daň. Položiek je najviac 200; viac ich neprijmeme, aby sme zvyšok ticho nezahodili.
⛔ Polia, ktoré by menili, čo sa zaúčtuje, neprijímame v neznámej hodnote. typ, rezim, trzbyUcet, sposobUhrady a polozky[].typ mimo povoleného zoznamu vrátia 400 namiesto toho, aby si server dosadil predvolenú hodnotu. Dôvod: typ: "zalohova" by doklad založil bez zápisu výnosu a dane, a neznámy rezim by dodanie do EÚ zaúčtoval ako tuzemské, takže by nebolo ani v súhrnnom výkaze, ani v kontrolnom.
⚠ Chýbajúce pole a neznáma hodnota nie sú to isté. Keď pole vynecháte, platí predvolená hodnota kontraktu a je to v poriadku (sposobUhrady → prevod, rezim → tuzemska). Jedinou výnimkou je polozky[].typ: tam predvoľba nie je dohoda, ale dohad o tom, čo predávate, takže doklad prejde a varovanie príde.
Odpoveď
{
"id": 12345, "cislo": "ESHOP/2026/000123", "vs": "2026000123", "rad_id": null,
"sposob_uhrady": "karta", "uhradena": true, "datum_uhrady": "2026-09-16",
"sparovane_pohyby": 0, "warnings": [], "drift_warnings": []
}
uhradena a datum_uhrady hovoria stav dokladu po uložení, nie len to, čo ste poslali. Keď už v banke čaká nespárovaná platba s rovnakým vs a jej suma sedí, doklad ju hneď spáruje: príde uhradena: true, datum_uhrady je deň platby a sparovane_pohyby počet pohybov, ktoré sa na tento doklad práve spárovali. Ak rovnaký vs aj sumu nesie aj staršia otvorená faktúra, platbu dostane ona a tento doklad ostane uhradena: false. Do 27. 9. 2026 odpoveď v takom prípade hlásila uhradena: false, hoci doklad bol už zaplatený.
200. warnings[] nie sú chyby: doklad vznikol; sú to veci, na ktoré by sme upozornili aj človeka v aplikácii (napr. odberateľ bez IČ DPH pri režime, ktorý ho vyžaduje). Odporúčam ich logovať, nie ignorovať.
Varovania, ktoré nesú strojovo čitateľný kod:
kod | Kedy príde | Čo s tým |
|---|---|---|
POLOZKA_BEZ_TYPU | aspoň jedna položka neniesla typ: zaúčtovali sme ju ako službu (602) | Ak je to tovar, doplňte "typ": "tovar" (604). Text varovania menuje čísla dotknutých položiek. |
TUZEMSKA_NULOVA_DAN_BEZ_IC_DPH | tuzemský doklad s nulovou daňou pre odberateľa bez IČ DPH | Skontrolujte, či ste sadzbu naozaj chceli nulovú. Do 18. 9. 2026 to bol jediný signál, že daň ticho vypadla. Odvtedy taký doklad neprejde bez sadzby vôbec. |
DODAVATEL_BEZ_ICO | doklad sa vytlačí bez IČO dodávateľa: nemá ho dodavatel.ico a nedoplní sa ani z Nastavení účtu (tie sa dopĺňajú, len keď dodavatel nenesie názov, IČO ani DIČ) | Doplňte IČO v Nastaveniach účtu, sekcia Firemné údaje, alebo ho posielajte v dodavatel.ico. Na faktúre ako na obchodnom liste je povinné (§ 3a ods. 1 Obchodného zákonníka). |
DODAVATEL_BEZ_IC_DPH | účet je platiteľ DPH a IČ DPH dodávateľa nie je ani v dodavatel.ic_dph, ani v Nastaveniach | Doplňte IČ DPH v Nastaveniach účtu (§ 74 ods. 1 písm. a) ZDPH). |
KURZ_MIMO_REFERENCIE | kurz sa od referenčného kurzu ECB/NBS k dňu dokladu líši o viac než 10 %, ale menej než päťnásobne | Doklad je založený vaším kurzom. Ak ste chceli referenčný kurz podľa § 24 ods. 2 písm. a) ZoÚ, text varovania nesie jeho hodnotu aj deň, ku ktorému platí. Pri väčšom rozdiele doklad nevznikne vôbec (ERR_KURZ_MIMO_ROZSAHU). |
---
4. Opakované doručenie (retry)
Číslo dokladu je idempotenčný kľúč. Žiadnu hlavičku ani vlastný identifikátor posielať netreba.
| Situácia | Odpoveď |
|---|---|
| nový doklad | 200 s id |
| to isté číslo, tá istá suma a dátum | 200, {"idempotentne": true, "id": <pôvodné>}: nič sa nezaložilo, nič sa nezaúčtovalo druhýkrát |
| to isté číslo, iná suma alebo dátum | 409, {"code":"ERR_CISLO_INY_DOKLAD"}: doklad nevznikne |
ten istý doklad, ale teraz s uhradena: true, hoci v Bezúčte zaplatený nie je | 409, {"code":"ERR_UHRADA_K_EXISTUJUCEMU_DOKLADU","existujuca":{"id":…}}: úhrada sa nezapíše; ohláste ju cez POST /api/faktury/<id>/uhrada (5.) |
Posledný riadok platí od 24. 9. 2026. Dovtedy prešlo také doručenie ako 200 s idempotentne: true a úhrada sa ticho zahodila: vy ste si zapísali „zaplatené", pohľadávka v Bezúčte ostala otvorená. Opakované založenie stav dokladu nemení; úhrada k existujúcemu dokladu má vlastnú cestu, ktorá overí vlastníka dokladu aj deň platby. Opačný smer (doklad je už zaplatený a retry uhradena nenesie) je obyčajný retry: 200, nič sa nestratí.
Prvé tri riadky sú zmerané na produkcii 18. 9. 2026, nie odvodené z kódu: tri volania za sebou tým istým kľúčom dali 200 s novým id, potom 200 s idempotentne: true a tým istým id, a napokon 409 s ERR_CISLO_INY_DOKLAD, ktorý v tele nesie obe sumy aj oba dátumy. Doklad z testu bol potom zmazaný a kľúč zrušený.
Druhý riadok je dôvod, prečo to existuje: pri stovkách dokladov mesačne je retry po timeoute, reštarte alebo 502 z proxy normálny stav a volajúci nemá ako vedieť, či prvý pokus prešiel.
Tretí riadok je zámerne tvrdý. Rovnaké číslo s iným obsahom znamená recyklované číslo vo vašom systéme; poradové číslo identifikuje jeden doklad (§ 74 ods. 1 zákona o DPH) a prepísať ním iný by zmazalo už zaúčtovaný záznam. Odpoveď nesie obe sumy aj oba dátumy, aby sa dalo zistiť, ktorý doklad kolíduje.
⚠ idempotentne: true si zapíšte na svojej strane. Bez toho si druhé 200 zaevidujete ako druhý doklad.
Dobropis má vlastné pravidlo. Číslo faktúry tu kľúčom nie je, lebo k jednej faktúre môže byť dobropisov viac. Čiastočný dobropis preto chce hlavičku Idempotency-Key (sekcia 6) a plný ju smie poslať: zopakované volanie s rovnakým kľúčom a rovnakým telom vráti pôvodný doklad s 200 a idempotentne: true, nový nevznikne.
---
5. Ohlásenie úhrady neskôr
POST /api/faktury/<id>/uhrada
Authorization: Bearer <kľúč>
Content-Type: application/json
{ "datum": "2026-09-30", "sposobUhrady": "karta" }
Cesta pre prípad, keď sa o platbe dozviete až po vystavení: prevod z výpisu, kartu zo súhrnu od brány. id je hodnota, ktorú vrátilo založenie dokladu.
Kľúč ohlási úhradu len k faktúre, ktorú vystavil on sám alebo kľúč, ktorý ste medzitým zrušili. Doklad založený v aplikácii aj doklad iného, stále aktívneho kľúča vráti 403. Toto obmedzenie je celý rozsah oprávnenia: kľúč nesmie meniť stav ľubovoľného dokladu na účte.
⛔ Kľúče vydané pred 18. 9. 2026 to nevedia: majú len faktura_ingest. Vydajte nový v Nastavenia → Prístupové kľúče; starý zrušte až po prepnutí.
ℹ Výmena kľúča doklady neosirí. Keď starý kľúč zrušíte, jeho faktúry prevezme ktorýkoľvek aktívny kľúč toho istého účtu: ohlási k nim úhradu aj vystaví dobropis. Kým starý kľúč nezrušíte, jeho doklady patria jemu, a to aj vtedy, keď už prestal platiť (napríklad po zmene hesla). Nový kľúč k nim dostane 403 s názvom starého kľúča v poli kluc. Ak ste ho týmto kľúčom nahradili, zrušte ho v Nastavenia → Prístupové kľúče a zopakujte volanie. Faktúry spred 18. 9. 2026, keď sa ešte neevidovalo, ktorý kľúč doklad vystavil, neprevezme žiadny kľúč; tie označte ako uhradené v aplikácii.
ℹ Keď o platbe viete už pri vystavení, túto cestu nepotrebujete: pošlite uhradena a datum_uhrady rovno pri zakladaní dokladu (sekcia 3). Tam smie byť dátum úhrady aj skorší než dátum vystavenia; tu nie, lebo doklad už existuje a spätná úhrada by menila uzavretý stav.
Kam peniaze sadnú
Spôsob úhrady rozhoduje o účte. Tabuľka platí pre túto cestu: ohlásenie úhrady k už vystavenému dokladu. Pri zakladaní (sekcia 3) prijímame uhradena: true len pri karta; ostatné spôsoby tam vrátia 400 ERR_UHRADA_PRI_ZALOZENI_NEPLATNA aj s dôvodom, lebo ten istý pohyb by do Bezúčta prišiel druhý raz: hotovosť cez dennú uzávierku eKasy, prevod a inkaso bankovým výpisom, dobierka až v deň inkasa u kuriéra.
sposobUhrady | Účet | Prečo |
|---|---|---|
karta | 261 Peniaze na ceste | Brána od zákazníka inkasovala, ale nám posiela jeden súhrn za mnoho objednávok o niekoľko dní. V deň úhrady na bankovom účte nie je nič. |
prevod, inkaso | 221 Bankové účty | Peniaze na účte naozaj sú: o prevode sa dozviete až z výpisu. |
dobirka | 221 | ⚠ Viď poznámku nižšie. |
hotovost | 211 Pokladnica |
⚠ Dobierka je dnes na 221 a vecne to nesedí. Kuriér v deň inkasa peniaze má, ale na váš účet ich pošle v súhrne o dni až týždne neskôr, znížené o poplatok za dobierku. Je to ten istý prípad ako karta a patrila by na 261. Dnes tam nejde, lebo jej chýba druhá polovica riešenia: vyrovnanie proti remitencii dopravcu. Do kartového zostatku dobierka nepatrí ani potom, čo sa to doplní: tie peniaze dlhuje Packeta či DPD, nie platobná brána, a dovoliť výplate z brány odúčtovať ich by bola tá istá zámena. Ak dobierky fakturujete, ozvite sa nám, nech to nastavíme.
Súhrnnú platbu z brány potom na bankovom výpise uzavriete tlačidlom 💳 Terminál pri pohybe (PATCH /api/banka/:id/parovat-terminal): zaúčtuje MD 221 / DAL 261 na pripísanú sumu a MD 568 / DAL 261 na províziu brány, takže zostatok 261 sa vynuluje a výnos ostane uznaný raz.
⚠ Do 19. 9. 2026 to tlačidlo faktúrové úhrady NEVIDELO a odpovedalo „na účte 261 nemáte nič nevyrovnané": kartový zostatok sa počítal len z tvaru dennej uzávierky pokladnice. Ak vám v knihách sedí súhrn z brány zaúčtovaný do výnosu (221/604), je to ten prípad a treba ho prekvalifikovať, inak je tá istá tržba v knihe dvakrát.
Polia
| Pole | Povinné | Popis |
|---|---|---|
datum | nie | Deň úhrady YYYY-MM-DD. Keď chýba, platí dnešok. Nesmie byť pred dňom vystavenia. |
sposobUhrady | nie | prevod · hotovost · karta · dobirka · inkaso. Keď chýba, platí spôsob z faktúry. |
⛔ Iné pole vráti 400. suma ani prijataId tá cesta neprijíma: ohlasuje sa plná úhrada. Čiastočnú úhradu a zápočet robí človek v aplikácii, pretože obe sú rozhodnutie o tom, ako sa doklad uzatvorí, nie hlásenie faktu. Pole prijaté a ticho zahodené je horšie než odmietnuté: dostali by ste 200 a mysleli si, že sme ho spracovali.
Odpoveď
| Situácia | Odpoveď |
|---|---|
| úhrada zapísaná | 200, {"ok": true, "stav": "zaplatená", "uhradena": <suma>, "zostatok": 0} |
| zopakované ohlásenie | 200, {"ok": true, "uz_oznamene": true}: nič sa nezapíše druhýkrát |
| doklad založil iný aktívny kľúč | 403, {"reason": "cudzi_doklad", "kluc": "<názov toho kľúča>"} |
| doklad nezaložil kľúč (aplikácia, alebo doklad spred 18. 9. 2026) | 403, {"reason": "doklad_bez_kluca"} |
| doklad nenájdený | 404 |
| stornovaný doklad | 409, {"reason": "stornovana"} |
| dobropis | 400, {"reason": "dobropis_sa_neuhradza"}: vrátenie peňazí odberateľovi sa zaúčtuje v aplikácii na pohybe vo výpise |
| neznáme pole / zlý dátum / zlý spôsob | 400 |
| obdobie uzamknuté ku dňu úhrady | 423, § 16 ods. 9 zákona o účtovníctve |
Druhý riadok je tam z toho istého dôvodu ako pri zakladáni: opakovanie po timeoute je bežný stav a chyba by v ňom vyzerala ako porucha integrácie.
⚠ Pri prevod a inkaso to ohlasujte len keď platbu naozaj vidíte. Doklad označený za zaplatený sa už nespáruje s vlastným pohybom z bankového výpisu: párovanie berá len faktúry v stave nezaplatená. Rozdiel oproti stavu úhrady pri vystavení (sekcia 3) je práve toto: tam platba ešte neprišla, tu už prišla a vy o nej viete.
---
6. Vrátenie tovaru: dobropis
POST /api/faktury/<id>/dobropis
Authorization: Bearer <kľúč>
Content-Type: application/json
{ "dovod_kod": "vratenie" }
Opravný doklad podľa § 25 ods. 1 a § 71 ods. 2 zákona o DPH. Pôvodná faktúra ostáva platná: dobropis ju neruší, otáča znamienko. Účtovné zápisy aj DPH idú do obdobia dobropisu, nie originálu, takže priznanie za už uzavretý mesiac sa spätne nemení.
Keď bola faktúra už uhradená, kredit nad otvorený zvyšok pohľadávky sa preúčtuje na záväzok voči odberateľovi (MD 311 / DAL 325): peniaze mu dlhujete, nie je to záporná pohľadávka.
Plný aj čiastočný dobropis. Bez poľa polozky sa vystaví plný dobropis na celú faktúru. S poľom polozky (výber vrátených položiek) sa vystaví čiastočný, a vtedy je hlavička Idempotency-Key povinná. Dôvod je jeden: plné vystavenie je voči opakovaniu bezpečné samo od seba (druhé volanie narazí na strop nižšie a skončí 409), čiastočné nie. Dve rovnaké volania na 20 € by prešli obe a odberateľ by dostal k dobru 40 €, a zopakované volanie po timeoute, reštarte alebo 502 z proxy je pri strojovom volaní normálny stav. S kľúčom sa druhé volanie nevystaví a vráti sa pôvodný doklad.
POST /api/faktury/<id>/dobropis
Authorization: Bearer <kľúč>
Content-Type: application/json
Idempotency-Key: vratka-2026-000457
{
"dovod_kod": "vratenie",
"dovod": "Vrátená doprava, reklamácia 457",
"polozky": [ { "nazov": "Doprava", "mn": 1, "cena": 5, "dph": 23 } ]
}
Položky majú rovnaký tvar ako pri zakladaní faktúry (nazov, mn, cena, dph, mj, typ). Čiastočný dobropis prechádza tými istými kontrolami ako v aplikácii: položky nesmú presiahnuť zostávajúci základ pôvodnej faktúry pri danej sadzbe, súčet dobropisov nesmie presiahnuť sumu faktúry a obdobie nesmie byť uzamknuté.
Kľúč dobropisuje len faktúru, ktorú vystavil on sám alebo kľúč, ktorý ste zrušili. Je to tá istá hranica ako pri úhrade, vrátane výmeny kľúča (sekcia 5).
Polia
| Pole | Povinné | Popis |
|---|---|---|
dovod_kod | nie | vratenie · zlava · oprava_ceny. Iná hodnota vráti 400. |
dovod | nie | Voľný text do poznámky dokladu a do auditnej stopy. Musí byť text. |
polozky | nie | Pole vrátených položiek (čiastočný dobropis). Musí byť pole; s hlavičkou Idempotency-Key je to povinné, bez poľa sa vystaví plný dobropis. |
⛔ Iné pole než tieto tri rozhranie odmietne (400, v tele zoznam v fields). Je to zámer, nie prísnosť: platobná brána vracia peniaze sumou, takže {"dovod_kod": "vratenie", "suma": 20} je tvar, ktorý sa napíše sám od seba, a keby sme neznáme pole ticho zahodili, vystavili by sme dobropis na celú faktúru, nie na 20 €. Radšej chybová hláška než tichá vratka celej objednávky.
Dátum dobropisu je deň volania: neposiela sa a spätne ho zadať nejde. Opravný doklad nesie vlastný dátum, nie dátum pôvodnej faktúry, a do tohto obdobia idú aj jeho účtovné zápisy a DPH. Vratku preto ohláste v deň, keď o nej viete; odložené volanie posunie opravu do iného mesiaca.
Hlavička Idempotency-Key
Je to váš vlastný, jedinečný identifikátor vratky: číslo vratky alebo ID refundu z platobnej brány. Má 1 až 128 znakov: písmená, číslice a znaky . _ : -, bez medzier. Iný tvar vráti 400, a to aj pri plnom dobropise, lebo kľúč, ktorý ticho zahodíme, by vratku nechránil. Kľúč platí v rámci jednej faktúry: ten istý reťazec pri inej faktúre je iný kľúč.
| Situácia | Odpoveď |
|---|---|
čiastočný dobropis (polozky) bez hlavičky | 400, {"reason": "chyba_idempotency_key"}: nič sa nevystaví |
| prvé volanie s kľúčom | 200, odpoveď ako v tabuľke nižšie |
| zopakované volanie, rovnaké telo | 200, {"idempotentne": true, "id": <pôvodný dobropis>, "cislo": "OD…", "stav": "…", "warnings": []}: nič sa nevystavilo ani nezaúčtovalo druhýkrát |
| ten istý kľúč, iné telo | 409, {"code": "ERR_IDEMPOTENCY_KONFLIKT", "dobropis_id": …, "dobropis_cislo": "OD…"}: nič sa nevystaví |
- Rovnaké telo je rovnaký
dovod_kod,dovoda rovnaké položky. Poradie položiek ani poradie polí v JSON na tom nič nemení. Zmena čo i len množstva je iný obsah: dostanete409, nie ticho prvý doklad. - Replay vráti pôvodný doklad, nie nový. Pole
warningsje pri ňom vždy prázdne: upozornenia z prvého vystavenia (napríklad vrátenie tovaru na sklad) sa neukladajú, takže sa neopakujú. Polestavnesie aktuálny stav dokladu. - Kľúč sa spotrebuje prvým vystavením. Ak bol dobropis medzičasom v aplikácii stornovaný, zopakované volanie vráti ten istý doklad so
stav: "stornovaná"a nový nevystaví. Storno je rozhodnutie človeka a strojové opakovanie ho nesmie ticho zvrátiť. Chcete vratku vystaviť znova, použite nový kľúč. - Replay sa vybaví pred ostatnými kontrolami stavu. Zopakované volanie, ktoré prvé vystavenie vyčerpalo do stropu, preto dostane
200s pôvodným dokladom, nie409. - Kľúč inej faktúry ani iného účtu nikdy nenájdeme: ten istý reťazec je tam samostatný kľúč. Doklad cudzieho kľúča sa nedá otvoriť ani cez replay (platí hranica vlastníctva vyššie).
- Súbežné volania s tým istým kľúčom nevystavia dva doklady: druhé počká na prvé a dostane
200sidempotentne: true.
Odpoveď
| Situácia | Odpoveď |
|---|---|
| dobropis vystavený | 200, {"id": <nový>, "cislo": "OD…", "opravuje": "<pôvodné číslo>", "opravuje_id": <id>} |
| zopakované volanie plného dobropisu bez hlavičky | 409, {"code": "ERR_FAKTURA_UZ_DOBROPISOVANA", "alreadyCredited": …, "origTotal": …, "zostava": 0}: druhý doklad nevznikne |
zopakované volanie s Idempotency-Key | 200 s pôvodným dokladom, viď vyššie |
| faktúra je dobropisovaná len čiastočne | 409, {"code": "ERR_FAKTURA_CIASTOCNE_DOBROPISOVANA", "zostava": …}: nie je vybavená, viď nižšie |
| doklad založil iný aktívny kľúč | 403, {"reason": "cudzi_doklad", "kluc": "<názov toho kľúča>"} |
| doklad nezaložil kľúč (aplikácia, alebo spred 18. 9. 2026) | 403, {"reason": "doklad_bez_kluca"} |
| faktúra v režime OSS § 68b | 200: dobropis sa vystaví a oprava sa zapíše do evidencie OSS, viď sekcia 9 |
| faktúra v režime OSS § 68b bez krajiny spotreby | 409, {"code": "ERR_OSS_DOBROPIS_BEZ_KRAJINY"}: opravu nie je kam vykázať |
čiastočný dobropis bez hlavičky Idempotency-Key | 400, {"reason": "chyba_idempotency_key"} |
hlavička Idempotency-Key v zlom tvare | 400, {"code": "ERR_VALIDATION", "field": "Idempotency-Key"} |
polozky nie je pole · prázdne pole · položka mimo pôvodnej faktúry | 400 |
| ten istý kľúč s iným telom | 409, {"code": "ERR_IDEMPOTENCY_KONFLIKT"} |
| iné pole v tele | 400, {"code": "ERR_VALIDATION", "fields": [...]} |
| doklad nenájdený | 404 |
| stornovaná faktúra · dobropis na dobropis · otvorená položka z migrácie | 409 |
| obdobie uzamknuté k dnešnému dňu | 423, § 16 ods. 9 zákona o účtovníctve |
Druhý riadok je tá istá poistka ako pri zakladaní dokladu, len iným mechanizmom: súčet dobropisov k jednej faktúre nesmie presiahnuť jej sumu. Je to obranná podmienka odvodená z logiky opravy základu dane podľa § 25 ods. 1 písm. a) a b) zákona o DPH: rozsah opravy nemôže byť väčší než rozsah pôvodného plnenia, nie doslovné znenie toho odseku. Retry po timeoute preto neskončí druhým opravným dokladom, ale odmietnutím, ktoré v tele nesie, koľko už je dobropisované.
⚠ Tie dva 409 nie sú to isté a nesmiete ich spracovať rovnako. ERR_FAKTURA_UZ_DOBROPISOVANA znamená, že faktúra je dobropisovaná celá: dosiahli ste, čo ste chceli, prestaňte opakovať. ERR_FAKTURA_CIASTOCNE_DOBROPISOVANA znamená pravý opak: časť sumy dobropisovaná je (typicky čiastočným dobropisom z aplikácie), zvyšok v poli zostava nie je vybavený a plný dobropis sa doň nezmestí. Z toho stavu vás nedostane žiadny počet opakovaní plného dobropisu: zvyšok vystavte čiastočným dobropisom (polozky a nový Idempotency-Key), najviac na sumu v zostava. Keby obidva stavy niesli jeden kód, ten druhý by ste vyhodnotili ako hotový a zvyšok by sa do kníh nedostal.
⚠ Platobná brána vratku spravidla neposiela ako samostatný pohyb: odpočíta ju z najbližšej výplaty. Výplata potom bude nižšia než súčet faktúr, ktoré ju tvoria, a aplikácia ju sama nevyrovná. Dobropis vystavený touto cestou je to, čo ten rozdiel v knihách vysvetlí.
---
7. Strop volaní
| Vrstva | Strop | Kľúč |
|---|---|---|
| ingest | 120 / min | podľa kľúča |
celé /api | 300 / min | podľa IP |
Pri prekročení príde 429, {"code":"ERR_RATE_LIMIT"} a hlavička Retry-After. Jednorazová dávka 800 historických dokladov pri tomto strope prejde za ~7 minút.
⚠ Druhý riadok je vrstva nad prvým a kľúčuje sa podľa IP, nie podľa kľúča. O jeho vyčerpaní teda môže rozhodnúť aj iná prevádzka z tej istej adresy.
---
8. Chyby
| Kód | Význam |
|---|---|
400 | chýbajúce povinné pole, neplatný tvar |
400 ERR_BAD_JSON | telo požiadavky nie je platný JSON (čiarka navyše, chýbajúca úvodzovka). Telo nikam nevraciame ani nezapisujeme, takže odpoveď nepovie, kde presne chyba je: skúste telo vložiť do ľubovoľného overovača JSON. Pred 14. 10. 2026 sme na to odpovedali 500, čo je pre vás pokyn „skúsiť znova", a to nepomôže. |
415 ERR_UNSUPPORTED_BODY | Content-Type s iným kódovaním než UTF-8 (napríklad charset=iso-8859-1) alebo Content-Encoding, ktorý neprijímame. Pošlite JSON v UTF-8 a bez kompresie. |
400 ERR_NEPLATNE_UTF8 | telo obsahuje bajty, ktoré nie sú platné UTF-8 (typicky skript alebo súbor v kódovaní Windows-1250 či Latin-2). Pred 13. 11. 2026 sme takéto telo prijali a každé písmeno s diakritikou sa uložilo ako náhradný znak, čo sa na doklade už nedá opraviť späť. Telo nikam nevraciame ani nezapisujeme: skontrolujte kódovanie súboru alebo skriptu a pošlite JSON v UTF-8. |
400 ERR_BAD_BODY_ENCODING | telo hlási kompresiu (Content-Encoding: gzip a podobne), ale nedá sa rozbaliť. Skontrolujte, že hlavička sedí s tým, čo posielate. |
413 ERR_PAYLOAD_TOO_LARGE | telo je väčšie než 5 MB. Jedna faktúra sa do toho zmestí s veľkou rezervou, takže spravidla ide o omyl (napríklad príloha poslaná ako text). |
400 ERR_DPH_SADZBA_NEURCENA | účet je platiteľ DPH, ale sadzba nie je ani na doklade, ani na položke |
400 ERR_SPOSOB_UHRADY_NEZNAMY | sposobUhrady mimo povoleného zoznamu |
400 ERR_KURZ_MIMO_ROZSAHU | kurz je aspoň päťnásobne inde než referenčný kurz ECB/NBS k dňu dokladu: spravidla obrátená orientácia (25.1 namiesto 0.0398) alebo posunutá desatinná čiarka. Telo nesie referenčný kurz aj deň, ku ktorému platí. |
400 s field: "polozky" | položka nesie v cena, mn alebo dph hodnotu, ktorá nie je číslo ("EUR 41.50", "2 ks", "23%", číslo s desatinnou čiarkou). Predvolenú hodnotu si za vás nedosadíme: vytiahli by sme z nej len začiatok alebo nulu a doklad by niesol inú sumu či daň, než akú ste poslali. Chýbajúce pole je iná situácia a rieši sa podľa tabuľky v 3. |
400 s field: "polozky" a polozka | položka nesie produkt_id. To je ID skladovej karty v Bezúčte, nie ID produktu vo vašom systéme: pri zapnutom sklade by sme podľa neho odpísali tovar a pri zhode čísla by to bol iný tovar. Pole vynechajte, označenie produktu patrí do produkt_sku (uloží sa na doklad, sklad podľa neho neodpisujeme). |
400 s field: "prijataZaloha" | odpočet preddavku bez zalohaFakturaId. Bez väzby na zálohovú faktúru by sme odpočet zaúčtovali bez overenia, že preddavok naozaj prišiel. Pošlite zalohaFakturaId, suma sa odvodí zo zálohovej faktúry. |
400 ERR_UHRADA_PRI_ZALOZENI_NEPLATNA | uhradena: true v situácii, v ktorej úhradu zaúčtovať nevieme, viď nižšie |
409 ERR_FAKTURA_UZ_DOBROPISOVANA | faktúra je už dobropisovaná v plnej výške; tak skončí aj zopakované volanie, viď 6. |
409 ERR_FAKTURA_CIASTOCNE_DOBROPISOVANA | dobropisovaná je len časť, zvyšok (zostava) vybavený nie je; vystavte ho čiastočným dobropisom, viď 6. |
409 ERR_IDEMPOTENCY_KONFLIKT | Idempotency-Key dobropisu už bol pri tejto faktúre použitý s iným obsahom; telo nesie dobropis_id a dobropis_cislo dokladu, ktorý pod kľúčom už je. Pre inú vratku použite nový kľúč, viď 6. |
401 | kľúč neplatný, odvolaný, alebo prišlo „odhlásiť všade" |
403 agent_missing_scope | kľúč na tento endpoint nemá právo (napr. pokus o čítanie) |
403 (bez kódu) | predplatné účtu neumožňuje zápis: skončený trial alebo nezaplatené. Kľúč je v poriadku, účet nie; opakovanie nepomôže. |
409 ERR_CISLO_INY_DOKLAD | číslo už nesie iný doklad, viď 4. |
409 ERR_UHRADA_K_EXISTUJUCEMU_DOKLADU | doklad už existuje nezaplatený a opakované založenie nesie uhradena: úhradu ohláste cez 5. |
423 | účtovné obdobie je uzamknuté (po podaní priznania, § 16 ods. 9 zákona o účtovníctve) |
429 ERR_RATE_LIMIT | strop volaní |
423 je jediná chyba, ktorú nevyrieši opakovanie: doklad patrí do obdobia, ktoré je už podané. Rieši sa v aplikácii (odomknutie obdobia), nie retry.
⚠ Kód chyby nie je vždy v poli code. Kto sa vetví podľa kódu, musí vedieť, kde ho hľadať: inak mu podmienka ticho neplatí nikdy:
| Chyba | Kde je kód | Tvar odpovede |
|---|---|---|
ERR_CISLO_INY_DOKLAD, ERR_UHRADA_K_EXISTUJUCEMU_DOKLADU, ERR_RATE_LIMIT, ERR_OSS_* | code | {"code":"ERR_CISLO_INY_DOKLAD","error":"…","existujuca":{…}} |
| kľúč nemá právo na endpoint | reason, nie code | {"error":"agent_denied","reason":"agent_missing_scope","required":["read"]} |
| overenia dokladu (napr. daň na faktúre neplatiteľa) | errorCode, nie code | {"error":"…","errorCode":"ERR_NEPLATITEL_DPH_NA_FAKTURE"} |
Bezpečné je vetviť sa cez resp.code ?? resp.errorCode ?? resp.reason.
Posledný riadok sa vás netýka, kým ste platiteľ DPH: neplatiteľ, ktorý na tuzemskej faktúre uvedie daň, dostane 400: daň by bol povinný odviesť bez nároku na odpočet (§ 69 ods. 5 zákona o DPH). Zmerané 18. 9. 2026: to isté telo požiadavky prešlo po zmene sadzieb položiek na 0.
Kde odmietnuté volanie uvidíte aj vy
V aplikácii, v Nastavenia → Prístupové kľúče, má každý kľúč tlačidlo Posledné volania. Vypíše posledných 100 volaní tým kľúčom (čas, metódu, cestu, stavový kód a strojový kód chyby) a odmietnuté volania sú tam tiež, vrátane tých, ktoré neprešli overením kľúča. Preto tam uvidíte aj pokus s kľúčom, ktorý ste medzitým zrušili alebo zle skopírovali.
Ak váš systém posiela dávky, jedno volanie medzi desiatkami ľahko stratíte z očí. Nad zoznamom je preto filter: výber „Všetky / Len odmietnuté / Len prijaté" a pole, do ktorého stačí napísať časť cesty (napríklad dobropis). Veľkosť písmen nehrá rolu.
Zmysel je jednoduchý: „automat nebeží" a „automat beží a my ho odmietame" sa zvonku nedajú rozoznať, a prázdny zoznam je odpoveď na tú istú otázku, lebo znamená, že k nám nedorazilo nič, čo by sme vedeli priradiť ku kľúču. História siaha 90 dní dozadu; staršie riadky sa mažú.
⚠ Čo v zozname NIE JE, aj keď ste volali. Zoznam je kniha volaní podľa kľúča, a kľúč spoznáme len z hlavičky Authorization. Preto sa tam nezapíše:
| Situácia | Čo uvidíte vy | Prečo v zozname nie je |
|---|---|---|
chýba hlavička Authorization | 401 | nevieme, čie volanie to bolo |
volanie na bezucto.sk bez www | 301 | presmerovanie sa vybaví pred overením kľúča |
| volanie na zlú adresu, firewall, DNS | chyba spojenia alebo cudzia odpoveď | k nám sa nedostalo |
globálny strop podľa IP (429) | 429 | strop sa počíta ešte pred overením kľúča |
Zapísané je naopak aj to, čo skončí pred spracovaním tela: chybný JSON (400 ERR_BAD_JSON) nepodporované alebo poškodené kódovanie tela (415, 400 ERR_BAD_BODY_ENCODING) a priveľké telo (413) so správnym kľúčom v zozname uvidíte. Ak je zoznam prázdny a váš systém tvrdí, že odosielal, začnite adresou a hlavičkou, nie nastavením kľúča.
---
9. Predaj do EÚ v režime OSS (§ 68b)
Faktúru pre spotrebiteľa v inom členskom štáte pošlite s dvoma poľami navyše. Doklad potom nesie daň krajiny spotreby: miesto dodania je členský štát kupujúceho (§ 14 ods. 2 zákona o DPH). Slovensko je miestom dodania len vtedy, keď tieto predaje neprekročili 10 000 € v predchádzajúcom ani v bežnom roku (§ 16a ods. 1 písm. c)), nie po prekročení prahu podľa § 16a ods. 2 ani po vašej voľbe podľa § 16a ods. 3. Doklad z priznania DPH aj z kontrolného výkazu vypadne a zaeviduje sa do podkladu pre kvartálne priznanie OSS (§ 68b ods. 13 zákona o DPH).
| Pole | Načo |
|---|---|
rezim: "oss_68b" | vyradí doklad zo slovenského priznania aj z kontrolného výkazu A.1 |
krajina_spotreby | ISO-2 kód členského štátu kupujúceho, napr. "DE" |
polozky[].dph | sadzba krajiny spotreby, nie slovenská (DE 19/7, AT 20/13/10, CZ 21/12, HU 27/18/5 …) |
polozky[].typ | "tovar": § 68b je predaj tovaru na diaľku; bez tohto poľa sa výnos zaúčtuje na 602 (služby) |
{
"cislo": "ESHOP/2026/000841",
"datum": "2026-09-17",
"rezim": "oss_68b",
"krajina_spotreby": "DE",
"odberatel": { "nazov": "Hans Müller", "ulica": "Hauptstraße 1", "obec": "Berlin", "psc": "10115", "krajina": "DE" },
"polozky": [{ "nazov": "Tovar z e-shopu", "typ": "tovar", "mn": 1, "cena": 100, "dph": 19, "mj": "ks" }]
}
Doklad NEVZNIKNE (400), keď:
krajina_spotrebychýba: bez štátu sa daň nedá priradiť a v priznaní OSS by nemala riadok;krajina_spotrebyje"SK": dodanie slovenskému spotrebiteľovi je tuzemské plnenie;- krajina nie je členský štát EÚ;
- sadzba na položke nie je sadzba tej krajiny (slovenských 23 % na nemeckej faktúre = 400);
- vaša firma nemá v nastaveniach IČ DPH: osobitná úprava sa uplatňuje pod ním (§ 68b ods. 5), odpoveď nesie
code: "ERR_VALIDATION"afield: "icDph". Ak IČ DPH nemáte, pridelí vám ho daňový úrad po oznámení podľa § 68b ods. 2.
⚠ Preklep v názve režimu ("oss", "oss_68") nespadne ticho na tuzemský režim. Vráti 400. Ticho by z nemeckej faktúry urobil slovenskú a v priznaní by to nikto nevidel.
Čo sa pri tomto režime zatiaľ NEDÁ. Vráti 409 s kódom, nie polovičný stav, ktorý by sa musel spätne rozmotávať:
| Úkon | Kód | Prečo |
|---|---|---|
úprava dokladu (PUT) | ERR_OSS_EDIT_NEPODPOROVANY | evidencia OSS sa s úpravou zatiaľ nezosúladí |
| konverzia proformy | ERR_OSS_KONVERZIA_NEPODPOROVANA | konverzia kopíruje režim, ale nie krajinu spotreby |
Dobropis funguje od 22. 9. 2026 v tom istom štvrťroku, od 23. 9. 2026 aj v neskoršom (dovtedy vracal ERR_OSS_DOBROPIS_NEPODPOROVANY vždy). Opravný doklad zdedí režim aj krajinu spotreby a do evidencie OSS pribudne záporný riadok:
- Obdobie: riadok je dátumovaný dňom opravného dokladu. Zdaňovacím obdobím OSS je kalendárny štvrťrok a priznanie sa podáva až do konca mesiaca po jeho skončení (§ 68b ods. 12 zákona o DPH).
- Dobropis v tom istom štvrťroku ako predaj: priznanie ešte neexistuje, takže sa predaj a jeho oprava vzájomne odpočítajú pred podaním medzi dodaniami toho štvrťroka.
- Dobropis v neskoršom štvrťroku: zmena už podaného priznania sa podľa § 68b ods. 19 zákona o DPH uvádza v nasledujúcom priznaní ako oprava s uvedením štátu spotreby, opravovaného zdaňovacieho obdobia a sumy dane. Riadok preto nesie aj opravované obdobie (napríklad
"2026-Q3") a OSS súhrn za štvrťrok dobropisu ho ukáže v samostatnom oddiele opráv, nie medzi dodaniami. Dodania bežného štvrťroka ani pôvodný štvrťrok sa nemenia. - Sadzba: použije sa sadzba pôvodného obchodu, nie aktuálna sadzba krajiny spotreby. Ak si medzitým štát sadzbu zmenil, oprava ide starou. V oddiele opráv sa daň na sadzby nerozpadá.
- Kurz: suma v cudzej mene sa prepočíta kurzom pôvodnej faktúry, teda tým istým, akým sa do evidencie zapísal predaj (§ 68b ods. 19 veta tretia).
- Čiastočný dobropis (s hlavičkou
Idempotency-Key, viď 6.) zníži evidenciu len o vrátenú časť, rovnako ako v aplikácii. - Ročný súčet k prahu 10 000 € sa opravou nemení. Schéma je od vystavenia prvej faktúry v tomto režime aktívna. Kto sa pod prahom rozhodol pre miesto dodania v štáte spotreby, je ho povinný uplatňovať najmenej dva kalendárne roky (§ 16a ods. 3 zákona o DPH), takže zníženie súčtu by zaradenie ďalších predajov aj tak nevrátilo späť.
Rezy: všetky vrátia 409 pred akýmkoľvek zápisom, doklad ani číslo dokladu nevzniknú. Odpoveď obsahuje aj polia obdobie_povodne a obdobie_dobropisu (napríklad "2026-Q3", "2026-Q4").
| Situácia | Kód |
|---|---|
| pôvodná faktúra v režime § 68b bez krajiny spotreby: opravu nie je kam vykázať; doplňte krajinu a zopakujte | ERR_OSS_DOBROPIS_BEZ_KRAJINY |
| dnešok patrí do štvrťroka pred dátumom dodania pôvodnej faktúry: priznanie, ktoré by sa opravovalo, ešte neexistuje | ERR_OSS_DOBROPIS_PRED_PLNENIM |
| priznanie za štvrťrok dobropisu by sa podávalo až po troch rokoch od lehoty na podanie pôvodného priznania (§ 68b ods. 19) | ERR_OSS_OPRAVA_PO_LEHOTE |
Kód ERR_OSS_DOBROPIS_INE_OBDOBIE, ktorý do 23. 9. 2026 odmietal každú vratku zo staršieho štvrťroka, sa už nevracia.
Storno tiež funguje, ale je to iná operácia: znamená, že doklad nikdy neplatil, takže riadky evidencie zmaže a zníži ročný súčet k prahu 10 000 € (§ 16a ods. 1 písm. c) zákona o DPH). Dobropis naopak tvrdí, že plnenie nastalo a potom sa opravilo, preto záporný riadok, nie mazanie.
Vystavenie prvej faktúry v tomto režime aktivuje schému OSS na daný rok: je to vyhlásenie, že sa osobitná úprava uplatňuje. Bez neho by sa predaj pod prahom 10 000 € zaradil pod pravidlo „miesto dodania SR, slovenská daň" a evidencia by o tom istom doklade tvrdila opak než doklad sám.
Overené na produkcii 18. 9. 2026
Celá vetva OSS bežala naostro na našom vlastnom účte: dovtedy ju nespustil nikto a evidencia oss_b2c_sales bola naprieč databázou prázdna. Merané, nie odhadnuté:
| Čo | Výsledok |
|---|---|
| doklad s dvoma sadzbami (DE 19 % zo 100 €, DE 7 % z 30 €) | 200, číslo prevzaté presne, vs odvodené a vrátené |
| evidencia OSS | dva riadky, jeden na sadzbu: 100 € / 19 % / 19,00 € a 30 € / 7 % / 2,10 € |
| ročný súčet k prahu | 130,00 €, schéma OSS aktivovaná na rok |
| zaúčtovanie | 311 / 604 na základ (položky mali typ: "tovar"), daň zvlášť za každú sadzbu |
| druhé doručenie toho istého čísla | 200 { "idempotentne": true }, nič sa nezdvojilo |
| storno | evidencia OSS aj ročný súčet späť na nulu, protizápis za každú sadzbu |
Odmietnutia sedia s tým, čo je vyššie napísané: chýbajúca krajina_spotreby, "SK", štát mimo EÚ, slovenských 23 % na nemeckej faktúre aj preklep v názve režimu vrátili 400 a doklad nevznikol.
Daň krajiny spotreby sa účtuje na vlastnú analytiku 343.682 (pri IOSS 343.683), nie na hlavnú 343, kde sedí slovenská DPH. Doklad z priznania DPH aj z kontrolného výkazu vypadne a zostatok hlavnej 343 ostáva zhodný so slovenským priznaním; v súvahe sa analytika zráta medzi daňové záväzky. Storno aj dobropis vracajú daň na ten účet, na ktorý ju zaúčtoval pôvodný doklad. Doklady zaúčtované skôr, než sme analytiku zaviedli, majú daň na hlavnej 343 a automaticky ich neprekladáme. Pre vášho účtovníka: záväzok z OSS je vykázaný v kvartálnom podklade OSS, nie v slovenskom priznaní.
Rozhranie je v pilotnej prevádzke a pripomienky ho ešte menia. Keď vám čokoľvek v tvare dát nesadne, napíšte na [email protected].