Od verze 2024.3 jsou v API k dispozici dvě nové sub-evidence (relace) pro odpočty záloh od faktury:

Zálohy k odpočtu — vrací seznam ZDD a neúčetních záloh, které lze od dané faktury odpočítat.
Částky k odpočtu — vrací částky, které lze ještě od dané zálohy či ZDD odpočítat. Struktura odpovědi je stejná jako u záloh k odpočtu.

💡 Obě sub-evidence mají shodných 12 vlastností — zaloha, ucetni, sumOsv, sumZklZakl, sumZklSniz, sumZklSniz2, sumDphZakl, sumDphSniz, sumDphSniz2, sumCelkZakl, sumCelkSniz a sumCelkSniz2.

Způsob volání

Lze využít HTTP metodu GET. Sub-evidence jsou dostupné na následujících adresách, kde {firma} je identifikátor firmy a {ID} identifikátor vybrané faktury (u částek k odpočtu identifikátor zálohové faktury nebo ZDD).

Zálohy k odpočtu:

GET https://demo.flexibee.eu/c/{firma}/faktura-vydana/{ID}/zalohy-k-odpoctu.xml

Případně jako relace:

GET https://demo.flexibee.eu/c/{firma}/faktura-vydana/{ID}.xml?relations=zalohy-k-odpoctu

Částky k odpočtu:

GET https://demo.flexibee.eu/c/{firma}/faktura-vydana/{ID}/castky-k-odpoctu.xml

Případně jako relace:

GET https://demo.flexibee.eu/c/{firma}/faktura-vydana/{ID}.xml?relations=castky-k-odpoctu

Podporovány jsou výstupní formáty XML, JSON a další. Pro generování výstupu nejsou nutné žádné parametry.

⚠️ Seznam atributů si vytáhněte z evidencí v jednotném čísle — zaloha-k-odpoctu/properties a castky-k-odpoctu/properties. Adresa zalohy-k-odpoctu/properties (množné číslo) vrací 500, protože jde o název relace, nikoli evidence.

Výpis záloh k odpočtu u vybrané faktury

GET https://demo.flexibee.eu/c/demo/faktura-vydana/123/zalohy-k-odpoctu.xml

Výstup:

<winstrom>
  <zaloha-k-odpoctu>
    <zaloha ref="/c/demo/faktura-vydana/126.xml" showAs="VF1-0005/2024">code:VF1-0005/2024</zaloha>
    <ucetni>true</ucetni>
    <sumOsv>0.0</sumOsv>
    <sumZklZakl>3305.79</sumZklZakl>
    <sumZklSniz>0.0</sumZklSniz>
    <sumZklSniz2>0.0</sumZklSniz2>
    <sumDphZakl>694.22</sumDphZakl>
    <sumDphSniz>0.0</sumDphSniz>
    <sumDphSniz2>0.0</sumDphSniz2>
    <sumCelkZakl>4000.01</sumCelkZakl>
    <sumCelkSniz>0.0</sumCelkSniz>
    <sumCelkSniz2>0.0</sumCelkSniz2>
  </zaloha-k-odpoctu>
  <zaloha-k-odpoctu>
    <zaloha ref="/c/demo/faktura-vydana/127.xml" showAs="VF2-0003/2024">code:VF2-0003/2024</zaloha>
    <ucetni>false</ucetni>
    <sumOsv>9500.0</sumOsv>
    <sumZklZakl>0.0</sumZklZakl>
    <sumZklSniz>0.0</sumZklSniz>
    <sumZklSniz2>0.0</sumZklSniz2>
    <sumDphZakl>0.0</sumDphZakl>
    <sumDphSniz>0.0</sumDphSniz>
    <sumDphSniz2>0.0</sumDphSniz2>
    <sumCelkZakl>0.0</sumCelkZakl>
    <sumCelkSniz>0.0</sumCelkSniz>
    <sumCelkSniz2>0.0</sumCelkSniz2>
  </zaloha-k-odpoctu>
</winstrom>

Vlastnosti výstupu

Vlastnost ucetni uvádí, jak bude účetně doklad odpočten:

true — daný doklad by se odpočítával jako ZDD,
false — daný doklad by se odpočítával jako neúčetní záloha.

Uvedené částky jsou v měně dokladu. Neúčetní zálohy mají částku pouze v poli sumOsv.

Výpis částek k odpočtu dané zálohy

GET https://demo.flexibee.eu/c/demo/faktura-vydana/126/castky-k-odpoctu.json

Výstup:

{
  "winstrom": {
    "@version": "1.0",
    "castky-k-odpoctu": [
      {
        "zaloha": "code:VF1-0005/2024",
        "zaloha@ref": "/c/demo/faktura-vydana/126.json",
        "zaloha@showAs": "VF1-0005/2024",
        "ucetni": "true",
        "sumOsv": "0.0",
        "sumZklZakl": "3305.79",
        "sumZklSniz": "0.0",
        "sumZklSniz2": "0.0",
        "sumDphZakl": "694.22",
        "sumDphSniz": "0.0",
        "sumDphSniz2": "0.0",
        "sumCelkZakl": "4000.01",
        "sumCelkSniz": "0.0",
        "sumCelkSniz2": "0.0"
      }
    ]
  }
}

Výpis částek k odpočtu formou relace

GET https://demo.flexibee.eu/c/demo/faktura-vydana/126.json?relations=castky-k-odpoctu

Výstup (zkráceno o ostatní vlastnosti faktury):

{
  "winstrom": {
    "faktura-vydana": [
      {
        "id": "126",
        "kod": "VF1-0005/2024",
        ...
        "odpocAuto": "true",
        "typDoklSkl": "code:STANDARD",
        "castky-k-odpoctu": [
          {
            "zaloha": "code:VF1-0005/2024",
            "zaloha@ref": "/c/demo/faktura-vydana/126.json",
            "zaloha@showAs": "VF1-0005/2024",
            "ucetni": "true",
            "sumOsv": "0.0",
            "sumZklZakl": "3305.79",
            "sumZklSniz": "0.0",
            "sumZklSniz2": "0.0",
            "sumDphZakl": "694.22",
            "sumDphSniz": "0.0",
            "sumDphSniz2": "0.0",
            "sumCelkZakl": "4000.01",
            "sumCelkSniz": "0.0",
            "sumCelkSniz2": "0.0"
          }
        ]
      }
    ]
  }
}

Výsledek volání

Pro rozpoznání, zda byl dotaz na API vykonán úspěšně, lze kontrolovat HTTP status odpovědi. V případě úspěšného vykonání služby je vracen status 200 a dokument odpovídající vybranému formátu (XML, JSON…). V případě neúspěchu je vracen status 4xx/5xx a zpráva o důvodu neúspěchu; u nevalidních volání je obsahem popis chyby.

Prázdný výstup je validní — pokud od faktury nelze žádné doklady odpočítat, výstupem je prázdná odpověď (analogicky pro částky k odpočtu):

{
  "winstrom": {
    "@version": "1.0",
    "zaloha-k-odpoctu": []
  }
}

ℹ️ Prázdná odpověď tedy neznamená chybu. Naopak chybný název relace vrátí 404 s kódem adresaNeplatnaUrl, takže překlep v URL od prázdného výsledku snadno odlišíte.

Související

Související články

Částky k odpočtu - REST API