Бронирование
Расширение «Бронирование» принимает записи клиентов с вашего сайта. Каждая запись становится задачей формы, а занятое время проверяется на сервере: два клиента не запишутся на одно время к одному мастеру.
Что нужно подготовить
| Форма | Что в ней |
|---|---|
| Записи (форма с расширением) | Поле Date с включённым периодом, поля клиента (Text, Phone, Email), ссылка на мастера и услуги |
| Услуги (необязательно) | Название, длительность в минутах (Number), цена (Number), при желании категория и перерыв после услуги |
| Мастера (необязательно) | Имя, расписание (поле Schedule), при желании сотрудник (Person) и таблица услуг мастера |
Без формы услуг запись идёт на фиксированное время. Без формы мастеров у формы один общий календарь.
Настройка
- Бот. Пользователь с ролью
BOT, у которого есть доступ к форме с правом создавать задачи. Записи с сайта создаются от его имени. - Поле даты. Поле Date с периодом: в него записываются начало и конец записи.
- Часовой пояс и разрешённые сайты — адреса, с которых виджет может обращаться к API, по одному в строке.
- Услуги и Мастера. Выберите формы, где хранятся услуги и мастера. В настройках появятся блоки
serviceиresource, а под ними списки полей выбранных форм с их id. - Допишите id полей в JSON вместо
null: как минимумduration_field_id— поле длительности в форме услуг. - Сохраните и включите расширение.
Настроить бронирование может и AI-admin: напишите ему, для какой формы включить онлайн-запись.
Услуги: одна или несколько
Режим выбирается тем, как форма записей ссылается на форму услуг. Используется один из двух.
| Режим | Что в форме записей | Блок в настройках |
|---|---|---|
| Одна услуга в записи | Поле Form, связанное с формой услуг | "service": {"field_id": ...} |
| Несколько услуг подряд у одного мастера | Таблица с колонкой Form, связанной с формой услуг | "service": {"table": {...}, "max_services": 5} |
При нескольких услугах время записи равно сумме длительностей, перерыв берётся у последней услуги, а в поле цены записывается общая сумма.
"service": {
"table": {
"table_field_id": 6090,
"service_column_id": 6091,
"price_column_id": 6092,
"duration_column_id": 6093
},
"max_services": 5,
"duration_field_id": 6070,
"price_field_id": 6071,
"category_field_id": 6072,
"buffer_field_id": null
}duration_field_id, price_field_id, category_field_id и buffer_field_id — поля формы услуг. Остальные id — поля формы записей.
Мастера
"resource": {
"field_id": 6079,
"schedule_field_id": 6060,
"person_field_id": null,
"services_table": {
"table_field_id": 6061,
"service_column_id": 6062,
"price_column_id": null,
"duration_column_id": null
}
}| Настройка | Значение |
|---|---|
field_id | Поле формы записей, связанное с формой мастеров |
schedule_field_id | Поле Schedule в карточке мастера: его рабочие часы |
person_field_id | Поле Person в карточке мастера: берутся рабочие часы и отсутствия сотрудника |
services_table | Таблица в карточке мастера: какие услуги он оказывает |
Рабочие часы мастера берутся в таком порядке: расписание в карточке → расписание сотрудника → resource.working_hours → общие working_hours. Дни отсутствия сотрудника закрыты целиком.
Услуги мастера. Если задана services_table, мастер предлагается только для услуг из своей таблицы. Мастер с пустой таблицей не предлагается ни для одной услуги.
Своя цена и длительность. Колонки price_column_id и duration_column_id нужны только если у мастера свои цены или время. Заполненная ячейка заменяет значение из формы услуг и не меняется вместе с ним, пустая означает «как в форме услуг».
Остальные настройки
| Настройка | Значение |
|---|---|
slot_step_min | Шаг сетки времени начала, минуты |
min_lead_min | За сколько минут до начала ещё можно записаться |
max_days_ahead | На сколько дней вперёд открыт календарь |
working_hours | Общие рабочие часы: {"mon": [["09:00","13:00"],["14:00","18:00"]], "sun": []} |
default_duration_min | Длительность записи, когда услуг нет |
price_field_id | Поле Number формы записей, куда записывается цена |
client_fields | Что может прислать сайт: [{"key": "name", "form_field_id": 6081, "required": true}]. Типы полей: Text, Textarea, Phone, Email |
Виджет записи на сайте
Адрес API и ключ показаны на вкладке Подключение сайта. Ключ публичный: его можно писать в коде страницы. Сайт должен быть в списке разрешённых.
Ответы приходят в виде {"success": true|false, "error_message": ..., "data": ...}.
1. Каталог — один раз при загрузке
GET {base}| Поле ответа | Значение |
|---|---|
services | Услуги: id, name, duration_min, price, category |
resources | Мастера: id, name, service_ids — услуги, которые мастер оказывает |
max_services | Сколько услуг можно выбрать в одной записи; 1 — одна |
fields | Поля клиента: key, label, type, required |
timezone, slot_step_min, max_days_ahead | Часовой пояс и границы календаря |
2. Мастера под выбранные услуги
Фильтруйте список в самом виджете, без запроса: показывайте мастера, только если в его service_ids есть все выбранные услуги. Если у мастера нет service_ids, он оказывает любые услуги.
Отдельный запрос нужен только когда у мастеров свои цены или длительность:
GET {base}/resources?service_ids=12,15В ответе у каждого мастера service с его ценой и длительностью.
3. Свободное время
GET {base}/slots?date=2026-11-25&service_ids=12,15&resource_id=51350&include_busy=true- Без
resource_id— «любой мастер»: время свободно, если свободен хотя бы один мастер, который оказывает все выбранные услуги. include_busy=trueвозвращает всю сетку с признакомavailable; без него — только свободное время.startпоказывайте как есть: он уже в часовом поясе салона.
4. Запись
POST {base}/bookings
Content-Type: application/json
Idempotency-Key: <UUID>
{
"start": "2026-11-25T10:00+02:00",
"service_ids": ["12", "15"],
"resource_id": 51350,
"language": "ru",
"fields": {"name": "Анна", "phone": "+37255512345"}
}Для одной услуги можно передать "service_id": "12". Без resource_id мастера выберет система. В ответе reference — номер записи.
Правила
- Сервер проверяет всё сам. Время вне расписания, занятое время или мастер, который не оказывает услугу, вернут ошибку, даже если виджет это пропустил.
- Один
Idempotency-Keyна одну попытку записи. При повторе того же запроса используйте тот же ключ: запись не задвоится. 409с кодомslot_taken: время только что заняли, загрузите время заново.400: покажите клиентуerror_message.429: слишком много запросов, повторите позже.- Свободное время всегда запрашивайте с сервера, не вычисляйте его в виджете.
Изменение записи в системе
Запись — обычная задача. Если сотрудник меняет время или мастера, отменяет или удаляет задачу, занятое время обновляется само. Запись, созданная сотрудником вручную, тоже занимает время и не даст записаться на него с сайта.