Как подключить ИИ-бота к YCLIENTS и проверять свободные слоты

Для онлайн-записи бот использует Partner Token и booking endpoints: получает услуги, сотрудников, доступные даты и время, затем создаёт запись. Для клиентской истории и других management/CRM методов дополнительно нужен User Token технического пользователя с правами нужного филиала. Webhook сообщает об изменениях записей, но не заменяет API-запросы. После неоднозначного таймаута создание записи нельзя повторять вслепую.

Два уровня доступа

В проверенном проекте EST.EPIL заголовок строится так:

Authorization: Bearer <partner_token>, User <user_token>

Partner Token идентифицирует приложение и используется в клиентском контуре записи. User Token наследует права конкретного пользователя и нужен для management/CRM операций.

YCLIENTS отдельно объясняет, что системного пользователя приложения нужно добавить в филиал и выдать ему необходимые права. Сам факт создания пользователя не открывает клиентскую базу.

Последовательность онлайн-записи

Рабочий маршрут:

определить филиал и услугу
  → GET /book_services/{company_id}
  → GET /book_staff/{company_id}
  → GET /book_dates/{company_id}
  → GET /book_times/{company_id}/{staff_id}/{date}
  → подтвердить имя, телефон и время
  → при необходимости POST /book_code/{company_id}
  → POST /book_record/{company_id}
  → сохранить record_id и hash

Модель разбирает свободную фразу клиента. Код выбирает ID только из ответа API и валидирует дату.

Пример безопасного клиента

Секреты читаются на сервере:

import os
import requests

base = "https://api.yclients.ru/api/v1"
auth = f"Bearer {os.environ['YCLIENTS_PARTNER_TOKEN']}"
user = os.getenv("YCLIENTS_USER_TOKEN")
if user:
    auth += f", User {user}"

headers = {
    "Authorization": auth,
    "Accept": "application/vnd.yclients.v2+json",
    "Content-Type": "application/json",
}

response = requests.get(
    f"{base}/book_services/<company_id>",
    headers=headers,
    timeout=25,
)
response.raise_for_status()
services = response.json()

В настоящем журнале токены и company ID не печатаются.

Почему услуги могут расходиться

В YCLIENTS публичная онлайн-запись и управленческий каталог решают разные задачи. Услуга может существовать в CRM, но не быть опубликована в book_services. Бот не должен обещать запись по одной только management-карточке.

В проекте код различал эти источники и сообщал о несовпадении администратору.

Запись без дублей

GET-запросы безопасно повторять при обрыве или 5xx. С POST /book_record ситуация другая: запись могла создаться, а ответ потеряться. Повтор создаст вторую.

Поэтому рабочий клиент:

• не повторяет book_record автоматически;
• сохраняет record_id и record_hash;
• перед новым действием ищет подтверждение результата;
• показывает оператору неоднозначный случай.

Для отмены записи, созданной через booking path, нужен сохранённый hash. Management API может быть недоступен роли технического пользователя.

Зачем нужен webhook

YCLIENTS отправляет webhook при создании, изменении и удалении записей и других объектов. Сервис принимает POST, проверяет запрос, быстро отвечает и обновляет локальную память идемпотентно.

YCLIENTS event
  → публичный HTTPS endpoint
  → проверка и dedup
  → очередь
  → обновление локального состояния
  → минимальный audit

Официальная справка рекомендует устойчивую обработку, логирование и идемпотентность. Настройка webhook зависит от приложения и подключения филиала.

Реальная ошибка 403

В EST.EPIL бот видел услуги и свободные окна, но поиск истории клиента отвечал 403. Причина была в правах User Token. Пользователя пригласили в филиал и выдали минимальную роль. Промт и модель здесь ни при чём.

Это хороший диагностический признак: если booking API работает, а CRM нет, сначала проверяются пользователь, филиал и роль.

Что остаётся человеку

Администратор подключается при конфликте услуги, переносе со сложными условиями, неоднозначном SMS-подтверждении, медицинском вопросе и любом неподтверждённом результате записи. Бот не выдаёт событие webhook за доказанную живую запись, пока целевая система не вернула объект.

Как тестировать

Проверьте три филиала или другие реальные варианты, услугу вне онлайн-записи, отсутствие мастера, пустой день, SMS-код, timeout после POST, повтор webhook, 403 CRM и отмену по hash. Логи должны показывать класс ошибки без телефона и клиентской истории.

Geron Labs может начать с read-only подключения расписания, а создание записи включить после проверки прав и дублей.

Читайте также: Как настроить данные, инструменты, память и эскалации ИИ-агента, Как ИИ-агент помогает продажам и когда передаёт клиента менеджеру.

Источники

• YCLIENTS, доступ к API: support.yclients.ru/67-68-199--dostup-k-api/ (проверено 28.09.2026).
• YCLIENTS, webhooks: support.yclients.ru/993 (проверено 28.09.2026).