Rovnako ako v aplikácii je možné získať v XML (PDF) aj prostredníctvom API Flexi.

Spôsob volania

Možno využiť HTTP metódu: GET.

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

Sú podporované výstupné formáty: XML alebo PDF.

Parametre

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

Upresnenie > Krajský daňový úrad
Firma > DIČ
Jedna z týchto hodnôt:
- Firma > Sídlo/Trv. bydlisko > E-mail
- Firma > Sídlo/Trv. bydlisko > Dátová schránka
- Upresnenie - Zástupca - Názov právnickej osoby
  Upresnenie - Zástupca - IČO právnickej osoby

Služba má 5 parametrov, na poradí parametrov nezáleží:

obdobi - nepovinný, obdobie, pre ktoré má byť kontrolné hlásenie vygenerované. Obdobie je možné zadávať ako konkrétny mesiac roka vo formáte yyyyMM (napr. 202310 = október 2023) alebo ako konkrétny štvrťrok roka yyyy'Q'M (napr. 2023Q2 = druhý štvrťrok roka 2023). Ak nie je uvedené, použije sa aktuálny rok a mesiac.
druh - nepovinný, druh podania kontrolného hlásenia. Možné hodnoty:
- B - riadne,
- O - opravné,
- N - následné,
- E - následné/opravné.
- Ak nie je uvedené, predvolená hodnota je B - riadne.
dodatecneOproti - povinný, ak sa podáva slovenský dodatočný výkaz. Integer: ID opravovaného výkazu
- Opravovaný musí byť za rovnaké obdobie ako nový výkaz.
- Zoznam uložených výkazov možno získať 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ý, odpoveď na výzvu. Možné hodnoty:
- B - nemám povinnosť podať KH (nulové KH),
- O - potvrdzujem správnosť naposledy podaného KH.
- Ak nie je uvedené, predvolená hodnota je prázdna, teda bez odpovede.
cisloJednaciVyzvy - povinný, ak je vyplnený parameter vyzvaOdpoved alebo ak ide o následné alebo opravné podanie: Číslo jednací výzvy musí zodpovedať vzoru: 12345678/12/1234-12345-123456
datumZjisteni - povinný, ak ide o následné alebo opravné podanie:
- Dátum, ku ktorému boli zistené dôvody na podanie následného kontrolného hlásenia. Dátum je možné zadávať vo formáte dd.MM.yyyy alebo yyyy-MM-dd.
stat - nepovinný: Možné hodnoty CZ, SK. Ak nie je uvedený, použije sa štát legislatívy.
ulozit - nepovinný: Či sa má výkaz uložiť. Ak nie je zadaný, výkaz sa neuloží.

Dostupné druhy podania

Dostupné druhy podania kontrolného hlásenia vo formáte xml:

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

Výsledkom sú všeobecné form-data v tvare:

<?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ážka volania

Kompletné najjednoduchšie volanie vyzerá nasledovne:

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

Prípadne pre PDF:

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

Výsledok volania

Výsledkom je kontrolné hlásenie v XML štruktúre pre 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>

Prípadne celý PDF súbor pri volaní s príponou .pdf

Príklady nevalidných volaní

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

V prípade úspešného vykonania služby je vrátený HTTP status 200 spolu s telom v požadovanom formáte XML alebo PDF.

V prípade nevalidných volaní je obsahom popis chyby.

1. Nevalidné nastavenie firmy

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

Výsledkom chyby je odpoveď 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é zadanie parametrov

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

Výsledkom chyby je odpoveď 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é obdobie (nevalidný nepovinný parameter)

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

Výsledkom chyby je odpoveď HTTP Status 200 OK a výsledok:

<?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: keďže parameter je nepovinný, rok = 2123 a 5. kvartál, volanie aj napriek tomu prebehne a vráti sa aktuálny rok a mesiac.