Customer and supplier contracts are used for automatic invoicing at regular or irregular intervals based on the use or provision of services.
Contracts can be generated via the REST API. In this guide, we will look at how to valorize contracts. The REST API can be used to valorize both customer and supplier contracts. Valorization is used to revalue a contract for a new period. Typically, the period and valorization percentage are set on the contract.
Calling method
You can use the HTTP method: PUT or POST.
The service is available at the following addresses:
/c/{firma}/smlouva/valorizuj-smlouvy - for customer contracts
/c/{firma}/dodavatelska-smlouva/valorizuj-smlouvy - for supplier contracts, where {firma} is the database company identifier.
Example endpoint on the demo company:
The following output formats are supported: XML or JSON.
Request body
The request body must include the required properties rok and procentoValorizace. Additionally, the optional filtr can be specified to valorize only selected contracts:
rok- the accounting period for which the valorization applies (in the format e.g. 2022, 2023, etc.)procentoValorizace- the percentage by which contract line items will be increased (in the format 5, 10, etc.)filtr- filter for selecting which contracts should be valorizedIf no filter is specified, all contracts whose line items are valid in the specified year will be valorized.
Important: It should also be noted that valorization will only apply to contract line items that have the properties valorizovat and valorizovatMesic set. Additionally, the property platiOdData on the contract line item must not be in the same month as the property valorizovatMesic, see contract line item properties. These properties specify whether a line item should be valorized and in which month — for more details, see the contract documentation.
Result
If the valorization of contract line items is successful, a new line item is created in the contract and the original line item's validity is ended. Whether the service was executed successfully can be checked via the HTTP response status, or by verifying that the property success in the returned document has a value of true.
If the service executes successfully, HTTP status 201 Created is returned along with a document in the standard format, see return values.
In case of failure, a 4xx/5xx status is returned along with a message describing the reason for the failure.
Call examples
1. Call in XML
POST https://demo.flexibee.eu/c/demo/smlouva/valorizuj-smlouvy.xml
Tělo:
<winstrom version="1.0">
<rok>2023</rok>
<procentoValorizace>10</procentoValorizace>
</winstrom>
In this call, all line items of all contracts for the period 2023 will be valorized by 10%, provided they have valorization enabled.
2. Call in JSON:
PUT https://demo.flexibee.eu/c/demo/dodavatelska-smlouva/valorizuj-smlouvy.json
Tělo:
{
"winstrom": {
"rok": "2023",
"procentoValorizace": "10",
"filtr":"code:SMLOUVA123"
}
}
In this case, all line items of the contract with the code SMLOUVA123 that are set for valorization will be valorized.
Failed requests
1. If an incorrect or empty rok is provided, a 400 Bad Request error will occur
<message>Pole 'rok' musí být vyplněno jednou z hodnot 2018, 2019, 2020, 2021, 2022, 2023, 2024.</message>
2. If procentoValorizace is not filled in, the response is again 400 Bad Request
<message>Element 'procentoValorizace' musí být uveden.</message>
3. If the element filter is used instead of filtr, all contracts will be valorized! With a result of 201 Created.
<winstrom version="1.0">
<rok>2018</rok>
<procentoValorizace>5</procentoValorizace>
<filter>code:SMLOUVA123</filter>
</winstrom>
FAQ
Contract entry examples
Customer contracts in practice
How do I find an invoice generated from a contract?
No link between the invoice and the contract is created. The relevant contract can only be looked up from the invoice using the cisSml field.
Need help?
If you have any questions about the application, please contact us at podporaflexi@abra.eu or via the chat window in the bottom right corner.