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.

VieNevie
založiť vydanú faktúru s vlastným číslomčokoľvek prečítať (ani vlastné faktúry)
položkový rozpadstornovať doklad
zaúčtovať dokladposlať 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 }

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

PolePovinnéPoznámka
cisloánoMax. 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ánoYYYY-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_dodaniaodporúčanéRozhoduje o zdaňovacom období (§ 19 zákona o DPH). Keď chýba, berie sa datum.
splatnieKeď chýba, dopočíta sa z nastavení firmy.
vsnie, ale čítajte ďalejPá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ť.
menanieEUR (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 EUREUR 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ánoOstatné 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ľ DPHPrijí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[]ánoKľúč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 tovartovar → 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.
dphSadzbanieZá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 %.
sposobUhradynieprevod (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.
uhradenanietrue 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_uhradynieYYYY-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, ssniePrenesú 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áciaPreč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úruKrytie si odvodzuje z nej: dve tvrdenia o tom istom stĺpci naraz neprijímame.
typ nie je faktura ani vyuctovaciaZálohová ani proforma nemá otvorenú pohľadávku, ktorú by úhrada zatvárala.
obdobie je uzamknuté ku dňu úhrady alebo ku dňu vystavenia423, § 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:

kodKedy prídeČo s tým
POLOZKA_BEZ_TYPUaspoň 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_DPHtuzemský doklad s nulovou daňou pre odberateľa bez IČ DPHSkontrolujte, č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_ICOdoklad 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 NastaveniachDoplňte IČ DPH v Nastaveniach účtu (§ 74 ods. 1 písm. a) ZDPH).
KURZ_MIMO_REFERENCIEkurz sa od referenčného kurzu ECB/NBS k dňu dokladu líši o viac než 10 %, ale menej než päťnásobneDoklad 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áciaOdpoveď
nový doklad200 s id
to isté číslo, tá istá suma a dátum200, {"idempotentne": true, "id": <pôvodné>}: nič sa nezaložilo, nič sa nezaúčtovalo druhýkrát
to isté číslo, iná suma alebo dátum409, {"code":"ERR_CISLO_INY_DOKLAD"}: doklad nevznikne
ten istý doklad, ale teraz s uhradena: true, hoci v Bezúčte zaplatený nie je409, {"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ÚčetPrečo
karta261 Peniaze na cesteBrá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, inkaso221 Bankové účtyPeniaze na účte naozaj sú: o prevode sa dozviete až z výpisu.
dobirka221⚠ Viď poznámku nižšie.
hotovost211 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

PolePovinnéPopis
datumnieDeň úhrady YYYY-MM-DD. Keď chýba, platí dnešok. Nesmie byť pred dňom vystavenia.
sposobUhradynieprevod · 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áciaOdpoveď
úhrada zapísaná200, {"ok": true, "stav": "zaplatená", "uhradena": <suma>, "zostatok": 0}
zopakované ohlásenie200, {"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ý doklad409, {"reason": "stornovana"}
dobropis400, {"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ôsob400
obdobie uzamknuté ku dňu úhrady423, § 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

PolePovinnéPopis
dovod_kodnievratenie · zlava · oprava_ceny. Iná hodnota vráti 400.
dovodnieVoľný text do poznámky dokladu a do auditnej stopy. Musí byť text.
polozkyniePole 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áciaOdpoveď
čiastočný dobropis (polozky) bez hlavičky400, {"reason": "chyba_idempotency_key"}: nič sa nevystaví
prvé volanie s kľúčom200, odpoveď ako v tabuľke nižšie
zopakované volanie, rovnaké telo200, {"idempotentne": true, "id": <pôvodný dobropis>, "cislo": "OD…", "stav": "…", "warnings": []}: nič sa nevystavilo ani nezaúčtovalo druhýkrát
ten istý kľúč, iné telo409, {"code": "ERR_IDEMPOTENCY_KONFLIKT", "dobropis_id": …, "dobropis_cislo": "OD…"}: nič sa nevystaví

Odpoveď

SituáciaOdpoveď
dobropis vystavený200, {"id": <nový>, "cislo": "OD…", "opravuje": "<pôvodné číslo>", "opravuje_id": <id>}
zopakované volanie plného dobropisu bez hlavičky409, {"code": "ERR_FAKTURA_UZ_DOBROPISOVANA", "alreadyCredited": …, "origTotal": …, "zostava": 0}: druhý doklad nevznikne
zopakované volanie s Idempotency-Key200 s pôvodným dokladom, viď vyššie
faktúra je dobropisovaná len čiastočne409, {"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 § 68b200: dobropis sa vystaví a oprava sa zapíše do evidencie OSS, viď sekcia 9
faktúra v režime OSS § 68b bez krajiny spotreby409, {"code": "ERR_OSS_DOBROPIS_BEZ_KRAJINY"}: opravu nie je kam vykázať
čiastočný dobropis bez hlavičky Idempotency-Key400, {"reason": "chyba_idempotency_key"}
hlavička Idempotency-Key v zlom tvare400, {"code": "ERR_VALIDATION", "field": "Idempotency-Key"}
polozky nie je pole · prázdne pole · položka mimo pôvodnej faktúry400
ten istý kľúč s iným telom409, {"code": "ERR_IDEMPOTENCY_KONFLIKT"}
iné pole v tele400, {"code": "ERR_VALIDATION", "fields": [...]}
doklad nenájdený404
stornovaná faktúra · dobropis na dobropis · otvorená položka z migrácie409
obdobie uzamknuté k dnešnému dňu423, § 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í

VrstvaStropKľúč
ingest120 / minpodľa kľúča
celé /api300 / minpodľ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ódVýznam
400chýbajúce povinné pole, neplatný tvar
400 ERR_BAD_JSONtelo 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_BODYContent-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_UTF8telo 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_ENCODINGtelo 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_LARGEtelo 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_NEZNAMYsposobUhrady mimo povoleného zoznamu
400 ERR_KURZ_MIMO_ROZSAHUkurz 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 polozkapolož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_NEPLATNAuhradena: true v situácii, v ktorej úhradu zaúčtovať nevieme, viď nižšie
409 ERR_FAKTURA_UZ_DOBROPISOVANAfaktúra je už dobropisovaná v plnej výške; tak skončí aj zopakované volanie, viď 6.
409 ERR_FAKTURA_CIASTOCNE_DOBROPISOVANAdobropisovaná je len časť, zvyšok (zostava) vybavený nie je; vystavte ho čiastočným dobropisom, viď 6.
409 ERR_IDEMPOTENCY_KONFLIKTIdempotency-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.
401kľúč neplatný, odvolaný, alebo prišlo „odhlásiť všade"
403 agent_missing_scopekľúč 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_DOKLADUdoklad 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_LIMITstrop 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:

ChybaKde je kódTvar 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 endpointreason, 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 vyPrečo v zozname nie je
chýba hlavička Authorization401nevieme, čie volanie to bolo
volanie na bezucto.sk bez www301presmerovanie sa vybaví pred overením kľúča
volanie na zlú adresu, firewall, DNSchyba spojenia alebo cudzia odpoveďk nám sa nedostalo
globálny strop podľa IP (429)429strop 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).

PoleNačo
rezim: "oss_68b"vyradí doklad zo slovenského priznania aj z kontrolného výkazu A.1
krajina_spotrebyISO-2 kód členského štátu kupujúceho, napr. "DE"
polozky[].dphsadzba 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ď:

⚠ 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ť:

ÚkonKódPrečo
úprava dokladu (PUT)ERR_OSS_EDIT_NEPODPOROVANYevidencia OSS sa s úpravou zatiaľ nezosúladí
konverzia proformyERR_OSS_KONVERZIA_NEPODPOROVANAkonverzia 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:

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áciaKód
pôvodná faktúra v režime § 68b bez krajiny spotreby: opravu nie je kam vykázať; doplňte krajinu a zopakujteERR_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 neexistujeERR_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é:

ČoVýsledok
doklad s dvoma sadzbami (DE 19 % zo 100 €, DE 7 % z 30 €)200, číslo prevzaté presne, vs odvodené a vrátené
evidencia OSSdva riadky, jeden na sadzbu: 100 € / 19 % / 19,00 € a 30 € / 7 % / 2,10 €
ročný súčet k prahu130,00 €, schéma OSS aktivovaná na rok
zaúčtovanie311 / 604 na základ (položky mali typ: "tovar"), daň zvlášť za každú sadzbu
druhé doručenie toho istého čísla200 { "idempotentne": true }, nič sa nezdvojilo
stornoevidencia 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].