Valorizácia slúži na zhodnotenie odberateľských aj dodávateľských zmlúv na nové obdobie — pri položkách zmluvy sa navýši cena o zadané percento. Cez REST API ju možno vyvolať pre všetky zmluvy, alebo len pre vybrané. Ako zo zmlúv generovať faktúry a ako zmluvy vytvárať, popisujú samostatné články.

Spôsob volania

Službu vyvoláte HTTP metódou PUT alebo POST; podporované výstupné formáty sú XML a JSON.

Adresa	Pre ktoré zmluvy
`/c/{firma}/smlouva/valorizuj-smlouvy`	Odberateľské zmluvy.
`/c/{firma}/dodavatelska-smlouva/valorizuj-smlouvy`	Dodávateľské zmluvy.

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

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

Telo požiadavky

Element	Význam
`rok` — povinný	Účtovné obdobie, na ktoré valorizácia platí, napríklad `2023`. Musí ísť o obdobie, ktoré má firma založené.
`procentoValorizace` — povinný	Percento, o ktoré sa položky zmlúv navýšia, napríklad `5` alebo `10`.
`filtr`	Nepovinné filtrovanie zmlúv, ktoré sa majú valorizovať — zapisuje sa ako WQL výraz, napríklad `kod = '1234'`. Ak nie je uvedené, valorizujú sa všetky zmluvy, ktorých položky sú platné v uvedenom roku.

🚨 Element sa volá filtr, nie filter. Ak zapíšete filter, služba ho mlčky ignoruje, vráti 201 Created a valorizuje všetky zmluvy.

⚠️ Valorizácia prebehne iba pri položkách zmlúv, ktoré majú nastavené vlastnosti valorizovat a valorizovatMesic. Vlastnosť platiOdData položky navyše nesmie byť v rovnakom mesiaci ako valorizovatMesic. Význam týchto vlastností popisuje článok Odberateľské zmluvy, ich prehľad potom popis evidencie.

Výsledok

Pri úspešnej valorizácii vznikne v zmluve nová položka a pôvodná položka má ukončenú platnosť. Úspech spoznáte z HTTP statusu 201 Created alebo z vlastnosti success s hodnotou true; odpoveď má štandardný formát, pozri návratové hodnoty. V elemente updated uvidíte, koľko zmlúv bolo valorizovaných:

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

Filter, ktorý nenájde žiadnu zmluvu, vracia tiež 201, ale s updated rovným nule. Pri neúspechu je vrátený status 4xx alebo 5xx a správa o dôvode.

Ukážky volania

Všetky zmluvy 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 volaním sa na obdobie 2023 valorizujú o 10 % všetky položky všetkých zmlúv, ktoré majú nastavené valorizovat.

Jedna zmluva v JSON

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

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

Tu sa valorizujú len položky zmluvy s označením SMLOUVA123, ktoré sú pre valorizáciu nastavené.

Neúspešné požiadavky

Situácia	Odpoveď
Chýba `rok` alebo je uvedený rok, ktorý firma nemá ako účtovné obdobie	`400`, `validace.notAvailableValue` — Pole 'rok' musí byť vyplnené jednou z hodnôt … s výpočtom dostupných období
Chýba `procentoValorizace`	`400`, `elementRequired` — Element 'procentoValorizace' musí byť uvedený.
Filter nie je platný WQL výraz — napríklad `code:SMLOUVA123`	`400` — Zlý formát WQL dotazu, problém na pozícii …
Namiesto `filtr` je uvedený `filter`	`201 Created` — filter je ignorovaný a valorizujú sa všetky zmluvy

FAQ

Ako spoznám, ktoré položky sa valorizovali?

Pôvodná položka má ukončenú platnosť a vedľa nej vznikne nová s navýšenou cenou. Prehľad položiek zmluvy získate reláciou polozkySmlouvy, napríklad dotazom /c/demo/smlouva/1.json?relations=polozkySmlouvy&detail=full.

Kde nájdem príklady zadania zmlúv?

Videotutoriál a príklady zadania nájdete v článku Odberateľské a dodávateľské zmluvy, širšie súvislosti potom v sérii Odberateľské zmluvy v praxi.

Súvisiace

Sorodni članki

Valorizácia zmlúv cez REST API