Успешный ответ
У успешного ответа ok равен true. Данные метода находятся в data.
Документация
API
Формат запросов, ответов и справочник полей для интеграций.
Общие правила
API возвращает JSON-ответы с единым признаком результата. Для ошибок передается числовой code верхнего уровня и список полей, если ошибка относится к данным формы.
Ошибки
У ошибки ok равен false. Поле code всегда числовое, а errors и required описывают проблемные поля.
Язык
Параметр api_lang принимает ru или en и влияет на текст сообщений API.
Доступ
Публичные методы доступны без сессии. Методы кабинета используют текущего пользователя и текущую организацию. Если у пользователя несколько организаций, организацию запроса можно выбрать параметром current_organization_id.
Дата и время
Каждое поле типа datetime возвращается в часовом поясе, который относится именно к этому полю. Общего корневого timezone для всего объекта нет.
Для поля <имя> API добавляет <имя>_iso_string в ISO 8601 со смещением и <имя>_timezone с IANA-зоной. Основное значение имеет формат YYYY-MM-DD HH:mm:ss.
В одном объекте поля могут использовать разные зоны: дата события — зону организации, а дата уведомления — зону пользователя.
Если datetime равен null, основное и ISO-поле равны null, а связанное поле timezone сохраняет применённую зону.
Поля с суффиксами _iso_string и _timezone предназначены только для чтения. При сохранении передавайте исходное поле datetime.
Правило не применяется к отдельным полям date, time, длительности, Unix timestamp и датам исключений EXDATE. Финансовый API mod=finance использует часовой пояс организации из context.timezone и не добавляет эти суффиксы к каждому полю.
Объект с разными часовыми поясами
{
"event": {
"dt_start": "2026-07-31 10:00:00",
"dt_start_iso_string": "2026-07-31T10:00:00+05:00",
"dt_start_timezone": "Asia/Yekaterinburg"
},
"notification": {
"read_at": "2026-07-31 08:15:00",
"read_at_iso_string": "2026-07-31T08:15:00+03:00",
"read_at_timezone": "Europe/Moscow"
}
}API-ключи
Для серверных интеграций кабинетный API можно вызывать без браузерной сессии, если передать ключ в HTTP-заголовке. Основной способ — Authorization: Bearer <api_key>. X-API-Key: <api_key> доступен как запасной вариант для серверов и прокси, которые не передают заголовок Authorization в приложение. Ключ выбирает того же пользователя, от имени которого он создан, и фиксирует текущую организацию запроса. Если у ключа включен режим только чтения, запросы на изменение данных вернут ошибку. Те же правила действуют для финансового API mod=finance: дополнительно учитываются права пользователя и доступность финансового модуля.
Создать, отключить или удалить ключ можно в настройках API-ключей. Полный ключ показывается только один раз после создания.
Способы передачи ключа
Authorization: Bearer <api_key>
X-API-Key: <api_key>Коды API-ключей
Эти коды относятся к авторизации ключом и управлению ключами кабинета.
| Код | Когда возникает | Ответ |
|---|---|---|
31 | API-ключ создан в режиме только чтения, а запрос пытается изменить данные. | message о запрете записи этим ключом. |
32 | API-ключ превысил лимит 120 запросов в минуту. | HTTP 429 и message о повторе позже. |
1101 | Для создания API-ключа не выбран текущий пользователь или организация. | message о необходимости выбрать организацию. |
1102 | API-ключ не найден, отключен, удален или не принадлежит текущей организации. | message об отсутствующем ключе. |
Формат ответа
Верхний уровень всегда описывает общий результат запроса. В успешном ответе data сразу содержит сохраненную или найденную сущность, список или другой результат метода.
| Поле | Тип | Описание |
|---|---|---|
ok | boolean | Признак результата запроса. true — успешно, false — ошибка. |
code | number | Числовой код ошибки верхнего уровня. Передается во всех ответах с ok=false. |
message | string | Общее текстовое сообщение для ошибки, если она не привязана к конкретному полю. |
data | object|array | Данные успешного ответа: сохраненная сущность, список или другой результат метода. |
required | array | Список обязательных незаполненных полей. Обычно приходит с code=16. |
errors | array | Список заполненных, но невалидных полей. Обычно приходит с code=17. |
Получение и сохранение данных
Для разделов данных используется единый формат. При получении через mod=data в ответе всегда приходят data и custom_fields. В data находится запись или список записей, а в custom_fields — справочник кастомных полей этого раздела. При сохранении через mod=save_data стандартные поля передаются на верхнем уровне тела запроса, а значения кастомных полей — в custom_fields. Для создания записи id не передается; для обновления передайте id в теле запроса.
| Метод | URL | Описание |
|---|---|---|
GET | /api/?mod=data&data=ENTITY | Получить список записей. Ответ содержит data со списком и custom_fields со справочником кастомных полей. |
GET | /api/?mod=data&data=ENTITY&id=ID | Получить одну запись по id. Ответ содержит data с объектом записи и custom_fields со справочником кастомных полей. |
POST | /api/?mod=save_data&data=ENTITY | Создать или сохранить запись. Для создания не передавайте id; для обновления передайте id в теле запроса. Успешный ответ возвращает сохраненную запись в data. |
POST | /api/?mod=delete_data&data=ENTITY&id=ID | Удалить запись по id. После успешного запроса запись больше не возвращается в ответах API. |
Пример получения данных
{
"ok": true,
"data": [
{
"id": 12,
"public_name": "Барбершоп на Пятницкой",
"customFields": {
"x9m2q7": "7700000000"
}
}
],
"custom_fields": [
{
"uid": "x9m2q7",
"name": "ИНН",
"type": "string",
"required": false
}
]
}Пример тела сохранения
{
"id": 12,
"public_name": "Барбершоп на Пятницкой",
"type": "service_studio",
"custom_fields": {
"x9m2q7": "7700000000"
}
}Пример ответа сохранения
{
"ok": true,
"data": {
"id": 12,
"public_name": "Барбершоп на Пятницкой",
"type": "service_studio",
"customFields": {
"x9m2q7": "7700000000"
}
}
}Пример удаления
POST /api/?mod=delete_data&data=resources&id=12
{
"ok": true
}Финансовый API кабинета
Ошибки полей
Если ошибка относится к форме, верхний code остается общим, а детали передаются списком required или errors.
| Поле | Тип | Описание |
|---|---|---|
required[].field | string | Имя незаполненного обязательного поля. |
required[].text | string | Текст ошибки для обязательного поля. |
errors[].type | string | Машинный тип ошибки поля: select_error, invalid_timezone, time_error и другие. |
errors[].field | string | Имя поля, к которому относится ошибка. |
errors[].text | string | Пользовательский текст ошибки поля. |
Общие коды ошибок
Эти коды могут вернуться при работе с любым разделом данных, включая организации.
| Код | Когда возникает | Ответ |
|---|---|---|
1 | Запрос не обработан ни одним модулем, action или mod. | message с общей неизвестной ошибкой. |
2 | Пользователь не авторизован для непубличного API. | message о необходимости авторизации. |
11 | Нет прав на действие в текущей организации. | message о правах доступа. |
12 | Создание записи запрещено. | message о запрете создания. |
13 | Пользователь не может сохранить существующую запись. | message о запрете сохранения. |
14 | Превышен тарифный лимит записей. | message о лимите тарифа. |
15 | Редактирование этого раздела запрещено. | message с причиной запрета редактирования. |
16 | Не заполнены обязательные стандартные или кастомные поля. | required со списком полей. |
17 | Заполненные поля не прошли валидацию. | errors со списком ошибок полей. |
18 | Удаление записи запрещено. | message с причиной запрета удаления. |
19 | Не передан корректный порядок сортировки или этот раздел не поддерживает сортировку. | message об отсутствии сортировки. |
20 | Нет доступа к id, которые переданы для сортировки. | message о запрете сохранения. |
21 | Не переданы данные для сохранения или отсутствует обязательный контекст сохранения. | message о нехватке данных. |
Пример успешного ответа
{
"ok": true,
"data": {
"id": 12
}
}Пример ошибки валидации
{
"ok": false,
"code": 17,
"errors": [
{
"type": "select_error",
"field": "type",
"text": "Недопустимое значение"
}
]
}