Kontrolní hlášení lze získat v XML i PDF nejen v aplikaci, ale i prostřednictvím REST API ABRA Flexi.

Způsob volání

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

Předpoklady v nastavení firmy

Pro úspěšné vygenerování kontrolního hlášení musí být v nastavení firmy vyplněny tyto údaje:

Upřesnění → Krajský finanční úřad
Firma → DIČ
jedna z hodnot Firma → Sídlo/Trv. bydliště → E-mail, nebo 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

Pokud některý z údajů chybí, vrátí služba 400 Bad Request s jejich výčtem — viz příklady nevalidních volání.

Parametry

Na pořadí parametrů nezáleží.

Parametr	Povinnost	Význam
`obdobi`	nepovinný	Období, pro které má být kontrolní hlášení vygenerováno. Zadává se jako konkrétní měsíc roku ve formátu `yyyyMM` (např. `202410` = říjen 2024), nebo jako čtvrtletí ve formátu `yyyy'Q'M` (např. `2024Q2` = druhé čtvrtletí roku 2024). Pokud není uvedeno, použije se aktuální rok a měsíc.
`druh`	nepovinný	Druh podání. Pro české hlášení `B` (řádné), `O` (opravné), `N` (následné) a `E` (následné/opravné), výchozí je `B`. Pro slovenský výkaz `R` (řádné), `O` (opravné) a `D` (dodatečné), výchozí je `R`.
`datumZjisteni`	povinný u druhů `N` a `E`	Datum, ke kterému byly zjištěny důvody pro podání následného kontrolního hlášení. Formát `dd.MM.yyyy` nebo `yyyy-MM-dd`.
`dodatecneOproti`	povinný u slovenského dodatečného výkazu	Celé číslo — ID opravovaného výkazu. Opravovaný výkaz musí být za stejné období jako nový.
`vyzvaOdpoved`	nepovinný	Odpověď na výzvu. Hodnota `B` znamená „nemám povinnost podat kontrolní hlášení" (nulové KH), hodnota `P` potvrzuje správnost naposledy podaného hlášení. Pokud parametr neuvedete, odpověď na výzvu se do hlášení nepropíše.
`cisloJednaciVyzvy`	povinný, je-li vyplněn `vyzvaOdpoved`	Číslo jednací výzvy ve formátu `99999999/99/9999-99999-999999`, například `12345678/12/1234-12345-123456`.
`stat`	nepovinný	Hodnoty `CZ` a `SK`. Pokud není uveden, použije se stát legislativy firmy.
`ulozit`	nepovinný	Zda se má výkaz uložit. Pokud není zadán, výkaz se neuloží.

Seznam uložených výkazů získáte z evidence ulozene-priznani-kon-vyk-dph, například:

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

Dostupné druhy podání

Dostupné druhy podání, jejich povinné parametry a dostupné reporty vrací pro jednotlivé státy adresa /c/{firma}/kontrolni-hlaseni/form-data.xml:

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

Výsledkem jsou form-data, jejichž zkrácená podoba pro českou legislativu vypadá 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ázky volání

Kontrolní hlášení ve formátu XML pro druhé čtvrtletí roku 2024, případně totéž 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ášení za říjen 2024:

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

Výsledek volání

V případě úspěšného vykonání služby je vracen HTTP status 200 společně s tělem v požadovaném formátu. Výsledkem je kontrolní hlášení v XML struktuře pro daňový portál (hodnoty jsou ilustrativní):

<?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>

Při volání s příponou .pdf je výsledkem celý PDF soubor kontrolního hlášení.

Data vygenerovaného hlášení

Samotná data vygenerovaného kontrolního hlášení jsou dostupná na adrese /c/{firma}/kontrolni-hlaseni-dph.{přípona} ve formátech json a xml. Vyžadovány jsou parametry rok a ctvrtleti nebo mesic. Použít lze filtraci, řazení záznamů zde dostupné není.

Dvěma dalšími parametry lze dohledat problematické položky — clenKonVykNull=true zobrazí položky, které nemají vyplněný řádek kontrolního hlášení, a kodSkTooLong=true položky, které mají pro Slovensko příliš dlouhé čí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

Příklady nevalidních volání

V případě nevalidních volání je vracen status 4xx nebo 5xx a obsahem odpovědi je popis chyby.

1. Nevalidní nastavení firmy

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

Odpovědí je 400 Bad Request s výčtem chybějících údajů:

<?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. Chybějící číslo jednací výzvy

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

Odpovědí je 400 Bad Request s kódem 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 parametru

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

Odpovědí je 400 Bad Request s kódem 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>

Obdobně u parametru druh je u české legislativy nabídnut výčet [B, O, N, E]. Chybný formát čísla jednacího vrací 400 s kódem illegal_parameter_exception a očekávaným vzorem.

⚠️ Hodnota parametru obdobi se nekontroluje proti rozsahu měsíců a čtvrtletí. Nesmyslné období, například 2124Q5, projde s odpovědí 200 OK, ale přebývající čtvrtletí se přenese do dalšího roku — v tomto případě vznikne hlášení za první čtvrtletí roku 2125. Před voláním si proto období ověřte na své straně.

FAQ

Jak kontrolní hlášení vytvořím v aplikaci?

Postup najdete v článku Kontrolní hlášení.

Kde v aplikaci zadám číslo jednací výzvy?

Odpověď najdete v článku Kontrolní hlášení - číslo jednací výzvy.

Proč nelze hlášení exportovat do XML pro finanční úřad?

Nejčastější příčiny popisuje článek Kontrolní hlášení nelze exportovat do XML pro FÚ.

Jaké další účetní výstupy lze přes API získat?

Přehled najdete v článku Účetní výstupy v REST API.

Související

Související články

Kontrolní hlášení - REST API