Starting with version 2024.3, two new sub-listings (relations) are available in the API for deducting advances from an invoice:

Advances for deduction — returns a list of tax documents for advance payments (ZDD) and non-accounting advances that can be deducted from the given invoice.
Amounts for deduction — returns the amounts that can still be deducted from the given advance or ZDD. The response structure is the same as for advances for deduction.

💡 Both sub-listings share the same 12 properties — zaloha, ucetni, sumOsv, sumZklZakl, sumZklSniz, sumZklSniz2, sumDphZakl, sumDphSniz, sumDphSniz2, sumCelkZakl, sumCelkSniz, and sumCelkSniz2.

Calling method

You can use the HTTP method GET. The sub-listings are available at the following addresses, where {firma} is the company identifier and {ID} is the identifier of the selected invoice (for amounts for deduction, the identifier of the advance invoice or ZDD).

Advances for deduction:

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

Or alternatively as a relation:

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

Amounts for deduction:

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

Or alternatively as a relation:

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

The following output formats are supported: XML, JSON, and others. No parameters are required to generate the output.

⚠️ Retrieve the list of attributes from the singular-form listings — zaloha-k-odpoctu/properties and castky-k-odpoctu/properties. The address zalohy-k-odpoctu/properties (plural form) returns 500, since it is the name of the relation, not the listing.

Listing advances for deduction for a selected invoice

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

Output:

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

Output properties

The ucetni property indicates how the document will be deducted from an accounting perspective:

true — the given document would be deducted as a ZDD,
false — the given document would be deducted as a non-accounting advance.

The amounts shown are in the document's currency. Non-accounting advances have an amount only in the sumOsv field.

Listing amounts for deduction of a given advance

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

Output:

{
  "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"
      }
    ]
  }
}

Listing amounts for deduction as a relation

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

Output (shortened, other invoice properties omitted):

{
  "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"
          }
        ]
      }
    ]
  }
}

Call result

To determine whether the API request was completed successfully, you can check the HTTP status of the response. If the service call is successful, status 200 is returned along with a document in the selected format (XML, JSON, etc.). If it fails, status 4xx/5xx is returned along with a message describing the reason for failure; for invalid calls, the content includes a description of the error.

An empty output is valid — if no documents can be deducted from the invoice, the output is an empty response (the same applies to amounts for deduction):

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

ℹ️ An empty response therefore does not indicate an error. Conversely, an incorrect relation name will return 404 with code adresaNeplatnaUrl, so you can easily distinguish a typo in the URL from an empty result.

# REST API Deductible Amounts