Customer and supplier contracts are used for automatic invoicing at regular, or even irregular, intervals based on the usage or provision of services.

Contracts can be used via the REST API to generate invoices, and contracts can also be indexed (valorized). In this guide, we'll look at how to create contracts — both customer and supplier — via the REST API.

Method of calling

You create a contract using the HTTP method PUT or POST; the supported output formats are XML and JSON.

POST https://demo.flexibee.eu/c/demo/smlouva.xml
POST https://demo.flexibee.eu/c/demo/dodavatelska-smlouva.json

The smlouva evidence contains customer contracts, while the dodavatelska-smlouva evidence contains supplier contracts. The {firma} segment in the address is the database company identifier.

Related evidences

There are additional evidences around contracts that are used for tracking or importing supplementary information:

Evidence	Purpose
typ-smlouvy, dodavatelsky-typ-smlouvy	Definition of the contract type — the template on which the actual contract is based, similar to a document type.
stav-smlouvy	Evidence of custom contract statuses — for example, when you need to distinguish contracts at a glance by some flag.
smlouva-polozka	Contract items. For an invoice to be generated from a contract, the contract must have at least one item specifying what is to be invoiced, along with the frequency and generation date details.
smlouva-zurnal	History of invoice generation from contracts — user, generation date, method (manual or automatic), number of invoices generated, and any errors.

⚠️ The smlouva-polozka evidence is shared between customer and supplier contract items and cannot be imported separately — without a contract header, the request returns 400 with code importNotAllowed and the message Import is not allowed. Therefore, send items nested within the contract, either when creating it or in a later update.

Request body

In the request body, include the contract header with the required properties, and optionally its items:

Property	Meaning
`kod`	Contract number, max. 20 characters.
`nazev`	Contract name, max. 255 characters.
`smlouvaOd`	Start of the contract's validity, in date format — generally corresponds to the moment the contract is signed. The validity date given on the contract item takes precedence.
`typSml`	Reference to the defined contract type.
`firma`	Reference to the address book — the company the contract is linked to.

For contract items, kod (code, max. 20 characters) and nazev (max. 255 characters) are required. If you link the item to a price list item using the cenik element, the code and name will be taken from the price list, and you don't need to specify them yourself.

⚠️ Other properties are not required, but they must be set correctly according to how you need invoicing to work, in order for invoices to be generated properly. You can find more about the settings and examples in the article Customer Contracts in Practice.

Result

You can tell whether the request succeeded from the HTTP status or from the success property in the response. On successful creation, the status 201 Created is returned along with a document in the standard format — see return values. On failure, the status 4xx or 5xx is returned, along with a message explaining the reason.

Sample calls

Customer contract in XML

POST https://demo.flexibee.eu/c/demo/smlouva.xml

<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 the customer contract "Internet na rok výhodně" with the predefined type SMLOUVA for company ABRA, valid from 3/1/2023.

Supplier contract with items in JSON

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

{
    "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"
                    }
                ]
            }
        }
    }
}

Here, a supplier contract with two items is created. Invoices will be generated with the document type FAKTURA, the invoicing frequency is 12 months, the cycle day and month is 31/1, and invoicing is done in advance. The KONZULTACE item references a price list item, from which the required code and name are taken automatically; the INTERNET2023 item is created without a link to the price list.

The zpusFaktK property accepts the values zpusobFakt.dopredu (Invoice in advance) and zpusobFakt.zpetne (Invoice in arrears).

Failed requests

Situation	Response
Missing contract type	`400`, `validace.notNull` — The 'Contract type' field must be filled in.
Item without a price list link and without a name	`400`, `validace.notNull` — The 'Name' field must be filled in.
Incorrectly entered code list value, for example the invoicing method	`400`, `importXmlNeplatnyCiselnik` — zpusobFakt.doprdu is not a valid code of the localized code list zpusobFakt.
Importing a standalone item without a contract header	`400`, `importNotAllowed` — Import is not allowed.

🚨 Flexi does not validate optional properties such as invoicing frequency or the cycle day and month in any way. A request with the values "frekFakt": 121, "den": 311, or "mesic": 13 will go through without an error, but the result will be nonsensical values that then prevent invoices from being generated.

FAQ

How do I find an invoice generated from a contract?

A generated invoice carries the contract number in the text property cisSml as well as the reference smlouva, so you can filter the invoices for a given contract directly:

GET https://demo.flexibee.eu/c/demo/faktura-vydana/(smlouva='code:45644').json

Where can I find examples of how to set up contracts?

You can find a video tutorial and setup examples in the article Customer and Supplier Contracts, and broader context in the series Customer Contracts in Practice.

How can I tell whether and when invoices were generated from a contract?

You can find the history in the smlouva-zurnal evidence — it includes the user, date, generation method, number of invoices, and any errors.

API Agreements