Послуги

Відкритий API

/services/api/v1/

Клієнти, записи, вільні слоти, статуси та історія клієнта. Те саме, що робить кабінет, але для сайту, телеграм-бота чи рецепції.

Доступ

Токен у заголовку. Створюється в налаштуваннях модуля «Послуги» → «API для інтеграцій». На платному тарифі токен робочий, на безкоштовному sandbox (усі методи працюють, дані живуть 24 години).

Authorization: Bearer <token>
X-API-Key: <token>

Обидва заголовки рівнозначні, достатньо одного.

Ліміти й режими

Час і дати: date, time, starts_at і ends_at: місцевий час бізнесу без зсуву: саме так календар і зберігає години, і саме їх бачить клієнт. created_at, updated_at і expires_at: повний ISO 8601 зі зсувом.
Ліміт запитів: 60 на годину на кожен токен платного тарифу, 30 для sandbox. Ліміт налаштовується окремо для кожного токена: якщо інтеграції треба більше, напишіть у підтримку.
Заголовки залишку: X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset приходять у кожній відповіді, а при 429 ще й Retry-After у секундах до скидання вікна.
Sandbox: Токен безкоштовного тарифу працює в окремому просторі: він бачить лише створене ним і не може змінити справжні дані кабінету. Створені обʼєкти видаляються через 24 години (поле expires_at у кожній відповіді), не займають час у публічному календарі й не створюють доходів і списань.
Кілька токенів: До 5 токенів на платному тарифі, окремий на кожну інтеграцію, щоб відкликати один, не ламаючи решту. На безкоштовному один sandbox-токен.

Ендпоінти

GET /services/api/v1/clients/

Список клієнтів

Клієнти акаунта з пагінацією й пошуком.

Параметри й приклади

Параметри запиту

Параметр	Обовʼязковий	Опис
`q`	ні	Пошук за імʼям, прізвищем, телефоном або email.
`is_active`	ні	true або false: лише активні чи лише архівні.
`limit`	ні	Скільки повернути, 1-100. За замовчуванням 50.
`offset`	ні	Зсув для наступної сторінки. За замовчуванням 0.

Відповідь 200

{
  "count": 128,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "id": 41,
      "first_name": "Оксана",
      "last_name": "Мельник",
      "full_name": "Оксана Мельник",
      "email": "[email protected]",
      "phone": "+380671234567",
      "telegram": "@oksana",
      "notes": "Алергія на аміак",
      "is_active": true,
      "sandbox": false,
      "expires_at": null,
      "created_at": "2026-08-14T11:02:37+03:00",
      "updated_at": "2026-09-01T09:15:00+03:00"
    }
  ]
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_parameter
{"error": {"code": "invalid_parameter", "message": "Query parameter is invalid."}}

POST /services/api/v1/clients/

Створити клієнта

Обовʼязкове лише імʼя, решта полів за наявності.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`first_name`	так	Імʼя, до 100 символів.
`last_name`	ні	Прізвище, до 100 символів.
`email`	ні	Перевіряється на формат. null, щоб прибрати.
`phone`	ні	До 30 символів, у будь-якому форматі.
`telegram`	ні	До 100 символів.
`notes`	ні	Внутрішня примітка, будь-яка довжина.
`is_active`	ні	true за замовчуванням.

Зірочка означає «одне з двох»: достатньо будь-якого.

Запит

{
  "first_name": "Оксана",
  "last_name": "Мельник",
  "phone": "+380671234567",
  "email": "[email protected]",
  "notes": "Прийшла з Instagram"
}

Відповідь 201

{
  "id": 42,
  "first_name": "Оксана",
  "last_name": "Мельник",
  "full_name": "Оксана Мельник",
  "email": "[email protected]",
  "phone": "+380671234567",
  "telegram": null,
  "notes": "Прийшла з Instagram",
  "is_active": true,
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T12:41:09+03:00",
  "updated_at": "2026-09-08T12:41:09+03:00"
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "first_name": "This field is required and must not be empty.",
      "email": "Not a valid email address."
    }
  }
}

GET /services/api/v1/clients/<id>/
Один клієнт

Той самий обʼєкт, що у списку, за внутрішнім id.
Параметри й приклади

Відповідь 200
```
{
  "id": 42,
  "first_name": "Оксана",
  "last_name": "Мельник",
  "full_name": "Оксана Мельник",
  "email": "[email protected]",
  "phone": "+380671234567",
  "telegram": null,
  "notes": "Прийшла з Instagram",
  "is_active": true,
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T12:41:09+03:00",
  "updated_at": "2026-09-08T12:41:09+03:00"
}
```
Помилки й тіла відповідей
- 401 missing_token
  {"error": {"code": "missing_token", "message": "Authorization header is missing."}}
- 401 invalid_token
  {"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
- 403 module_required
  {"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
- 403 plan_required
  {"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
- 429 rate_limit_exceeded
  {"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
- 405 method_not_allowed
  {"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
- 404 not_found
  {"error": {"code": "not_found", "message": "Object does not exist."}}

PATCH /services/api/v1/clients/<id>/

Редагувати клієнта

Часткове оновлення: надсилайте лише ті поля, які змінюються. Порожнє тіло: це 400, а не «нічого не робити».

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`first_name`	ні	Імʼя, до 100 символів. Порожнім бути не може.
`last_name`	ні	Прізвище.
`email`	ні	Формат перевіряється, null прибирає значення.
`phone`	ні	Телефон, null прибирає значення.
`telegram`	ні	Telegram, null прибирає значення.
`notes`	ні	Примітка.
`is_active`	ні	Активність клієнта.

Зірочка означає «одне з двох»: достатньо будь-якого.

Запит

{
  "phone": "+380509998877",
  "notes": "Просила писати в Telegram"
}

Відповідь 200

{
  "id": 42,
  "first_name": "Оксана",
  "last_name": "Мельник",
  "full_name": "Оксана Мельник",
  "email": "[email protected]",
  "phone": "+380509998877",
  "telegram": null,
  "notes": "Просила писати в Telegram",
  "is_active": true,
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T12:41:09+03:00",
  "updated_at": "2026-09-08T13:02:44+03:00"
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
404 not_found
{"error": {"code": "not_found", "message": "Object does not exist."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "body": "Provide at least one of: first_name, last_name, email, phone, telegram, notes, is_active."
    }
  }
}

POST /services/api/v1/clients/<id>/status/

Змінити статус клієнта

Активний або архівний. Окремий ендпоінт, бо це найчастіша зміна, і плутати її з редагуванням полів не варто.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`is_active`	так	true: активний, false: в архіві.

Зірочка означає «одне з двох»: достатньо будь-якого.

Запит

{
  "is_active": false
}

Відповідь 200

{
  "id": 42,
  "first_name": "Оксана",
  "last_name": "Мельник",
  "full_name": "Оксана Мельник",
  "email": "[email protected]",
  "phone": "+380509998877",
  "telegram": null,
  "notes": "Просила писати в Telegram",
  "is_active": false,
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T12:41:09+03:00",
  "updated_at": "2026-09-08T13:20:10+03:00"
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
404 not_found
{"error": {"code": "not_found", "message": "Object does not exist."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "is_active": "This field is required and must be a boolean."
    }
  }
}

GET /services/api/v1/clients/<id>/history/
Історія клієнта

Усі записи клієнта, підсумки й оплати. Оплати беруться з модуля «Облік доходів», вони створюються з виконаних записів. Немає модуля, тоді список порожній, і це не помилка.
Параметри й приклади

Відповідь 200
```
{
  "client": { "id": 42, "full_name": "Оксана Мельник", "...": "решта полів як у GET клієнта" },
  "stats": {
    "bookings_total": 7,
    "bookings_completed": 5,
    "bookings_cancelled": 1,
    "bookings_upcoming": 1,
    "revenue_completed": "3400.00",
    "first_visit": "2026-04-12",
    "last_visit": "2026-08-30"
  },
  "bookings": [
    {
      "id": 913,
      "status": "completed",
      "date": "2026-08-30",
      "time": "14:00",
      "starts_at": "2026-08-30T14:00:00",
      "ends_at": "2026-08-30T15:30:00",
      "duration_minutes": 90,
      "notes": null,
      "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
      "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
      "sandbox": false,
      "expires_at": null,
      "created_at": "2026-08-20T10:00:00+03:00",
      "updated_at": "2026-08-30T15:31:02+03:00"
    }
  ],
  "payments": [
    {
      "id": 55,
      "booking_id": 913,
      "date": "2026-08-30",
      "amount": "700.00",
      "currency": "UAH",
      "source": "booking_completed"
    }
  ]
}
```
Помилки й тіла відповідей
- 401 missing_token
  {"error": {"code": "missing_token", "message": "Authorization header is missing."}}
- 401 invalid_token
  {"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
- 403 module_required
  {"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
- 403 plan_required
  {"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
- 429 rate_limit_exceeded
  {"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
- 405 method_not_allowed
  {"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
- 404 not_found
  {"error": {"code": "not_found", "message": "Object does not exist."}}

GET /services/api/v1/services/

Список послуг

Потрібен, щоб знати service_id і тривалість: від неї залежить сітка слотів.

Параметри й приклади

Параметри запиту

Параметр	Обовʼязковий	Опис
`is_active`	ні	true або false.
`limit`	ні	1-100, за замовчуванням 50.
`offset`	ні	Зсув, за замовчуванням 0.

Відповідь 200

{
  "count": 4,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "id": 3,
      "name": "Стрижка",
      "short_description": "Чоловіча або жіноча",
      "price": "700.00",
      "duration_minutes": 90,
      "is_active": true
    }
  ]
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_parameter
{"error": {"code": "invalid_parameter", "message": "Query parameter is invalid."}}

GET /services/api/v1/slots/

Вільні часові слоти

Сітка дорівнює тривалості послуги, зайняте виключається за реальним перетином часу, минулі години не показуються. Це та сама функція, що малює пікер у кабінеті, тож API не покаже вільним те, чого не приймає створення запису.

Параметри й приклади

Параметри запиту

Параметр	Обовʼязковий	Опис
`service_id`	так	Послуга, під тривалість якої рахується сітка.
`date`	ні	YYYY-MM-DD. За замовчуванням сьогодні.
`days`	ні	Скільки днів підряд повернути, 1-14. За замовчуванням 1.

Відповідь 200

{
  "service_id": 3,
  "duration_minutes": 90,
  "count": 3,
  "results": [
    {
      "date": "2026-09-10",
      "is_working_day": true,
      "slots": [
        { "time": "09:00", "starts_at": "2026-09-10T09:00:00", "ends_at": "2026-09-10T10:30:00" },
        { "time": "10:30", "starts_at": "2026-09-10T10:30:00", "ends_at": "2026-09-10T12:00:00" }
      ]
    },
    {
      "date": "2026-09-11",
      "is_working_day": false,
      "slots": []
    }
  ]
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_parameter
{"error": {"code": "invalid_parameter", "message": "Query parameter is invalid."}}
404 not_found
{"error": {"code": "not_found", "message": "Object does not exist."}}

GET /services/api/v1/bookings/

Список записів

Записи з фільтрами за датою, статусом, клієнтом і послугою.

Параметри й приклади

Параметри запиту

Параметр	Обовʼязковий	Опис
`date_from`	ні	YYYY-MM-DD, включно.
`date_to`	ні	YYYY-MM-DD, включно.
`status`	ні	pending, confirmed, cancelled або completed.
`client_id`	ні	Лише записи цього клієнта.
`service_id`	ні	Лише записи на цю послугу.
`limit`	ні	1-100, за замовчуванням 50.
`offset`	ні	Зсув, за замовчуванням 0.

Відповідь 200

{
  "count": 12,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "id": 913,
      "status": "confirmed",
      "date": "2026-09-10",
      "time": "09:00",
      "starts_at": "2026-09-10T09:00:00",
      "ends_at": "2026-09-10T10:30:00",
      "duration_minutes": 90,
      "notes": "Просила майстра Ірину",
      "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
      "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
      "sandbox": false,
      "expires_at": null,
      "created_at": "2026-09-08T12:50:00+03:00",
      "updated_at": "2026-09-08T12:50:00+03:00"
    }
  ]
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_parameter
{"error": {"code": "invalid_parameter", "message": "Query parameter is invalid."}}

POST /services/api/v1/bookings/

Створити запис

Час перевіряється так само, як у кабінеті: перетин із наявними записами за тривалістю послуги, робочий розклад і «час уже минув». Не пройшло: 409 із людським текстом причини в message.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`client_id`	так	Наявний клієнт цього акаунта.
`service_id`	так	Активна послуга цього акаунта.
`date`	так	YYYY-MM-DD.
`time`	так	HH:MM (приймається і HH:MM:SS).
`notes`	ні	Примітка до запису.
`status`	ні	pending (за замовчуванням), confirmed, cancelled, completed.

Зірочка означає «одне з двох»: достатньо будь-якого.

Запит

{
  "client_id": 42,
  "service_id": 3,
  "date": "2026-09-10",
  "time": "09:00",
  "notes": "Просила майстра Ірину",
  "status": "confirmed"
}

Відповідь 201

{
  "id": 914,
  "status": "confirmed",
  "date": "2026-09-10",
  "time": "09:00",
  "starts_at": "2026-09-10T09:00:00",
  "ends_at": "2026-09-10T10:30:00",
  "duration_minutes": 90,
  "notes": "Просила майстра Ірину",
  "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
  "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T13:40:00+03:00",
  "updated_at": "2026-09-08T13:40:00+03:00"
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "client_id": "Client with this id does not exist in this account.",
      "date": "Required, format YYYY-MM-DD."
    }
  }
}

409 slot_taken

{
  "error": {
    "code": "slot_taken",
    "message": "Requested time slot is not available.",
    "details": {
      "reason": "overlaps_existing_booking"
    }
  }
}

GET /services/api/v1/bookings/<id>/
Один запис

Той самий обʼєкт, що у списку, за внутрішнім id.
Параметри й приклади

Відповідь 200
```
{
  "id": 914,
  "status": "confirmed",
  "date": "2026-09-10",
  "time": "09:00",
  "starts_at": "2026-09-10T09:00:00",
  "ends_at": "2026-09-10T10:30:00",
  "duration_minutes": 90,
  "notes": "Просила майстра Ірину",
  "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
  "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T13:40:00+03:00",
  "updated_at": "2026-09-08T13:40:00+03:00"
}
```
Помилки й тіла відповідей
- 401 missing_token
  {"error": {"code": "missing_token", "message": "Authorization header is missing."}}
- 401 invalid_token
  {"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
- 403 module_required
  {"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
- 403 plan_required
  {"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
- 429 rate_limit_exceeded
  {"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
- 405 method_not_allowed
  {"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
- 404 not_found
  {"error": {"code": "not_found", "message": "Object does not exist."}}

PATCH /services/api/v1/bookings/<id>/

Редагувати запис

Перенести на інший час, змінити послугу, клієнта чи примітку. Якщо змінюються дата, час або послуга, час перевіряється заново, але вже без урахування самого цього запису (інакше він конфліктував би сам із собою).

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`client_id`	ні	Інший клієнт цього акаунта.
`service_id`	ні	Інша активна послуга.
`date`	ні	YYYY-MM-DD.
`time`	ні	HH:MM.
`notes`	ні	Примітка, null, щоб прибрати.
`status`	ні	pending, confirmed, cancelled, completed.

Зірочка означає «одне з двох»: достатньо будь-якого.

Запит

{
  "date": "2026-09-11",
  "time": "11:00"
}

Відповідь 200

{
  "id": 914,
  "status": "confirmed",
  "date": "2026-09-11",
  "time": "11:00",
  "starts_at": "2026-09-11T11:00:00",
  "ends_at": "2026-09-11T12:30:00",
  "duration_minutes": 90,
  "notes": "Просила майстра Ірину",
  "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
  "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T13:40:00+03:00",
  "updated_at": "2026-09-08T14:05:12+03:00"
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
404 not_found
{"error": {"code": "not_found", "message": "Object does not exist."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "body": "Provide at least one of: client_id, service_id, date, time, notes, status."
    }
  }
}

409 slot_taken

{
  "error": {
    "code": "slot_taken",
    "message": "Requested time slot is not available.",
    "details": {
      "reason": "time_in_the_past"
    }
  }
}

POST /services/api/v1/bookings/<id>/status/

Змінити статус запису

Переведення в completed тягне за собою те саме, що й у кабінеті: автоматичний дохід у модулі «Облік доходів» і списання матеріалів в ERP, якщо вони налаштовані. Для sandbox-токена ці наслідки не виконуються: тестовий запис не має рухати справжні гроші й склад.

Параметри й приклади

Поля тіла запиту

Поле	Обовʼязкове	Опис
`status`	так	pending, confirmed, cancelled або completed.

Зірочка означає «одне з двох»: достатньо будь-якого.

Запит

{
  "status": "completed"
}

Відповідь 200

{
  "id": 914,
  "status": "completed",
  "date": "2026-09-11",
  "time": "11:00",
  "starts_at": "2026-09-11T11:00:00",
  "ends_at": "2026-09-11T12:30:00",
  "duration_minutes": 90,
  "notes": "Просила майстра Ірину",
  "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
  "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
  "sandbox": false,
  "expires_at": null,
  "created_at": "2026-09-08T13:40:00+03:00",
  "updated_at": "2026-09-11T12:31:00+03:00"
}

Помилки й тіла відповідей

401 missing_token
{"error": {"code": "missing_token", "message": "Authorization header is missing."}}
401 invalid_token
{"error": {"code": "invalid_token", "message": "Token is invalid or revoked."}}
403 module_required
{"error": {"code": "module_required", "message": "Module is not enabled for this account."}}
403 plan_required
{"error": {"code": "plan_required", "message": "Paid plan required for this token."}}
429 rate_limit_exceeded
{"error": {"code": "rate_limit_exceeded", "message": "Hourly request limit exceeded."}}
405 method_not_allowed
{"error": {"code": "method_not_allowed", "message": "HTTP method is not allowed for this endpoint."}}
404 not_found
{"error": {"code": "not_found", "message": "Object does not exist."}}
400 invalid_json
{"error": {"code": "invalid_json", "message": "Request body is not a valid JSON object."}}

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "status": "This field is required and must be one of: pending, confirmed, cancelled, completed."
    }
  }
}

Усі помилки

Формат один на всі модулі. code стабільний, на нього і варто перевіряти; message англійською й може бути уточнений. У details є конкретні поля, якщо помилка про них. Тіло кожної помилки показане в самому ендпоінті, ось загальний вигляд:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields failed validation.",
    "details": {
      "field_name": "What exactly is wrong with this field."
    }
  }
}

code	HTTP	message	Коли
`missing_token`	401	Authorization header is missing.	Немає ні Authorization: Bearer, ні X-API-Key.
`invalid_token`	401	Token is invalid or revoked.	Токена не існує або його відкликали в налаштуваннях модуля.
`module_required`	403	Module is not enabled for this account.	До акаунта не підключено модуль «Послуги».
`plan_required`	403	Paid plan required for this token.	Токен видано на платному тарифі, а тариф уже не платний. Дані не зникають, але щоб API знову працював, треба або поновити підписку, або створити sandbox-токен.
`rate_limit_exceeded`	429	Hourly request limit exceeded.	Вичерпано ліміт запитів на годину. Коли вікно скинеться — у заголовках X-RateLimit-Reset і Retry-After.
`method_not_allowed`	405	HTTP method is not allowed for this endpoint.	Не той HTTP-метод. Дозволені перелічені в заголовку Allow.
`invalid_json`	400	Request body is not a valid JSON object.	Тіло запиту не розібралось як JSON.
`validation_error`	400	Some fields failed validation.	Поля не пройшли перевірку. Які саме й що з ними — у details.
`invalid_parameter`	400	Query parameter is invalid.	Некоректний параметр у query string (дата, id, limit).
`not_found`	404	Object does not exist.	Обʼєкта немає або він належить іншому акаунту — назовні це одне й те саме, щоб чужі id не можна було перебрати.
`slot_taken`	409	Requested time slot is not available.	Час зайнятий іншим записом, поза робочим розкладом або вже минув. Причина — у details.reason: time_in_the_past, non_working_day, outside_working_hours або overlaps_existing_booking.

Вебхуки

Вебхук це API навпаки: не ви питаєте нас, а ми надсилаємо POST на вашу адресу, коли щось стається. Опитувати /bookings/ раз на хвилину не потрібно.

Куди вставити адресу: Налаштування модуля «Послуги» → «Вебхуки». Там же є секрет для перевірки підпису, кнопка тестової доставки й журнал останніх спроб.

Події

event	Коли	data
`client.created`	Новий клієнт — з кабінету, публічної форми запису або через API.	`client`
`client.updated`	Змінились дані клієнта або його статус (активний / в архіві).	`client`
`booking.created`	Новий запис на послугу — з кабінету, публічної сторінки запису або через API.	`booking`
`booking.updated`	Перенесення на інший час, зміна послуги, клієнта або примітки.	`booking`
`booking.status_changed`	Окрема подія, бо саме на неї вішають нагадування, відгуки й підрахунок виручки. У changes — старий і новий статус.	`booking`

Тіло запиту

{
  "event": "booking.status_changed",
  "delivery_id": "0f3c1d2e-6f5a-4a1b-9c77-1b2f4e5d6a70",
  "created_at": "2026-09-11T12:31:00+03:00",
  "sandbox": false,
  "changes": {
    "status": { "from": "confirmed", "to": "completed" }
  },
  "data": {
    "id": 914,
    "status": "completed",
    "date": "2026-09-11",
    "time": "11:00",
    "starts_at": "2026-09-11T11:00:00",
    "ends_at": "2026-09-11T12:30:00",
    "duration_minutes": 90,
    "notes": "Просила майстра Ірину",
    "client": { "id": 42, "full_name": "Оксана Мельник", "phone": "+380509998877", "email": null },
    "service": { "id": 3, "name": "Стрижка", "price": "700.00", "duration_minutes": 90 },
    "sandbox": false,
    "expires_at": null,
    "created_at": "2026-09-08T13:40:00+03:00",
    "updated_at": "2026-09-11T12:31:00+03:00"
  }
}

data: той самий обʼєкт, що віддає відповідний ендпоінт API. Другий парсер на ті самі поля писати не треба. changes приходить лише в booking.status_changed.

Заголовки

Заголовок	Що в ньому
`X-ClearMoney-Event`	Код події, те саме, що в полі event.
`X-ClearMoney-Delivery`	UUID доставки. За ним відсіюйте повтори.
`X-ClearMoney-Timestamp`	Час відправлення, ISO 8601.
`X-ClearMoney-Signature`	sha256=<HMAC-SHA256 сирого тіла запиту з вашим секретом>.

Перевірка підпису

Підпис рахується від сирого тіла запиту, до будь-якого розбору JSON. Якщо спершу розібрати й серіалізувати назад, підпис не збіжиться через порядок ключів і пробіли.

import hashlib
import hmac

def is_from_clearmoney(request_body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), request_body, hashlib.sha256
    ).hexdigest()
    # compare_digest, а не ==: побайтове порівняння дає можливість
    # підібрати підпис за часом відповіді.
    return hmac.compare_digest(expected, signature)

<?php
function is_from_clearmoney($body, $signature, $secret) {
    $expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
    return hash_equals($expected, $signature);
}

$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CLEARMONEY_SIGNATURE'] ?? '';
if (!is_from_clearmoney($body, $signature, CLEARMONEY_WEBHOOK_SECRET)) {
    http_response_code(401);
    exit;
}
http_response_code(200);

Вимоги до вашого боку

Тільки https: Ми надсилаємо дані клієнтів: імена, телефони. Посилання на http не приймається, як і адреса у внутрішній мережі.
Відповідайте 2xx: Будь-який код 2xx означає «прийняв». Таймаут 10 секунд, тож складну обробку робіть після відповіді, а не до неї.
Ідемпотентність: Одна подія може прийти двічі, мережа є мережа. Тримайтеся X-ClearMoney-Delivery: той самий UUID означає ту саму подію.

Повтори й відмови

Коли повторюємо: Таймаут, обрив зʼєднання, 429 і 5xx. До 5 спроб із наростаючою паузою: хвилина, потім довше, до двох годин.
Коли не повторюємо: Решта 4xx означає «надсилаєш не те або не туди». Повтори тут лише марно стукають у ваш сервер.
Мертва адреса: 20 невдач підряд, і вебхук вимикається, а в налаштуваннях зʼявляється причина. Інакше інтеграція місяцями «працює», а події нікуди не доходять.
Sandbox: Вебхук безкоштовного тарифу отримує лише події sandbox-обʼєктів. У платного в конверті є поле sandbox, за ним тестові події можна відсіяти.

Наявні ендпоінти кабінету

Ці адреси лишились для сторінок кабінету й працюють лише з сесією браузера. Для інтеграцій вони не потрібні: усе те саме є вище під токеном.

GET /services/api/clients/ Список клієнтів
POST /services/api/clients/create/ Створити клієнта
GET /services/api/clients/<id>/ Один клієнт
POST /services/api/clients/<id>/delete/ Видалити клієнта

Спільні правила

Гроші рядками, дати ISO 8601, ізоляція даних за токеном, ідемпотентність ingest: однакові для всіх модулів і описані на головній документації.

Інші модулі

Товари та замовлення Відкритий API
Облік доходів У планах

Питання по інтеграції пишіть у Telegram або на сторінці підтримки.

Послуги

Доступ

Ліміти й режими

Ендпоінти

Список клієнтів

Параметри запиту

Відповідь 200

Помилки й тіла відповідей

Створити клієнта

Поля тіла запиту

Запит

Відповідь 201

Помилки й тіла відповідей

Один клієнт

Відповідь 200

Помилки й тіла відповідей

Редагувати клієнта

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Змінити статус клієнта

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Історія клієнта

Відповідь 200

Помилки й тіла відповідей

Список послуг

Параметри запиту

Відповідь 200

Помилки й тіла відповідей

Вільні часові слоти

Параметри запиту

Відповідь 200

Помилки й тіла відповідей

Список записів

Параметри запиту

Відповідь 200

Помилки й тіла відповідей

Створити запис

Поля тіла запиту

Запит

Відповідь 201

Помилки й тіла відповідей

Один запис

Відповідь 200

Помилки й тіла відповідей

Редагувати запис

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Змінити статус запису

Поля тіла запиту

Запит

Відповідь 200

Помилки й тіла відповідей

Усі помилки

Вебхуки

Події

Тіло запиту

Заголовки

Перевірка підпису

Вимоги до вашого боку

Повтори й відмови

Наявні ендпоінти кабінету

Спільні правила

Інші модулі