Kontrolné hlásenie je možné získať v XML aj PDF nielen v aplikácii, ale aj prostredníctvom REST API ABRA Flexi.

Spôsob volania

Služba je dostupná metódou GET na adrese /c/{firma}/kontrolni-hlaseni.{přípona}, kde {firma} je databázový identifikátor firmy. Podporovanými výstupnými formátmi sú xml a pdf.

Predpoklady v nastavení firmy

Pre úspešné vygenerovanie kontrolného hlásenia musia byť v nastavení firmy vyplnené tieto údaje:

Upresnenie → Krajský finančný úrad
Firma → DIČ
jedna z hodnôt Firma → Sídlo/Trvalý pobyt → E-mail, alebo Firma → Sídlo/Trvalý pobyt → Dátová schránka
Upresnenie → Zástupca → Názov právnickej osoby
Upresnenie → Zástupca → IČO právnickej osoby

Ak niektorý z údajov chýba, vráti služba 400 Bad Request s ich výpočtom — pozri príklady nevalidných volaní.

Parametre

Na poradí parametrov nezáleží.

Parameter	Povinnosť	Význam
`obdobi`	nepovinný	Obdobie, pre ktoré má byť kontrolné hlásenie vygenerované. Zadáva sa ako konkrétny mesiac roka vo formáte `yyyyMM` (napr. `202410` = október 2024), alebo ako štvrťrok vo formáte `yyyy'Q'M` (napr. `2024Q2` = druhý štvrťrok roka 2024). Ak nie je uvedené, použije sa aktuálny rok a mesiac.
`druh`	nepovinný	Druh podania. Pre české hlásenie `B` (riadne), `O` (opravné), `N` (následné) a `E` (následné/opravné), predvolené je `B`. Pre slovenský výkaz `R` (riadne), `O` (opravné) a `D` (dodatočné), predvolené je `R`.
`datumZjisteni`	povinný pri druhoch `N` a `E`	Dátum, ku ktorému boli zistené dôvody na podanie následného kontrolného hlásenia. Formát `dd.MM.yyyy` alebo `yyyy-MM-dd`.
`dodatecneOproti`	povinný pri slovenskom dodatočnom výkaze	Celé číslo — ID opravovaného výkazu. Opravovaný výkaz musí byť za rovnaké obdobie ako nový.
`vyzvaOdpoved`	nepovinný	Odpoveď na výzvu. Hodnota `B` znamená „nemám povinnosť podať kontrolné hlásenie" (nulové KH), hodnota `P` potvrdzuje správnosť naposledy podaného hlásenia. Ak parameter neuvediete, odpoveď na výzvu sa do hlásenia nepremietne.
`cisloJednaciVyzvy`	povinný, ak je vyplnený `vyzvaOdpoved`	Číslo jednacie výzvy vo formáte `99999999/99/9999-99999-999999`, napríklad `12345678/12/1234-12345-123456`.
`stat`	nepovinný	Hodnoty `CZ` a `SK`. Ak nie je uvedený, použije sa štát legislatívy firmy.
`ulozit`	nepovinný	Či sa má výkaz uložiť. Ak nie je zadaný, výkaz sa neuloží.

Zoznam uložených výkazov získate z evidencie ulozene-priznani-kon-vyk-dph, napríklad:

GET https://demo.flexibee.eu/c/demo/ulozene-priznani-kon-vyk-dph/(rok eq 2024 and ctvrtleti eq 2).xml

Dostupné druhy podania

Dostupné druhy podania, ich povinné parametre a dostupné reporty vracia pre jednotlivé štáty adresa /c/{firma}/kontrolni-hlaseni/form-data.xml:

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni/form-data.xml

Výsledkom sú form-data, ktorých skrátená podoba pre českú legislatívu vyzerá takto:

<?xml version="1.0" ?>
<form-data>
  <statyDph>
    <statDph>
      <dostupneReporty>
        <report>
          <reportId>kontrolniVykazPrehledCZ$$SUM</reportId>
          <reportName>Kontrolní řádky na Daňové přiznání k DPH (DaP)</reportName>
        </report>
      </dostupneReporty>
      <kod>CZ</kod>
      <nazev>Česká republika</nazev>
      <supportXml>true</supportXml>
      <supportPdf>true</supportPdf>
      <dostupneDruhy>
        <druh>
          <kod>B</kod>
          <nazev>řádné</nazev>
          <povinneParametry></povinneParametry>
        </druh>
        <druh>
          <kod>O</kod>
          <nazev>opravné</nazev>
          <povinneParametry></povinneParametry>
        </druh>
        <druh>
          <kod>N</kod>
          <nazev>následné</nazev>
          <povinneParametry>
            <povinnyParametr>datumZjisteni</povinnyParametr>
          </povinneParametry>
        </druh>
        <druh>
          <kod>E</kod>
          <nazev>následné/opravné</nazev>
          <povinneParametry>
            <povinnyParametr>datumZjisteni</povinnyParametr>
          </povinneParametry>
        </druh>
      </dostupneDruhy>
    </statDph>
  </statyDph>
</form-data>

Ukážky volania

Kontrolné hlásenie vo formáte XML za druhý štvrťrok roka 2024, prípadne to isté v PDF:

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdobi=2024Q2
GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.pdf?obdobi=2024Q2

Následné kontrolné hlásenie za október 2024:

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdobi=202410&druh=N&datumZjisteni=2024-10-10

Výsledok volania

V prípade úspešného vykonania služby je vrátený HTTP status 200 spolu s telom v požadovanom formáte. Výsledkom je kontrolné hlásenie v XML štruktúre pre daňový portál (hodnoty sú ilustratívne):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Pisemnost>
  <DPHKH1>
    <VetaD ctvrt="2" d_poddp="21.07.2024" dokument="KH1" k_uladis="DPH" khdph_forma="B" rok="2024"/>
    <VetaP c_orient="1" c_pop="1" c_ufo="460" dic="CZ12345678" email="info@vzorovafirma.cz" naz_obce="Praha" psc="10000" stat="ČESKÁ REPUBLIKA" typ_ds="P" ulice="Ulice 1" zkrobchjm="Vzorová firma s.r.o."/>
    <VetaA5 dan1="0.00" dan2="0.00" dan3="0.00" zakl_dane1="0.00" zakl_dane2="0.00" zakl_dane3="0.00"/>
    <VetaB3 dan1="0.00" dan2="0.00" dan3="0.00" zakl_dane1="0.00" zakl_dane2="0.00" zakl_dane3="0.00"/>
    <VetaC celk_zd_a2="0.00" obrat23="0.00" obrat5="0.00" pln23="0.00" pln5="0.00" pln_rez_pren="0.00" rez_pren23="0.00" rez_pren5="0.00"/>
  </DPHKH1>
</Pisemnost>

Pri volaní s príponou .pdf je výsledkom celý PDF súbor kontrolného hlásenia.

Dáta vygenerovaného hlásenia

Samotné dáta vygenerovaného kontrolného hlásenia sú dostupné na adrese /c/{firma}/kontrolni-hlaseni-dph.{přípona} vo formátoch json a xml. Vyžadované sú parametre rok a ctvrtleti alebo mesic. Použiť je možné filtrovanie, radenie záznamov tu dostupné nie je.

Dvoma ďalšími parametrami je možné dohľadať problematické položky — clenKonVykNull=true zobrazí položky, ktoré nemajú vyplnený riadok kontrolného hlásenia, a kodSkTooLong=true položky, ktoré majú pre Slovensko príliš dlhé číslo došlé.

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni-dph.json?rok=2024&ctvrtleti=2
GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni-dph.json?rok=2024&ctvrtleti=2&clenKonVykNull=true
GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni-dph.json?rok=2024&ctvrtleti=2&kodSkTooLong=true

Príklady nevalidných volaní

V prípade nevalidných volaní je vrátený status 4xx alebo 5xx a obsahom odpovede je popis chyby.

1. Nevalidné nastavenie firmy

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdobi=2024Q2

Odpoveďou je 400 Bad Request s výpočtom chýbajúcich údajov:

<?xml version="1.0" ?>
<winstrom version="1.0">
  <success>false</success>
  <message>V nastavení firmy chybí tyto údaje:
Upřesnění - Krajský finanční úřad
Jedna z hodnot:
  - Firma - Sídlo/Trv. bydliště - E-mail
  - Firma - Sídlo/Trv. bydliště - Datová schránka
Upřesnění - Zástupce - Název právnické osoby
Upřesnění - Zástupce - IČO právnické osoby</message>
</winstrom>

2. Chýbajúce číslo jednacie výzvy

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdobi=2024Q2&vyzvaOdpoved=B

Odpoveďou je 400 Bad Request s kódom missing_param_exception:

<winstrom version="1.0">
  <success>false</success>
  <message>K provedení operace je vyžadován parametr 'cisloJednaciVyzvy'</message>
</winstrom>

3. Nepodporovaná hodnota parametra

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdobi=2024Q2&vyzvaOdpoved=A&cisloJednaciVyzvy=12345678/12/1234-12345-123456

Odpoveďou je 400 Bad Request s kódom unsupported_param_value_exception:

<winstrom version="1.0">
  <success>false</success>
  <message>Parametr 'vyzvaOdpoved' má nepodporovanou hodnotu! Zvolte jednu z následujících možností: [B, P]</message>
</winstrom>

Obdobne pri parametri druh je pre českú legislatívu ponúknutý výpočet [B, O, N, E]. Chybný formát čísla jednacieho vracia 400 s kódom illegal_parameter_exception a očakávaným vzorom.

⚠️ Hodnota parametra obdobi sa nekontroluje voči rozsahu mesiacov a štvrťrokov. Nezmyselné obdobie, napríklad 2124Q5, prejde s odpoveďou 200 OK, ale prebytočný štvrťrok sa prenesie do ďalšieho roka — v tomto prípade vznikne hlásenie za prvý štvrťrok roka 2125. Pred volaním si preto obdobie overte na svojej strane.

FAQ

Ako kontrolné hlásenie vytvorím v aplikácii?

Postup nájdete v článku Kontrolné hlásenie.

Kde v aplikácii zadám číslo jednacie výzvy?

Odpoveď nájdete v článku Kontrolné hlásenie - číslo jednacie výzvy.

Prečo nie je možné hlásenie exportovať do XML pre finančný úrad?

Najčastejšie príčiny popisuje článok Kontrolné hlásenie nie je možné exportovať do XML pre FÚ.

Aké ďalšie účtovné výstupy je možné cez API získať?

Prehľad nájdete v článku Účtovné výstupy v REST API.

Súvisiace

Sorodni članki

Kontrolné hlásenie – REST API