Pokladnu nebo banku lze spárovat s jednou nebo více fakturami vydanými nebo přijatými následujícím způsobem:

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

Párování více faktur

V jednom spárování lze uhrazovat více faktur najednou. Při spárování s více fakturami musí být všechny uvedené faktury stejného typu faktury (vydané nebo přijaté). U každé uhrazované faktury lze uvést atribut castka, jehož hodnota omezuje celkovou částku k úhradě, která bude z faktury uhrazena.

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

Stejný požadavek ve formátu JSON:

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

ℹ️ Identifikátor uhrazované faktury lze v JSON zapsat jako "@content" (kanonický zápis obsahu elementu) nebo přímo jako hodnotu klíče "uhrazovanaFak" s typem v "uhrazovanaFak@type". Oba zápisy jsou rovnocenné — u neexistujícího identifikátoru vrátí server v obou případech 400 nestedObjectNotFound.

Hodnota atributu castka nesmí překročit zbývající částku k úhradě na uhrazované faktuře. Je-li hodnota atributu castka menší než zbývající částka k úhradě, bude tato konkrétní faktura vždy uhrazena jako částečná úhrada. Je-li hodnota rovna zbývající částce k úhradě, pak atribut ztrácí význam a spárování proběhne stejně, jako by nebyl uveden.

Zbytek

Může se stát, že uhrazující částka na uhrazujícím dokladu a součet částek na uhrazovaných fakturách nesouhlasí (např. při kurzovém rozdílu nebo když schází doplatit pár korun). V takovém případě se import řídí hodnotou v tagu <zbytek>.

Hodnota	Výsledek importu
`ne`	Zbytek nesmí nastat. Pokud částky souhlasí, budou faktury zcela uhrazeny (nebo částečně, pokud došlo k omezení úhrady atributem `castka`) a uhrazující doklad bude spárován. Pokud zbytek nastane, jde o chybu `400 – Částky na uhrazovaném a uhrazujícím dokladu se neshodují`.
`zauctovat`	Faktury budou zcela uhrazeny (nebo částečně, pokud došlo k omezení úhrady atributem `castka`) a uhrazující doklad bude spárován. Pro zbytek vznikne interní doklad.
`ignorovat`	Faktury budou zcela uhrazeny (nebo částečně, pokud došlo k omezení úhrady atributem `castka`), ale uhrazující doklad nebude spárován. Zbytek se ignoruje.
`castecnaUhrada`	Je-li částka na uhrazujícím dokladu menší než na uhrazovaném, jedná se o částečnou úhradu. Částka uhrazujícího dokladu se postupně „spotřebovává" na uhrazení faktur nebo částek, které se z nich mají uhradit, v pořadí jejich uvedení v elementu `<sparovani>`. Faktura, na kterou z úhrady už nezbývá dostatečná částka, se uhradí částečně do výše zbývajících prostředků; faktury, na které nezbývají žádné prostředky, jsou z párování vyřazeny a zůstanou neuhrazeny. Je-li částka na uhrazujícím dokladu větší, jde o chybu `400 – Částečná úhrada nemá smysl, částka na uhrazujícím dokladu je větší než na uhrazovaném`.
`castecnaUhradaNeboZauctovat`	Je-li částka na uhrazujícím dokladu větší než na uhrazovaném, zbytek se zaúčtuje (vznikne interní doklad) a uhrazující doklad bude spárován. Je-li menší, jedná se o částečnou úhradu.
`castecnaUhradaNeboIgnorovat`	Je-li částka na uhrazujícím dokladu větší než na uhrazovaném, zbytek se ignoruje a uhrazující doklad nebude spárován. Je-li menší, jedná se o částečnou úhradu.

⚠️ Jiná než uvedená hodnota vrátí 400 elementInvalidValue: „Hodnota elementu 'zbytek' je neplatná."

Doplňkové parametry spárování

V tagu <sparovani> lze navíc uvést ještě následující elementy. Nejsou povinné a standardně se berou z nastavení firmy.

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

Spárování úhrady v domácí měně s fakturou v cizí měně

Vedle párování dokladů ve stejných měnách lze také spárovat pokladnu nebo banku v domácí měně s fakturami v cizí měně. Cizí měna musí být pro všechny párované faktury stejná. V tomto případě se uhrazující doklad automaticky převede do cizí měny v kurzu rovnajícím se poměru uhrazující částky na bance v domácí měně ku celkové uhrazované částce na fakturách v cizí měně.

Spárování úhrady v cizí měně s fakturou v jiné cizí měně

Spárovat lze i pokladnu nebo banku v cizí měně s fakturou v jiné cizí měně. V tomto případě program považuje úhradu za kompletní úhradu 1 : 1 a nedochází ke změně měny na uhrazujícím dokladu. Kurzový rozdíl se vypočítává z rozdílu částek v tuzemské měně.

Odpárování

Analogicky lze provádět i odpárování:

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

Totéž v JSON:

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

Pokud žádný uhrazovaný doklad není uveden, odpárují se všechny, které jsou s daným uhrazujícím dokladem spárovány. Párování je idempotentní, tj. lze opakovat jeho volání.

Automatické párování

Přes API lze vyvolat i automatické párování plateb. Službu zavoláte metodou PUT nad evidencí banky nebo pokladny:

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

Filtrováním lze omezit úhrady vstupující do párování:

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

Příklad níže bude párovat jen úhrady zadané od 1. 3. 2020:

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

Pomocí parametrů lze nastavit mód párování, omezit, v jakých účetních obdobích se budou hledat doklady k úhradě, a určit, jak nakládat s rozdílem mezi úhradou a uhrazovaným dokladem:

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

Parametr	Hodnoty a význam
`mod`	Mód automatického párování: `varCasUcet` — dle variabilního symbolu, částky a účtu; `varCas` — dle variabilního symbolu a částky (výchozí hodnota); `jenVar` — dle variabilního symbolu; `jenCastka` — připojit, tj. párovat, když souhlasí částka a nesouhlasí VS.
`obdobi`	V kterých obdobích se budou hledat doklady k úhradě: `aktualni` — aktuální účetní období; `aktualni-predchozi` — aktuální a předchozí účetní období; `vsechna` — všechna účetní období (výchozí hodnota).
`ignorovat-rozdil-castka`	Jak velký rozdíl mezi úhradou a uhrazovaným dokladem ignorovat. Výchozí hodnota `0.0` — částky musí odpovídat; v módu `jenVar` se nastavení rozdílu ignoruje. Jedná se o rozdíl v částce v měně bankovního dokladu, tedy u bankovního dokladu v EUR a `ignorovat-rozdil-castka=1` bude ignorován rozdíl 1 EUR.
`zauctovat-rozdil`	Zda se zaúčtují doklady, pokud dojde ke spojení úhrad, kdy nejsou částky dokladů shodné. Výchozí hodnota `true` — vznikne interní doklad na rozdíl mezi doklady a doklady budou plně spárovány.

⚠️ Neplatná hodnota parametru mod nebo obdobi skončí chybou 400. Filtr patří do cesty URL (/banka/(datVyst>='2020-03-01')/…) — jako query parametr ?filter= se ignoruje.

Dále je možné automatické párování ovlivnit pokročilou parametrizací. V případě pokročilé varianty automatického párování lze období nastavit parametrem paramParovaniUhradOmezeniObdobiDrgn s hodnotami aktualni, aktualni-predchozi (výchozí pro aplikaci) a vsechna (výchozí pro API). Přes API se parametr zapisuje do evidence parametr:

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

Původní způsob párování pouze přes REST API

Je podporován i zastaralý způsob, kterým šlo párovat pouze přes REST API (nikoliv XML importem), na 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>

Odpárování stejným způsobem:

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

📝 Pro nové integrace použijte párování přes XML import nad evidencí banka nebo pokladni-pohyb (příklady výše). Zastaralé URL /parovani-uhrad zůstává funkční pouze z důvodu zpětné kompatibility.

Související

Související články

Párování plateb