When creating documents (e.g., invoices), it is necessary to allow deduction by another document (e.g., an advance payment). The collection <odpocty-zaloh> with individual <odpocet> elements is used for this purpose.
In addition to deducting advances and tax documents for advance payments (ZDD), you can also create an invoice directly from paid advances. See how to do it.
Deducting an advance payment (issuing a tax document for the payment)
<?xml version="1.0"?>
<winstrom version="1.0">
<faktura-vydana>
<id>code:VF-123/2021</id>
<!-- Typ faktury (objekt) - max. délka: 20 -->
<typDokl>code:FAKTURA</typDokl>
<!-- ...další náležitosti faktury -->
<polozkyFaktury>
<faktura-vydana-polozka>
<cenik>code:CANON XS1</cenik>
<typPolozkyK>typPolozky.katalog</typPolozkyK>
<mnozMj>1.0</mnozMj>
<sklad>code:SKLAD</sklad>
</faktura-vydana-polozka>
</polozkyFaktury>
<odpocty-zaloh>
<odpocet>
<!-- odpočet zálohy -->
<castkaMen>16300.0</castkaMen> <!-- částka v měně určená pro odpočet -->
<doklad>code:ZALOHA0001/2010</doklad> <!-- identifikátor dokladu pro odpočet -->
<id>ext:odpocet1</id> <!-- externí identifikátor vytvořené odpočtové položky -->
</odpocet>
</odpocty-zaloh>
</faktura-vydana>
</winstrom>
Example in JSON (does not include the faktura-vydana-polozka and odpocet elements, since in JSON they are written as array items):
{
"winstrom": {
"faktura-vydana": {
"polozkyFaktury": [
{
"cenik": "code:CANON XS1",
"sklad": "code:SKLAD",
"mnozMj": 1
}
],
"odpocty-zaloh": [
{
"castkaMen": 16300,
"doklad": "code:ZALOHA0001/2021"
}
],
"typDokl": "code:FAKTURA"
}
}
}
Deducting a ZDD (tax document for an advance payment)
For a tax document for an advance payment, instead of a single amount, amounts are listed by VAT rate:
<winstrom version="1.0">
<faktura-vydana>
<id>code:VF-12/2014</id>
<!-- Typ faktury (objekt) - max. délka: 20 -->
<typDokl>code:FAKTURA</typDokl>
<odpocty-zaloh>
<odpocet>
<!-- odpočet zdd -->
<castkaZaklMen>400.0</castkaZaklMen> <!-- částka základní sazby v měně určená pro odpočet -->
<castkaSnizMen>400.0</castkaSnizMen> <!-- částka snížené sazby v měně určená pro odpočet -->
<castkaSniz2Men>400.0</castkaSniz2Men> <!-- částka 2. snížené sazby v měně určená pro odpočet -->
<castkaOsvMen>400.0</castkaOsvMen> <!-- částka osvobozená od DPH v měně určená pro odpočet -->
<doklad>code:ZDD0001/2010</doklad> <!-- identifikátor dokladu pro odpočet -->
<id>ext:odpocet1</id> <!-- externí identifikátor vytvořených odpočtových položek -->
<!-- identifikátor jednotlivých položek je doplněn o postfix -ZAKL, -SNIZ, -SNIZ2, -OSV -->
<castkyBezDph>true</castkyBezDph> <!-- zda jsou uvedené částky včetně, nebo bez DPH -->
<skupPlneni>code:TEPLO</skupPlneni> <!-- identifikátor skupiny plnění, příp. ALL nebo OTHER, nepovinné -->
<prijmoutDoporuceni>true</prijmoutDoporuceni> <!-- zda se má automaticky aplikovat doporučení úpravy faktury, nepovinné -->
<castkyVseDostupne>true</castkyVseDostupne> <!-- pokud je true, odpočítá se ze zálohy vše, co ještě není odpočteno, nepovinné -->
</odpocet>
</odpocty-zaloh>
</faktura-vydana>
</winstrom>
Deduction method
When deducting a tax document for an advance payment, deduction items are first created based on the amounts available on the invoice (VAT rates are taken from the invoice). Then, for any remaining amount to be deducted, overpayment deduction items are created (using VAT rates from the ZDD).
Amounts excluding VAT vs. including VAT
The castkyBezDph element determines whether the specified amounts include VAT or exclude VAT. For backward compatibility, the default value is false, but since ZDD deductions internally work with amounts excluding VAT, we recommend sending amounts excluding VAT.
⚠️ For non-accounting advances, castkyBezDph cannot be used — the call will end with a 400 error with the code zalohyXmlZalohaCastkyBezDph: "Amounts excluding VAT cannot be used for non-accounting advances."
Performance group
If the skupPlneni element is specified, the deduction only includes amounts from invoice items with this performance group. If the value is empty, only items without a performance group are included. The performance group is not taken into account if the element is not present or has the value ALL.
The value OTHER (labeled "Other group" in the application) is intended for cases where the items of the final invoice have a different VAT rate than the ZDD — e.g., an invoice with a zero rate and a ZDD at 21%. In this mode, the deduction is not matched to the VAT rates of the invoice items; instead, deduction items are created directly with VAT rates taken from the ZDD.
Automatic invoice adjustment
When deducting a ZDD from an invoice, the goal is often to obtain a fully paid invoice. Due to differences in rounding or VAT correction, it may happen that the invoice is not fully paid. Proper invoice configuration can eliminate this problem, and the system can suggest configuration adjustments.
If <prijmoutDoporuceni>true</prijmoutDoporuceni> is specified, the recommended invoice adjustments will be applied automatically. A list of recommendations can be obtained at:
GET /c/{firma}/faktura-vydana/{ID}/zalohy-k-odpoctu.xml?relations=doporuceni
Deducting all available amounts
Instead of filling in amounts in the castka*Men fields, you can use the castkyVseDostupne element with the value true. This will deduct everything from the advance that has not yet been deducted.
Automatic deduction
When creating documents, you can also use automatic deduction of advance invoices and tax documents for advance payments:
<?xml version="1.0"?>
<winstrom version="1.0">
<faktura-vydana>
<!-- Typ faktury (objekt) - max. délka: 20 -->
<typDokl>code:FAKTURA</typDokl>
<odpocty-zaloh>
<!-- automatický odpočet zálohy a zdd, které mají automatický odpočet povolen v typu dokladu -->
<automaticky-odpocet>true</automaticky-odpocet>
</odpocty-zaloh>
</faktura-vydana>
</winstrom>
ℹ️ Advance invoices and ZDDs must have Allow automatic deduction when creating a new document checked in the document type settings. If you are importing multiple invoices with automatic deduction in a single XML, use the atomic="false" mode.
If you are importing an invoice with rounding configured, first create the invoice and only then deduct the advance documents:
<?xml version="1.0"?>
<winstrom version="1.0">
<faktura-vydana atomic="false">
<!-- Vytvoření faktury se zaokrouhlením -->
<id>ext:mojeId</id>
<typDokl>code:FAKTURA</typDokl>
</faktura-vydana>
<faktura-vydana>
<id>ext:mojeId</id>
<odpocty-zaloh>
<!-- automatický odpočet zálohy a zdd, které mají automatický odpočet povolen v typu dokladu -->
<automaticky-odpocet>true</automaticky-odpocet>
</odpocty-zaloh>
</faktura-vydana>
</winstrom>