Valorization is used to appreciate customer and supplier contracts for a new period — the price of the contract items is increased by the specified percentage. Via the REST API, it can be triggered for all contracts, or only for selected ones. How to generate invoices from contracts and how to create contracts are described in separate articles.

Calling method

You call the service using the HTTP method PUT or POST; the supported output formats are XML and JSON.

Address	For which contracts
`/c/{firma}/smlouva/valorizuj-smlouvy`	Customer contracts.
`/c/{firma}/dodavatelska-smlouva/valorizuj-smlouvy`	Supplier contracts.

The {firma} segment is the database company identifier:

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

Request body

Element	Meaning
`rok` — required	The accounting period the valorization applies to, for example `2023`. It must be a period the company has set up.
`procentoValorizace` — required	The percentage by which the contract items will be increased, for example `5` or `10`.
`filtr`	Optional filter for the contracts to be valorized — written as a WQL expression, for example `kod = '1234'`. If not specified, all contracts whose items are valid in the given year are valorized.

🚨 The element is named filtr, not filter. If you enter filter, the service silently ignores it, returns 201 Created, and valorizes all contracts.

⚠️ Valorization only takes place for contract items that have the properties valorizovat and valorizovatMesic set. In addition, the item's platiOdData property must not be in the same month as valorizovatMesic. The meaning of these properties is described in the article Customer Contracts, and an overview of them in the record description.

Result

On successful valorization, a new item is created in the contract, and the original item's validity is terminated. You can recognize success from the HTTP status 201 Created or from the success property with the value true; the response has the standard format, see return values. The updated element shows how many contracts were valorized:

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

A filter that finds no contract also returns 201, but with updated equal to zero. On failure, the status 4xx or 5xx is returned, along with a message explaining the reason.

Call examples

All contracts in XML

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

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

This call valorizes by 10% for the year 2023 all items of all contracts that have valorizovat set.

One contract in JSON

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

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

Here, only the items of the contract labeled SMLOUVA123 that are set up for valorization are valorized.

Unsuccessful requests

Situation	Response
`rok` is missing, or the given year is not one the company has as an accounting period	`400`, `validace.notAvailableValue` — The 'rok' field must be filled in with one of the values … along with a list of available periods
`procentoValorizace` is missing	`400`, `elementRequired` — The 'procentoValorizace' element must be specified.
The filter is not a valid WQL expression — for example `code:SMLOUVA123`	`400` — Incorrect WQL query format, problem at position …
`filter` is specified instead of `filtr`	`201 Created` — the filter is ignored and all contracts are valorized

FAQ

How do I know which items were valorized?

The original item's validity is terminated, and a new one with the increased price is created alongside it. You can get an overview of contract items via the polozkySmlouvy relation, for example with the query /c/demo/smlouva/1.json?relations=polozkySmlouvy&detail=full.

Where can I find examples of how to enter contracts?

You'll find a video tutorial and entry examples in the article Customer and Supplier Contracts, and broader context in the Customer Contracts in Practice series.

Contract Indexation via REST API