Skip to content

Бронирование ​

Расширение «Бронирование» принимает записи клиентов с вашего сайта. Каждая запись становится задачей формы, а занятое время проверяется на сервере: два клиента не запишутся на одно время к одному мастеру.

Что нужно подготовить ​

ФормаЧто в ней
Записи (форма с расширением)Поле Date с включённым периодом, поля клиента (Text, Phone, Email), ссылка на мастера и услуги
Услуги (необязательно)Название, длительность в минутах (Number), цена (Number), при желании категория и перерыв после услуги
Мастера (необязательно)Имя, расписание (поле Schedule), при желании сотрудник (Person) и таблица услуг мастера

Без формы услуг запись идёт на фиксированное время. Без формы мастеров у формы один общий календарь.

Настройка ​

  1. Бот. Пользователь с ролью BOT, у которого есть доступ к форме с правом создавать задачи. Записи с сайта создаются от его имени.
  2. Поле даты. Поле Date с периодом: в него записываются начало и конец записи.
  3. Часовой пояс и разрешённые сайты — адреса, с которых виджет может обращаться к API, по одному в строке.
  4. Услуги и Мастера. Выберите формы, где хранятся услуги и мастера. В настройках появятся блоки service и resource, а под ними списки полей выбранных форм с их id.
  5. Допишите id полей в JSON вместо null: как минимум duration_field_id — поле длительности в форме услуг.
  6. Сохраните и включите расширение.

Настроить бронирование может и AI-admin: напишите ему, для какой формы включить онлайн-запись.

Услуги: одна или несколько ​

Режим выбирается тем, как форма записей ссылается на форму услуг. Используется один из двух.

РежимЧто в форме записейБлок в настройках
Одна услуга в записиПоле Form, связанное с формой услуг"service": {"field_id": ...}
Несколько услуг подряд у одного мастераТаблица с колонкой Form, связанной с формой услуг"service": {"table": {...}, "max_services": 5}

При нескольких услугах время записи равно сумме длительностей, перерыв берётся у последней услуги, а в поле цены записывается общая сумма.

json
"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 — поля формы записей.

Мастера ​

json
"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: слишком много запросов, повторите позже.
  • Свободное время всегда запрашивайте с сервера, не вычисляйте его в виджете.

Изменение записи в системе ​

Запись — обычная задача. Если сотрудник меняет время или мастера, отменяет или удаляет задачу, занятое время обновляется само. Запись, созданная сотрудником вручную, тоже занимает время и не даст записаться на него с сайта.