Kontrolní hlášení - REST API

Stejně jako v aplikaci je možné získat v XML (PDF) i prostřednictví API Flexi.

Způsob volání

Lze využít HTTP metodu: GET.

Služba je dostupná na adrese: /c/{firma}/kontrolni-hlaseni.{pripona}, kde {firma} je databázový identifikátor firmy.

Jsou podporovány výstupní formáty: XML nebo PDF.

Parametry

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

Upřesnění > Krajský finanční úřad
Firma > DIČ
Jedna z těchto 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

Služba má 5 parametrů, na pořadí parametrů nezáleží:

obdobi - nepovinný, období, pro které má být kontrolní hlášení vygenerováno. Období je možno zadávat jako konkrétní měsíc roku ve formátu yyyyMM (př. 202310 = říjen 2023) nebo jako konkrétní čtvrtletí roku yyyy'Q'M (př. 2023Q2 = druhé čtvrtletí roku 2023). Pokud není uvedeno, tak se použije aktuální rok a měsíc.
druh - nepovinný, druh podání kontrolního hlášení. Možné hodnoty:
- B - řádné,
- O - opravné,
- N - následné,
- E - následné/opravné.
- Pokud není uvedeno, tak je výchozí hodnota B - řádné.
dodatecneOproti - povinný, pokud je podáván slovenský dodatečný výkaz. Integer: ID opravovaného výkazu
- Opravovaný musí být za stejné období jako nové výkaz.
- Seznam uložených výkazů lze získat na adrese GET https://demo.flexibee.eu/c/demo/ulozene-priznani-kon-vyk-dph/(rok={rok} AND mesic={mesic} AND ctvrtleti={ctvrtleti}).xml
vyzvaOdpoved - nepovinný, odpověd na výzvu. Možné hodnoty:
- B - nemám povinnost podat KH (nulové KH),
- O - potvrzuji správnost naposledy podaného KH.
- Pokud není uvedeno, tak je výchozí hodnota prázdná, tedy bez odpovědi.
cisloJednaciVyzvy - povinný, pokud je vyplněn parametr vyzvaOdpoved nebo pokud se jedná o následné nebo opravné podání: Číslo jednací výzvy musí odpovídat vzoru: 12345678/12/1234-12345-123456
datumZjisteni - povinný, pokud se jedná o následné nebo opravné podání:
- Datum, ke kterému byly zjištěny důvody pro podání následného kontrolního hlášení. Datum je možné zadávat ve formátu dd.MM.yyyy nebo yyyy-MM-dd.
stat - nepovinný: Možné hodnoty CZ, SK. Pokud není uveden, použije stát legislativy.
ulozit - nepovinný: Jestli se má výkaz uložit. Pokud není zadán, výkaz se neuloží.

Dostupné druhy podání

Dostupné druhy podání kontrolního hlášení ve formátu xml:

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

Výsledkem jsou obecná form-data ve tvaru:

<?xml version="1.0" ?>
<form-data>
    <statyDph>
        <statDph>
            <kod>CZ</kod>
            <nazev>Česká republika</nazev>
            <nazevA>Czech republic</nazevA>
            <nazevB></nazevB>
            <nazevC></nazevC>
            <dostupneDruhy>
                <druh>
                    <kod>B</kod>
                    <nazev>řádné</nazev>
                    <povinneParametry></povinneParametry>
                </druh>
                <druh>
                    <kod>O</kod>
                    <nazev>opravné</nazev>
                    <povinneParametry>
                        <povinnyParametr>datumZjisteni</povinnyParametr>
                    </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></povinneParametry>
                </druh>
            </dostupneDruhy>
        </statDph>
    </statyDph>
</form-data>

Ukázka volání

Kompletní nejjednodušší volání pak vypadá následovně:

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

Případně pro PDF:

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

Výsledek volání

Výsledek je pak kontrolní hlášení v XML struktuře pro daňový portál:

<Pisemnost>
    <DPHKH1>
        <VetaD ctvrt="2" d_poddp="21.12.2023" dokument="KH1" k_uladis="DPH" khdph_forma="B" rok="2023"/>
        <VetaP c_orient="1180" c_pop="18" c_ufo="460" dic="25719122" email="podporaflexi@abra.eu" naz_obce="Plzeň" psc="30100" sest_jmeno="Tomáš" sest_prijmeni="Nový" sest_telef="+420724444999" stat="ČESKÁ REPUBLIKA" typ_ds="P" ulice="Lochotínská" zkrobchjm="ABRA Software a.s."/>
        <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řípadně celý PDF soubor při volání s příponou .pdf

Příklady nevalidních volání

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

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 XML či PDF.

V případě nevalidních volání je obsahem popis chyby.

1. Nevalidní nastavení firmy

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

Výsledek je chyby je odpověď HTTP Status 400 Bad request a popis chyby:

<?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. Nevalidní zadání parametrů

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdbi=2023Q2&vyzvaOdpoved=A

Výsledek je chyby je odpověď HTTP Status 400 Bad request a popis chyby:

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


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

3. Nevalidní období (nevalidní nepovinný parametr)

GET https://demo.flexibee.eu/c/demo/kontrolni-hlaseni.xml?obdbi=2123Q5

Výsledek je chyby je odpověď HTTP Status 200 OK a výsledek:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Pisemnost>
    <DPHKH1>
        <VetaD d_poddp="21.12.2023" dokument="KH1" k_uladis="DPH" khdph_forma="B" mesic="12" rok="2023"/>
        <VetaP c_orient="1180" c_pop="18" c_ufo="460" dic="25719122" email="podporaflexi@abra.eu" naz_obce="Plzeň" psc="30100" sest_jmeno="Tomáš" sest_prijmeni="Nový" sest_telef="+420724444999" stat="ČESKÁ REPUBLIKA" typ_ds="P" ulice="Lochotínská" zkrobchjm="ABRA Software a.s."/>
        <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>
¨

Pozor: jelikož je parametr nepovinný, rok = 2123 a 5. kvartál, volání i přesto projde a vrátí se aktuální rok a měsíc.

FAQ

Kontrolní hlášení v GUI

Další účetní výstupy v API

Číslo jednací výzvy

Nelze exportovat do XML pro FÚ?

Potřebujete poradit?

V případě dotazů k aplikaci nás kontaktujte na podporaflexi@abra.eu případně prostřednictvím chat okna v pravém dolním rohu.

Související články

Přiznání DPH - REST API

Inventura v REST API

Smlouvy v API

Souhrnné hlášení k DPH - REST API

Práce pro střediska - REST API