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 or revalued via the REST API. This guide covers how to create contracts using the REST API. Both customer and supplier contracts can be created via the REST API.
Request method
Contracts can be created using the HTTP method: PUT or POST.
The following output formats are supported: XML or JSON.
The records are available at the following endpoints:
/c/{firma}/smlouva/properties - for customer contracts
/c/{firma}/dodavatelska-smlouva/properties for supplier contracts, where {firma} is the database company identifier.
Example endpoints for the demo company:
There are additional supplementary records used for tracking or importing related information:
used to define the contract type; this is a contract template, similar to a document type, which is used when creating an actual contract.
used to maintain custom contract statuses, for example when contracts need to be distinguished at a glance by a specific flag.
every contract must have at least one line item defined in order for an invoice to be generated — specifying what should be included in the invoice and other details related to invoicing frequency and date. Note: this record is shared between line items of both supplier and customer contracts. Line items cannot be imported independently without providing the contract header.
used to track the history of invoice generation from contracts. Contains information about the user, generation date, method (manual/automatic), number of generated invoices, and any errors.
Request body
The request body must include the contract header with required fields and optionally the contract line items. Line items can also be imported later by updating the contract. The required fields for the contract header are:
kod- contract number, max. 20 charactersnazev- contract name, max. 255 characterssmlouvaOd- contract start date, in the format specified in the documentation (generally the date the contract is signed); the validity date set on the contract line item takes precedence.typSml- reference to the defined contract typefirma- reference to the company directory; the company to which the contract is linked.
For completeness, the required fields for contract line items are:
kod- contract line item code, max. 20 charactersnazev- contract line item name, max. 255 characters
Note: Additional fields are not mandatory; however, for invoices to be generated correctly, the fields must be configured according to the specific invoicing requirements. For more information on configuration and generation examples, see the documentation on Customer and supplier contracts in practice.
Response
Upon successful contract creation, you can verify the HTTP response status or check that the success property in the returned document has the value true.
On success, HTTP status 201 Created is returned along with a document in the standard response format; see return values.
On failure, a 4xx/5xx status is returned along with a message describing the reason for the failure.
Example calls
1. XML call
POST https://demo.flexibee.eu/c/demo/smlouva.xml
Tělo:
<winstrom>
<smlouva>
<kod>INTERNETROK23</kod>
<nazev>Internet na rok výhodně</nazev>
<smlouvaOd>2023-03-01</smlouvaOd>
<typSml>code:SMLOUVA</typSml>
<firma>code:ABRA</firma>
</smlouva>
</winstrom>
This call creates a customer contract "Internet na rok výhodně" with the pre-defined contract type SMLOUVA for company ABRA, valid from 1 March 2023.
2. JSON call:
PUT https://demo.flexibee.eu/c/demo/dodavatelska-smlouva.json
Tělo:
{
"winstrom": {
"dodavatelska-smlouva": {
"kod": "INTERNETROK23",
"nazev": "Internet na rok výhodně",
"smlouvaOd": "2023-03-01",
"typSml": "code:SMLOUVA",
"firma": "code:ABRA",
"frekFakt": 12,
"den": 31,
"mesic": 1,
"zpusFaktK": "zpusobFakt.dopredu",
"typDoklFak": "code:FAKTURA",
"polozkySmlouvy": {
"smlouva-polozka": [
{
"kod": "INTERNET2023",
"nazev": "Internet výhodně 2023"
},
{
"cenik": "code:KONZULTACE"
}
]
}
}
}
}
This call creates a supplier contract with two line items — "Internet na rok výhodně" — with the pre-defined contract type SMLOUVA for company ABRA, valid from 1 March 2023. Invoices will be generated with document type FAKTURA; the invoicing frequency is set to 12 months, the turnover day and month is 31/1, billed in advance. The KONZULTACE line item is handled via a price list item referenced by its code, from which the required fields (code and name) are automatically inherited. The INTERNET2023 line item is created without a price list reference.
Failed requests
1. If the contract type is missing, a 400 Bad Request error is returned
<message>Pole 'Typ smlouvy' musí být vyplněno. </message>
2. WARNING: Flexi does not validate values in optional fields such as invoicing frequency, turnover day and month, etc. The request will succeed, but the result may contain nonsensical values that will prevent invoice generation:
"frekFakt": 121,
"den": 311,
"mesic": 13
3. If an enumeration value is entered incorrectly — for example, the invoicing method — a 400 Bad Request error is returned:
"message": "zpusobFakt.doprdu není platný kód lokalizovaného číselníku zpusobFakt. [INTERE23]",
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 only way to look up the relevant contract from an invoice is by 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.