Valorizace slouží ke zhodnocení odběratelských i dodavatelských smluv na nové období — u položek smlouvy se navýší cena o zadané procento. Přes REST API ji lze vyvolat pro všechny smlouvy, nebo jen pro vybrané. Jak ze smluv generovat faktury a jak smlouvy tvořit, popisují samostatné články.

Způsob volání

Službu vyvoláte HTTP metodou PUT nebo POST; podporované výstupní formáty jsou XML a JSON.

Adresa	Pro které smlouvy
`/c/{firma}/smlouva/valorizuj-smlouvy`	Odběratelské smlouvy.
`/c/{firma}/dodavatelska-smlouva/valorizuj-smlouvy`	Dodavatelské smlouvy.

Segment {firma} je databázový identifikátor firmy:

PUT https://demo.flexibee.eu/c/demo/smlouva/valorizuj-smlouvy.json

Tělo požadavku

Element	Význam
`rok` — povinný	Účetní období, na které valorizace platí, například `2023`. Musí jít o období, které firma má založené.
`procentoValorizace` — povinný	Procento, o které se položky smluv navýší, například `5` nebo `10`.
`filtr`	Nepovinná filtrace smluv, které se mají valorizovat — zapisuje se jako WQL výraz, například `kod = '1234'`. Není-li uvedena, valorizují se všechny smlouvy, jejichž položky jsou platné v uvedeném roce.

🚨 Element se jmenuje filtr, ne filter. Zapíšete-li filter, služba jej mlčky ignoruje, vrátí 201 Created a valorizuje všechny smlouvy.

⚠️ Valorizace proběhne pouze u položek smluv, které mají nastavené vlastnosti valorizovat a valorizovatMesic. Vlastnost platiOdData položky navíc nesmí být ve stejném měsíci jako valorizovatMesic. Význam těchto vlastností popisuje článek Odběratelské smlouvy, jejich přehled pak popis evidence.

Výsledek

Při úspěšné valorizaci vznikne ve smlouvě nová položka a původní položka má ukončenou platnost. Úspěch poznáte z HTTP statusu 201 Created nebo z vlastnosti success s hodnotou true; odpověď má standardní formát, viz návratové hodnoty. V elementu updated uvidíte, kolik smluv bylo valorizováno:

<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
  <success>true</success>
  <stats>
    <created>0</created>
    <updated>1</updated>
    <deleted>0</deleted>
    <skipped>0</skipped>
    <failed>0</failed>
  </stats>
</winstrom>

Filtr, který žádnou smlouvu nenajde, vrací také 201, ale s updated rovným nule. Při neúspěchu je vracen status 4xx nebo 5xx a zpráva o důvodu.

Ukázky volání

Všechny smlouvy v XML

POST https://demo.flexibee.eu/c/demo/smlouva/valorizuj-smlouvy.xml

<winstrom version="1.0">
    <rok>2023</rok>
    <procentoValorizace>10</procentoValorizace>
</winstrom>

Tímto voláním se na období 2023 valorizují o 10 % všechny položky všech smluv, které mají nastaveno valorizovat.

Jedna smlouva v JSON

PUT https://demo.flexibee.eu/c/demo/dodavatelska-smlouva/valorizuj-smlouvy.json

{
   "winstrom": {
         "rok": "2023",
         "procentoValorizace": "10",
         "filtr": "kod = 'SMLOUVA123'"
   }
}

Zde se valorizují jen položky smlouvy s označením SMLOUVA123, které jsou pro valorizaci nastavené.

Neúspěšné požadavky

Situace	Odpověď
Chybí `rok` nebo je uveden rok, který firma nemá jako účetní období	`400`, `validace.notAvailableValue` — Pole 'rok' musí být vyplněno jednou z hodnot … s výčtem dostupných období
Chybí `procentoValorizace`	`400`, `elementRequired` — Element 'procentoValorizace' musí být uveden.
Filtr není platný WQL výraz — například `code:SMLOUVA123`	`400` — Špatný formát WQL dotazu, problém na pozici …
Místo `filtr` je uveden `filter`	`201 Created` — filtr je ignorován a valorizují se všechny smlouvy

FAQ

Jak poznám, které položky se valorizovaly?

Původní položka má ukončenou platnost a vedle ní vznikne nová s navýšenou cenou. Přehled položek smlouvy získáte relací polozkySmlouvy, například dotazem /c/demo/smlouva/1.json?relations=polozkySmlouvy&detail=full.

Kde najdu příklady zadání smluv?

Videotutoriál a příklady zadání najdete v článku Odběratelské a dodavatelské smlouvy, širší souvislosti pak v sérii Odběratelské smlouvy v praxi.

Související

Související články

Valorizace smluv přes REST API