API odpoveď

Čo má vrátiť API po odoslaní eFaktúry?

Krátka odpoveď

API odpoveď po odoslaní má byť strojovo spracovateľná. Mala by obsahovať interné ID faktúry, ID pokusu, transakčné ID partnera, aktuálny stav, čas, hash XML, prípadné warnings a errors. Ak je odoslanie asynchrónne, odpoveď nemá predstierať doručenie, ale jasne povedať, že stav ešte čaká.

ID

Faktúra a pokus

Rozlišujte doklad a konkrétny send attempt.

Status

Aktuálny stav

Napríklad accepted, queued, failed alebo delivered podľa mapovania.

Hash

Väzba na XML

Odpoveď má byť viazaná na presný obsah.

Errors

Kódy a správy

Chyba má byť opraviteľná, nie záhadná.

Podrobné vysvetlenie

Najhoršia odpoveď je iba text 'OK'. ERP potrebuje údaje, podľa ktorých vie stav uložiť, neskôr aktualizovať a spárovať s webhookom. Pri chybe má API vrátiť kód, správu pre človeka a technický detail pre podporu.

Ako to vyplýva zo zákona

Preukázateľnosť procesu vyžaduje, aby odoslanie a neskoršie doručovacie stavy boli spätne spojiteľné s konkrétnym dokladom a pokusom.

Praktické príklady

  • API vráti status queued a submissionId pre ďalšie sledovanie.
  • Chyba endpoint-not-found sa uloží k dokladu a vytvorí úlohu fakturantovi.
  • Webhook neskôr príde s rovnakým submissionId a stavom delivered.

Najčastejšie chyby

  • „Stačí HTTP 200.“ HTTP stav nie je obchodný ani doručovací stav faktúry.
  • „API môže vrátiť doručené hneď.“ Iba ak to partner naozaj potvrdil.
  • „Chyby môžu byť voľný text.“ Potrebujete kódy pre automatizované spracovanie.

Záver

API odpoveď má byť dôkazný a integračný záznam, nie iba potvrdenie technického prijatia requestu.

Právny základ

  • Zákon č. 222/2004 Z. z. o DPH, § 76a
  • Interná API dokumentácia
  • Doručovacie statusy partnera

Súvisiace otázky

Nie je to právne poradenstvo. Zdroje: zákon č. 222/2004 Z. z. o DPH, Finančná správa SR eFaktúra FAQ, OpenPeppol BIS Billing 3.0 a interný validačný model eFaktúra centra. Overené 7. 7. 2026.