A cash register or bank account can be matched with one or more issued or received invoices as follows:

<?xml version="1.0"?>
<winstrom version="1.0">
  <banka>
    <!-- uhrazující doklad; může být i "pokladni-pohyb" -->
    <id>code:BANKA1</id>
    <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu -->
    <sparovani>
      <!-- uhrazovaný doklad; pro uhrazení více faktur se element opakuje
           type   - ve spárování lze použít pouze faktury stejného typu (vydané nebo přijaté)
           castka - (volitelný) určuje částku, která se má z faktury uhradit -->
      <uhrazovanaFak type="faktura-vydana" castka="1000">code:FV1</uhrazovanaFak>
      <!-- co dělat se zbytkem, pokud nastane -->
      <zbytek>ignorovat</zbytek>
    </sparovani>
  </banka>
</winstrom>

Matching multiple invoices

A single match can settle multiple invoices at once. When matching multiple invoices, all listed invoices must be of the same invoice type (issued or received). For each invoice being paid, you can specify the castka attribute, whose value limits the total amount to be paid from that invoice.

<?xml version="1.0"?>
<winstrom version="1.0">
  <banka>
    <id>code:BANKA1</id>
    <sparovani>
      <!-- uhrazují se dvě faktury najednou -->
      <uhrazovanaFak type="faktura-vydana" castka="500">code:FV1</uhrazovanaFak>  <!-- z FV1 se uhrazuje 500 -->
      <uhrazovanaFak type="faktura-vydana">code:FV2</uhrazovanaFak>              <!-- z FV2 se uhrazuje celá zbývající částka -->
      <zbytek>ignorovat</zbytek>
    </sparovani>
  </banka>
</winstrom>

The same request in JSON format:

{
  "winstrom": {
    "banka": {
      "id": "code:BANKA1",
      "sparovani": {
        "uhrazovanaFak": [
          { "@content": "code:FV1", "@type": "faktura-vydana", "@castka": "500" },
          { "@content": "code:FV2", "@type": "faktura-vydana" }
        ],
        "zbytek": "ignorovat"
      }
    }
  }
}

ℹ️ The identifier of the invoice being paid can be written in JSON either as "@content" (the canonical notation of the element's content) or directly as the value of the "uhrazovanaFak" key with a type of "uhrazovanaFak@type". Both notations are equivalent — for a non-existent identifier, the server returns 400 nestedObjectNotFound in both cases.

The value of the castka attribute must not exceed the remaining amount due on the invoice being paid. If the value of the castka attribute is lower than the remaining amount due, that particular invoice will always be settled as a partial payment. If the value equals the remaining amount due, the attribute has no effect and the matching proceeds as if it had not been specified.

Remainder

It can happen that the paying amount on the paying document and the sum of the amounts on the invoices being paid do not match (e.g., due to an exchange rate difference or a small outstanding balance of a few cents). In such a case, the import follows the value in the <zbytek> tag.

Value	Import result
`ne`	No remainder is allowed to occur. If the amounts match, the invoices will be fully settled (or partially, if the payment was limited by the `castka` attribute) and the paying document will be matched. If a remainder does occur, this results in a `400 – Částky na uhrazovaném a uhrazujícím dokladu se neshodují` error.
`zauctovat`	The invoices will be fully settled (or partially, if the payment was limited by the `castka` attribute) and the paying document will be matched. An internal document will be created for the remainder.
`ignorovat`	The invoices will be fully settled (or partially, if the payment was limited by the `castka` attribute), but the paying document will not be matched. The remainder is ignored.
`castecnaUhrada`	If the amount on the paying document is smaller than on the document being paid, this constitutes a partial payment. The amount on the paying document is gradually "consumed" to settle the invoices, or the amounts to be paid from them, in the order in which they appear in the `<sparovani>` element. An invoice for which there is not enough remaining amount will be partially settled up to the remaining funds; invoices for which no funds remain are excluded from the matching and remain unpaid. If the amount on the paying document is greater, this results in a `400 – Částečná úhrada nemá smysl, částka na uhrazujícím dokladu je větší než na uhrazovaném` error.
`castecnaUhradaNeboZauctovat`	If the amount on the paying document is greater than on the document being paid, the remainder is posted (an internal document is created) and the paying document will be matched. If it is smaller, this constitutes a partial payment.
`castecnaUhradaNeboIgnorovat`	If the amount on the paying document is greater than on the document being paid, the remainder is ignored and the paying document will not be matched. If it is smaller, this constitutes a partial payment.

⚠️ Any value other than those listed will result in 400 elementInvalidValue: "The value of the 'zbytek' element is invalid."

Additional matching parameters

The following elements can also be specified in the <sparovani> tag. They are optional and are taken from the company settings by default.

<!-- kurzový rozdíl, defaultně z nastavení firmy -->
<krTypDokl></krTypDokl>              <!-- typ dokladu pro kurzový rozdíl -->
<krTypDoklZisk></krTypDoklZisk>      <!-- typ dokladu pro zisk kurzového rozdílu -->
<krTypDoklZtrata></krTypDoklZtrata>  <!-- typ dokladu pro ztrátu kurzového rozdílu -->
<krRada></krRada>                    <!-- řada pro kurzový rozdíl -->

<!-- zbytek, defaultně z nastavení firmy -->
<zbTypDokl></zbTypDokl>              <!-- typ dokladu pro zbytek -->
<zbTypDoklZisk></zbTypDoklZisk>      <!-- typ dokladu pro zisk zbytku -->
<zbTypDoklZtrata></zbTypDoklZtrata>  <!-- typ dokladu pro ztrátu zbytku -->
<zbRada></zbRada>                    <!-- řada pro zbytek -->

Matching a payment in the home currency with an invoice in a foreign currency

In addition to matching documents in the same currency, you can also match a cash register or bank account in the home currency with invoices in a foreign currency. The foreign currency must be the same for all matched invoices. In this case, the paying document is automatically converted to the foreign currency at a rate equal to the ratio of the paying amount on the bank account in the home currency to the total amount being paid on the invoices in the foreign currency.

Matching a payment in a foreign currency with an invoice in a different foreign currency

You can also match a cash register or bank account in a foreign currency with an invoice in a different foreign currency. In this case, the program treats the payment as a complete 1 : 1 payment, and the currency on the paying document does not change. The exchange rate difference is calculated from the difference in amounts in the local currency.

Unmatching

Unmatching can be performed in an analogous way:

<?xml version="1.0"?>
<winstrom version="1.0">
  <banka>
    <id>code:BANKA1</id>
    <odparovani>
      <uhrazovanaFak type="faktura-vydana">code:FV1</uhrazovanaFak>  <!-- nepovinné, lze vícekrát -->
    </odparovani>
  </banka>
</winstrom>

The same in JSON:

{
  "winstrom": {
    "banka": {
      "id": "code:BANKA1",
      "odparovani": {
        "uhrazovanaFak": { "@content": "code:FV1", "@type": "faktura-vydana" }
      }
    }
  }
}

If no document being paid is specified, all documents matched to the given paying document will be unmatched. Matching is idempotent, i.e., the call can be repeated.

Automatic matching

Automatic payment matching can also be triggered via the API. You call the service using the PUT method on the bank or cash register records:

PUT /c/{firma}/banka/automaticke-parovani

You can use filtering to limit which payments are included in the matching:

PUT /c/{firma}/banka/{filtr}/automaticke-parovani

The example below will only match payments entered from March 1, 2020 onward:

PUT /c/{firma}/banka/(datVyst>='2020-03-01')/automaticke-parovani

Parameters can be used to set the matching mode, restrict which accounting periods are searched for documents to be paid, and determine how to handle the difference between the payment and the document being paid:

PUT /c/{firma}/banka/automaticke-parovani
    ?mod=jenVar
    &obdobi=aktualni
    &ignorovat-rozdil-castka=1.5
    &zauctovat-rozdil=true

Parameter	Values and meaning
`mod`	Automatic matching mode: `varCasUcet` — by variable symbol, amount, and account; `varCas` — by variable symbol and amount (default value); `jenVar` — by variable symbol; `jenCastka` — attach, i.e., match when the amount matches but the variable symbol does not.
`obdobi`	In which periods to search for documents to be paid: `aktualni` — current accounting period; `aktualni-predchozi` — current and previous accounting period; `vsechna` — all accounting periods (default value).
`ignorovat-rozdil-castka`	How large a difference between the payment and the document being paid should be ignored. The default value `0.0` — amounts must match exactly; in `jenVar` mode, the difference setting is ignored. This is the difference in the amount in the currency of the bank document, i.e., for a bank document in EUR and `ignorovat-rozdil-castka=1`, a difference of EUR 1 will be ignored.
`zauctovat-rozdil`	Whether documents are posted when payments are merged and the document amounts do not match. The default value `true` — an internal document will be created for the difference between the documents, and the documents will be fully matched.

⚠️ An invalid value for the mod or obdobi parameter will result in a 400 error. The filter belongs in the URL path (/banka/(datVyst>='2020-03-01')/…) — as a query parameter, ?filter= is ignored.

Automatic matching can also be influenced with advanced parameterization. In the advanced variant of automatic matching, the period can be set using the paramParovaniUhradOmezeniObdobiDrgn parameter with the values aktualni, aktualni-predchozi (default for the application), and vsechna (default for the API). Via the API, the parameter is written into the parametr record:

<winstrom version="1.0">
  <parametr>
    <paramK>paramParovaniUhradOmezeniObdobiDrgn</paramK>
    <hodnota>vsechna</hodnota>
  </parametr>
</winstrom>

Original matching method via REST API only

The legacy method, which allowed matching only via the REST API (not via XML import), is also still supported at the URL /c/{firma}/parovani-uhrad:

<?xml version="1.0"?>
<winstrom version="1.0">
  <sparovani>
    <uhrazovanaFak type="faktura-prijata">code:FP1</uhrazovanaFak>  <!-- faktura -->
    <uhrazujiciDokl type="banka">code:BANKA1</uhrazujiciDokl>       <!-- bankovní doklad -->
    <zbytek>ignorovat</zbytek>                                     <!-- zbytek ignorovat -->
  </sparovani>
</winstrom>

Unmatching works the same way:

<?xml version="1.0"?>
<winstrom version="1.0">
  <odparovani>
    <uhrazujiciDokl>code:foo</uhrazujiciDokl>  <!-- povinné -->
    <uhrazovanaFak>code:bar</uhrazovanaFak>    <!-- nepovinné, lze vícekrát -->
  </odparovani>
</winstrom>

📝 For new integrations, use matching via XML import on the banka or pokladni-pohyb record (examples above). The legacy URL /parovani-uhrad remains functional only for backward compatibility.

Payment Matching