Client Contracts API

General notes

Enumerators

BillingsFrequencyEnum:

This enumerator value is used in field billings_frequency.

Name	Type	Value
MONTHLY	int	1
QUARTERLY	int	2
YEARLY	int	3

BillingsAtEnum:

This enumerator value is used in field billings_at.

Name	Type	Value
START_OF_PERIOD	int	1
END_OF_PERIOD	int	2

Embeddable fields

Name	Type	Description
client	Client	Model of Client.
project	Project	Model of Project.
responsible_person	User	Model of User.
client_contract_invoices	ClientContractInvoice[]	Array of invoices.
next_invoice	string	Date of next invoice.
download_file	string	Url for file download.

Content

Client Contracts collection:

• [GET] index
• [POST] create

Single role:

• [GET] client detail
• [PUT/PATCH] update client
• [DELETE] remove

Clients collection

Client Contracts index

This method needs permission access on client-contracts.

Request

Index behaviour	Definition
Paginated by default	Yes
Sorting	id, name, description, client_id, file_id, project_id, responsible_person_id, amount_of_money, billings_frequency, billings_at, valid_from, valid_to, created_at, updated_at
Filters	id:int, name:string, description:string, client_id:int, file_id:int, project_id:int, responsible_person_id:int, amount_of_money:Monetary (Decimal), billings_frequency:enum, billings_at:enum, valid_from:date, valid_to:date, created_at:datetime, updated_at:datetime
Embedded	-

GET /api/v0/client-contracts HTTP/1.1
Content-Type: application/json

Response

200 OK

{
    "items": [
        {
            "id": 5,
            "name": "Kaitrade smlouva",
            "description": null,
            "client_id": 2,
            "file_id": 1,
            "project_id": null,
            "responsible_person_id": 39,
            "amount_of_money": {
                "CZK": {
                    "value": 120.22,
                    "formatted": "120,22 Kč"
                }
            },
            "billings_frequency": "1",
            "billings_at": "1",
            "valid_from": "2023-12-31T23:00:00.000000Z",
            "valid_to": null,
            "created_at": "2024-01-29T14:58:24+0100",
            "updated_at": "2024-01-30T06:41:28+0100",
            "_links": [
                {
                    "href": "/api/v0/client-contracts/5",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ]
}

---

Create Client Contracts

This method needs permission create on client-contracts.

Request

Param	Type	Description	Requirements
name	string	Contract name	Required. Must be a string with a maximal length of 100 characters.
description	string	Contract description	Optional. Must be a string.
client_id	int	Reference to model Client.	Required.
file_id	int	Reference to model File.	Optional. Must be file of types: PDF, DOC, DOCX.
project_id	int	Reference to model Project.	Optional.
responsible_person_id	int	Reference to model User.	Optional. If null, value is set equal to responsible person for Client.
amount_of_money	array	Amount of money per invoice.	Required. [CurrencyId => (float) Value]
billings_frequency	enum	Frequency of new invoices.	Required.
billings_at	enum	Determines if new invoices are created at the start or end of given period.	Required.
valid_from	date	Valid from	Required.
valid_to	date	Valid to	Required.

POST /api/v0/client-contracts HTTP/1.1
Content-Type: application/json
{
    "name": "Kaitrade Smlouva",
    "client_id": 2,
    "file_id": 1,
    "amount_of_money": 
    {
        "CZK": 120.21547
    },
    "billings_frequency": 1, 
    "billings_at": 2,
    "valid_from": "2024-01-01",
    "valid_to": null
}

Response

201 CREATED

{
    "items": [
        {
            "id": 5,
            "name": "Kaitrade smlouva",
            "description": null,
            "client_id": 2,
            "file_id": 1,
            "project_id": null,
            "responsible_person_id": 39,
            "amount_of_money": {
                "CZK": {
                    "value": 120.22,
                    "formatted": "120,22 Kč"
                }
            },
            "billings_frequency": "1",
            "billings_at": "1",
            "valid_from": "2023-12-31T23:00:00.000000Z",
            "valid_to": null,
            "created_at": "2024-01-29T14:58:24+0100",
            "updated_at": "2024-01-30T06:41:28+0100",
            "_links": [
                {
                    "href": "/api/v0/client-contracts/6",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ]
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

403 FORBIDDEN

Unauthorized.

---

---

Single Client Contract

Client Contract detail

GET /api/v0/client-contracts/{contract_id}

This method needs permission read on client-contracts.

Request

GET /api/v0/client-contracts/1 HTTP/1.1
Content-Type: application/json

Response

200 OK

{
    "id": 5,
    "name": "Kaitrade Smlouva",
    "description": null,
    "client_id": 2,
    "file_id": 1,
    "project_id": null,
    "responsible_person_id": 39,
    "amount_of_money": {
        "CZK": {
            "value": 120.22,
            "formatted": "120,22 Kč"
        }
    },
    "billings_frequency": "1",
    "billings_at": "1",
    "valid_from": "2023-12-31T23:00:00.000000Z",
    "valid_to": null,
    "created_at": "2024-01-29T14:58:24+0100",
    "updated_at": "2024-01-30T06:41:28+0100",
    "_links": [
        {
            "href": "/api/v0/client-contracts/5",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

ClientContract was not found.

GET /api/v0/clients/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

---

Update Client Contract

PUT/PATCH /api/v0/client-contracts/{contract_id}

This method needs permission update on client-contracts.

Request

Param	Type	Description	Requirements
name	string	Contract name	Must be a string with a maximal length of 100 characters.
description	string	Contract description	Must be a string.
client_id	int	Reference to model Client.
file_id	int	Reference to model File.	Must be file of types: PDF, DOC, DOCX.
project_id	int	Reference to model Project.
responsible_person_id	int	Reference to model User.	If null, value is set equal to responsible person for Client.
amount_of_money	array	Amount of money per invoice.
billings_frequency	enum	Frequency of new invoices.
billings_at	enum	Determines if new invoices are created at the start or end of given period.
valid_from	date	Valid from
valid_to	date	Valid to

For PATCH method any field can be omitted.

PATCH /api/v0/client-contracts/5 HTTP/1.1
Content-Type: application/json
{
    "name": "Demo smlouva",
}

Response

200 OK

Successfully updated.

{
    "id": 5,
    "name": "Demo smlouva",
    "description": null,
    "client_id": 2,
    "file_id": 1,
    "project_id": null,
    "responsible_person_id": 39,
    "amount_of_money": {
        "CZK": {
            "value": 120.22,
            "formatted": "120,22 Kč"
        }
    },
    "billings_frequency": "1",
    "billings_at": "2",
    "valid_from": "2023-12-31T23:00:00.000000Z",
    "valid_to": null,
    "created_at": "2024-01-29T14:58:24+0100",
    "updated_at": "2024-01-30T10:43:29+0100",
    "_links": [
        {
            "href": "/api/v0/client-contracts/5",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

Not found.

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

{
    "type" : "ValidationError",
    "message" : "The given data was invalid.",
    "id" : "fe1b04de-b347-43b5-8118-864c1eefaccf",
    "errors": [
        {
            "field": "name",
            "message": "Value must be of type string."
        }
    ]
}

---

Delete Client Contract

DELETE /api/v0/client-contracts/{contract_id}

This method needs permission delete on client-contracts.

Request

DELETE /api/v0/client-contracts/5 HTTP/1.1
Content-Type: application/json

Response

204 NO CONTENT

Successfully deleted.

404 NOT FOUND

Not found.