Skip to content

BITRIX_APP_INSTALL.md

Latest commit

 

History

History
241 lines (166 loc) · 7.96 KB

BITRIX_APP_INSTALL.md

File metadata and controls

241 lines (166 loc) · 7.96 KB
Raw

Bitrix24 REST App Installation

Detailed guide for installing the YCLIENTS booking widget as a Bitrix24 local app.

Подробная инструкция по установке виджета онлайн-записи YCLIENTS в Bitrix24.

Обзор

После установки в карточке сделки появится вкладка "Записать в YCLIENTS", где менеджер сможет:

  • Выбрать филиал (из 5 доступных)
  • Выбрать дату и мастера
  • Посмотреть расписание (timeline с 15-минутной сеткой)
  • Выбрать услугу (с поиском и отображением длительности)
  • Записать клиента — данные подставятся из сделки автоматически

Виджет: static/widget/booking-app.html (v2.2, custom UI)

Этап 1: Подготовка данных (20 минут)

1.1. Получить токены YCLIENTS

Нужны два токена:

  • Partner Token — YCLIENTS → Настройки → API → Партнёрский токен
  • User Token — YCLIENTS → Настройки → API → Авторизация пользователя

1.2. Создать локальное приложение в Bitrix24

Шаг 1: Портал Bitrix24 → Приложения → Разработчикам → Другое → Локальное приложение

Шаг 2: Нажать "Зарегистрировать приложение"

Шаг 3: Заполнить форму:

Название: YCLIENTS Запись клиентов
Код: yclients_booking
Путь вашего обработчика: https://your-domain.example.com/bitrix-app/install
Путь начальной страницы: https://your-domain.example.com/bitrix-app/widget-frame

Шаг 4: Выбрать права:

  • CRM (crm)
  • Встраивание приложений (placement)

Шаг 5: Сохранить и скопировать:

  • CLIENT_ID (например local.67abc123.45678)
  • CLIENT_SECRET (длинная строка)

Этап 2: Настройка окружения (30 минут)

2.1. Обновить .env

nano .env

Добавить:

# Bitrix24 REST Application
BITRIX_CLIENT_ID=local.xxx.xxx
BITRIX_CLIENT_SECRET=ваш_секрет
BITRIX_APP_DOMAIN=your-domain.example.com

# YCLIENTS
YCLIENTS_PARTNER_TOKEN=xxx
YCLIENTS_USER_TOKEN=xxx
YCLIENTS_COMPANY_IDS=100001,100002,100003,100004,100005

# Включить обработку событий
PROCESSOR_ENABLED=true

2.2. Применить миграцию БД

cat migrations/add_bitrix_apps_table.sql | docker compose exec -T db psql -U hooks_user -d hooks_db

Проверить:

docker compose exec db psql -U hooks_user -d hooks_db -c "\d bitrix_apps"

2.3. Деплой на сервер

# Копируем файлы (git на сервере не работает!)
scp -r app/* root@YOUR_SERVER_IP:/root/yclients-bitrix/app/
scp -r static/widget/booking-app.* \
    root@YOUR_SERVER_IP:/root/yclients-bitrix/static/widget/

# Пересборка
ssh root@YOUR_SERVER_IP "cd /root/yclients-bitrix && docker compose up -d --build hooks"

2.4. Nginx (если не настроен)

sudo nginx -t && sudo systemctl reload nginx

2.5. Проверить endpoints

# Healthcheck
curl https://your-domain.example.com/healthz

# Widget (должен вернуть HTML)
curl -I https://your-domain.example.com/bitrix-widget/booking-app.html
# Должно быть: HTTP/2 200

Этап 3: Установка приложения на портал (10 минут)

3.1. Открыть приложение

В браузере:

https://your-portal.bitrix24.ru/marketplace/local/yclients_booking/

Или: Приложения → Разработчикам → Локальное приложение → "YCLIENTS Запись клиентов" → Установить

3.2. Подтвердить права

Нажать "Установить".

3.3. Что произойдёт автоматически

  1. Bitrix перенаправит на https://your-domain.example.com/bitrix-app/install?code=...&domain=...
  2. Сервер обменяет code на access_token
  3. Токены сохранятся в таблице bitrix_apps
  4. Placement зарегистрируется (вкладка в карточке сделки)
  5. Перенаправление обратно на портал

Логи:

docker compose logs -f hooks | grep "bitrix-app"

Ожидаемые логи:

INFO:bitrix-app exchanging code for token domain=your-portal.bitrix24.ru
INFO:bitrix-app tokens stored domain=your-portal.bitrix24.ru
INFO:bitrix-app registering placement domain=your-portal.bitrix24.ru
INFO:bitrix-app app installed successfully domain=your-portal.bitrix24.ru

Этап 4: Тестирование (30 минут)

4.1. Проверка вкладки

  1. Открыть CRM → Сделки → любая сделка
  2. Найти вкладку "Записать в YCLIENTS"

4.2. Проверка виджета

  1. Кликнуть вкладку → должен загрузиться выбор филиалов:
    • Курская, Медведково, Китай Город, Митино, Котельники

4.3. Тест записи

  1. Выбрать филиал → дату → мастера → время → услугу
  2. Подтвердить
  3. Проверить в YCLIENTS что запись появилась
  4. Через 5-10 сек обновить сделку — поля должны заполниться

Этап 5: Troubleshooting

Вкладка не появилась

# Проверить что токены сохранились
docker compose exec db psql -U hooks_user -d hooks_db -c "SELECT domain, expires_at FROM bitrix_apps;"

# Вручную зарегистрировать placement
curl -X POST "https://your-domain.example.com/bitrix-app/refresh-placement?domain=your-portal.bitrix24.ru"

# Если не помогло — удалить и переустановить приложение

Белый экран

  1. Открыть консоль (F12)
  2. Ошибка CORS → проверить nginx конфигурацию
  3. Проверить заголовки: curl -I https://your-domain.example.com/bitrix-widget/booking-app.html
  4. Должен быть Content-Security-Policy: frame-ancestors https://*.bitrix24.ru ...

Данные клиента не подставляются

  1. У сделки должен быть контакт
  2. У контакта должен быть телефон
  3. Проверить API: /bitrix-app/api/deal-info?deal_id=XXX&domain=your-portal.bitrix24.ru

OAuth токен истёк

Токены обновляются автоматически. Если не обновляются:

docker compose exec db psql -U hooks_user -d hooks_db \
    -c "SELECT domain, expires_at FROM bitrix_apps;"

# Переустановить приложение если токены протухли

Полезные команды

# Логи
docker compose logs -f hooks | grep "bitrix-app"

# БД: OAuth токены
docker compose exec db psql -U hooks_user -d hooks_db -c "SELECT * FROM bitrix_apps;"

# БД: События за сегодня
docker compose exec db psql -U hooks_user -d hooks_db \
    -c "SELECT id, source, status, received_at FROM webhook_events WHERE received_at > NOW() - INTERVAL '1 day' ORDER BY received_at DESC LIMIT 20;"

# Перезапуск
docker compose down && docker compose up -d --build

Контакты

  • Сервер: YOUR_SERVER_IP
  • Домен: your-domain.example.com
  • Битрикс портал: your-portal.bitrix24.ru