# YCLIENTS

## Что это

**YCLIENTS** — CRM и сервис онлайн-записи для салонов красоты, клиник, фитнес-клубов и других сервисных бизнесов. Интеграция позволяет боту записывать клиентов прямо в журнал филиала. Бот показывает услуги и мастеров, находит свободные даты и время, создаёт, отменяет и переносит записи. Если в подключении указаны логин и пароль администратора, бот также ищет клиента по телефону и показывает его предстоящие визиты.

## Требования

- Филиал в [YCLIENTS](https://www.yclients.com) с включённой онлайн-записью: услуги и мастера должны быть доступны для онлайн-записи.
- **Partner token** — выдаётся в кабинете разработчика [developers.yclients.com](https://developers.yclients.com/ru/). Приложение с этим токеном должно быть подключено к вашему филиалу.
- **ID филиала** — число из адреса кабинета YCLIENTS, например `yclients.com/timetable/123456`.
- Для операций с клиентами и записями — **логин и пароль** сотрудника филиала с правами на клиентскую базу и журнал записи. Необязательно.

## Как подключить

1. Получите partner token в кабинете разработчика YCLIENTS и подключите приложение к своему филиалу.
2. Скопируйте ID филиала из адреса кабинета YCLIENTS.
3. В конструкторе откройте **Интеграции** → найдите карточку **YCLIENTS** → **Подключить**.
4. Заполните поля **Partner token** и **ID филиала**. Если нужны поиск клиентов, их записи или перенос записи, укажите также логин и пароль администратора.
5. Сохраните подключение и нажмите **Проверить соединение**. Кнопка запрашивает данные филиала, а если заданы логин и пароль — ещё и выполняет вход.

## Доступные операции

| Операция | Что делает |
|---|---|
| Список услуг | Услуги онлайн-записи: ID, название, цена от/до, длительность. Можно отфильтровать по мастеру |
| Список мастеров | Мастера онлайн-записи: ID, имя, специализация, рейтинг. Можно отфильтровать по услуге и времени |
| Свободные даты | Даты, на которые есть свободное время, с учётом услуги и мастера |
| Свободное время | Свободные окна на выбранную дату; без мастера — у любого свободного |
| Создать запись | Проверяет окно и записывает клиента (имя, телефон, email, комментарий). Возвращает ID и хэш записи |
| Отменить запись | Отменяет запись по её ID и хэшу |
| Найти клиента по телефону | Ищет клиента в базе филиала: ID, имя, телефон, email. *Нужны логин и пароль* |
| Создать клиента | Добавляет клиента в базу филиала. *Нужны логин и пароль* |
| Предстоящие записи клиента | Записи клиента с сегодняшнего дня (до 20): дата, услуги, мастер. *Нужны логин и пароль* |
| Перенести запись | Меняет время существующей записи, сохраняя услуги и мастера. *Нужны логин и пароль* |

## Ограничения

- Операции онлайн-записи видят только услуги и мастеров, открытых для онлайн-записи в настройках филиала.
- Одно подключение работает с одним филиалом. Для сети филиалов создайте отдельное подключение на каждый.
- YCLIENTS ограничивает частоту запросов к API. Не вызывайте списки в цикле — сохраняйте результат в переменные.
- Дата и время передаются в формате ISO 8601. Для создания записи используйте поле `datetime` из результата операции «Свободное время».

## Особенности и примечания

> Типичный сценарий записи: «Список услуг» → «Свободное время» на выбранную дату → «Создать запись». В мастере создания бота эти три шага уже собраны в инструменты ИИ-диалога.

> Сохраните `record_id` и `record_hash` из операции «Создать запись» в переменные клиента — они нужны, чтобы бот мог отменить запись.

> По логину и паролю Botconsole сам получает токен пользователя YCLIENTS и хранит его в зашифрованном виде. Если сменить логин в подключении, токен будет получен заново.