Интеграция
YClients + Telegram бот: полная настройка
8-шаговый гайд по интеграции Telegram-бота с YClients. От получения Partner Token до работы с сетями филиалов и депозитами через СБП. Для интеграторов и тех, кто делает самостоятельно.
1
Получить Partner Token от YClients
- Написать в поддержку YClients с запросом на партнёрскую интеграцию
- Указать название продукта, URL, описание use case
- Срок одобрения: 3-14 дней
- Partner Token нужен всем провайдерам, работающим с множественными клиентами
- Без Partner Token вы сможете работать только в одном аккаунте YClients (для соло-бота это ок)
2
Получить User Token от клиента
- Клиент (салон/клиника) заходит в свой аккаунт YClients
- Настройки → Интеграции → Partner API → Создать токен
- Передаёт токен интегратору через защищённый канал (не email!)
- Записать токен в Vault / .env (не в код)
- User Token привязан к конкретному company_id в YClients
3
Базовые API запросы
- GET /company/{company_id}/staff — список мастеров
- GET /book_staff/{company_id} — свободные слоты конкретного мастера
- GET /company/{company_id}/services — каталог услуг с ценами
- POST /book_record/{company_id} — создать запись
- PUT /records/{record_id} — перенести запись
- DELETE /records/{record_id} — отменить запись
- Все запросы требуют headers: Authorization: Bearer PARTNER_TOKEN, X-User-Token: USER_TOKEN
4
Кэширование расписания (обязательно!)
- Расписание мастеров не должно дёргаться при каждом запросе клиента
- Реализовать Redis-кэш с TTL 30 минут
- Фоновый cron-job обновляет кэш каждые 15 минут
- Кэш ключи: schedule:{company_id}:{master_id}:{date}
- При создании/отмене записи — инвалидация кэша для этой даты
5
Rate limits и backoff
- YClients лимит: 60 запросов/минуту на компанию
- Implement token-bucket rate limiter
- При 429 ответе — exponential backoff (1с, 2с, 5с, 15с)
- После 5 попыток — логировать и уведомить админа
- Для сетей из 10+ филиалов — распараллелить по company_id
6
Webhook'и от YClients
- Настройки → Интеграции → Webhooks в личном кабинете YClients
- Подписаться на события: record_created, record_updated, record_deleted
- URL webhook: https://your-app/webhooks/yclients
- Обрабатывать события асинхронно (очередь)
- Обновлять свою БД + отправлять уведомления в Telegram клиенту
7
Депозиты через СБП + ЮKassa
- YClients не поддерживает депозиты — реализовать отдельно
- При записи: создать запись в YClients + создать платёж в ЮKassa
- Ссылка на оплату в Telegram сообщение клиента
- Webhook ЮKassa → обновление статуса депозита в вашей БД
- При приходе клиента (статус записи = «выполнена») → депозит возвращается как бонус
- При неявке — депозит остаётся салону
- Отдельная таблица: deposits(id, yclients_record_id, amount, status, payment_id)
8
Сети филиалов (multi-company)
- В YClients каждый филиал — отдельная «компания» с отдельным company_id
- Для сети из 5 филиалов — 5 company_id, но один Partner Token
- Бот должен уметь роутить запросы: «мне в Митино» → company_id филиала Митино
- Реализовать маппинг: label → company_id
- Клиент видит все филиалы в одном боте через меню
Tyaga Lab делает это за час
Наша YClients-интеграция готова из коробки: Partner Token получен, кэш настроен, депозиты работают, мульти-филиалы из коробки. Клиенту остаётся только выдать User Token — подключение занимает ~1 час.