# Подключение коробочного Битрикс24

Коробочный Битрикс24 заказчик разворачивает на своём сервере, а не в облаке Битрикс24. Чтобы Вайбкод мог работать с таким Битрикс24 — обращаться к CRM, задачам, ботам, выписывать вебхуки — на его стороне нужен личный ключ разработчика.

Подключение идёт через бот-компаньон: один раз для всего Битрикс24 и по одному подтверждению на каждого пользователя. В кабинете такой Битрикс24 подписан двояко — на карточке стоит отметка «Self-hosted», а в заголовке его настроек «Коробочная версия Битрикс24».

## Как это работает

### Шаг 1. Администратор Битрикс24 — один раз

Шаг выполняет любой пользователь коробочного Битрикс24 с правами администратора.

1. Откройте административный раздел Битрикс24
2. Установите бесплатный модуль «VibeCode Connector», если его ещё нет — он лежит в разделе модулей
3. Откройте настройки модуля
4. Нажмите «Подключить к Вайбкоду»
5. Дождитесь окончания активации — модуль зарегистрирует Битрикс24 на платформе Вайбкод, выпишет ключ разработчика администратора, установит приложение и зарегистрирует бот-компаньон

После этого шага любой пользователь этого Битрикс24 подключает себя сам — обращаться к администратору повторно не нужно.

### Шаг 2. Пользователь Вайбкод — одно подтверждение

1. Откройте Вайбкод, перейдите на экран [Выберите портал](/auth/portals)
2. Нажмите «Подключить коробочную версию Битрикс24»
3. Введите адрес своего Битрикс24 — например, `mybox.example.com` — и нажмите «Подключить»
4. Мастер проверит, что этот Битрикс24 зарегистрирован и бот-компаньон на нём установлен
5. Нажмите «Подтвердить в браузере» или «Подтвердить в десктоп-приложении» — откроется чат с «Вайбкод Бот» в мессенджере Битрикс24, и туда придёт запрос на привязку
6. В запросе видна карточка с вашим именем и почтой из кабинета Вайбкод и две кнопки — «Да, это я» и «Нет, это не я»
7. Нажмите «Да, это я» — Вайбкод выпишет ваш личный ключ разработчика и откроет дашборд этого Битрикс24

Открывайте чат там, где вы уже вошли в свой Битрикс24 — в приложении на компьютере или в браузере. Кнопки подтверждения активны 10 минут. Если сообщение от бота не пришло, в мастере есть повторная отправка.

Готово. С этого момента ваши скрипты, агенты и приложения Вайбкод могут обращаться к этому Битрикс24 от вашего имени.

Если вы уже подключали этот Битрикс24 раньше, мастер пропускает подтверждение в боте и сразу открывает дашборд.

## Состояния мастера подключения

| Состояние | Что видит пользователь | Что происходит |
|---|---|---|
| **Проверка адреса** | «Проверяем ваш Битрикс24» | Мастер ищет регистрацию по введённому адресу |
| **Ожидание подтверждения** | «Подтвердите, что это вы», кнопки подтверждения активны 10 минут | Запрос отправлен в чат с ботом |
| **Успех** | «Битрикс24 подключён», отсчёт до перехода на дашборд | Пользователь нажал «Да, это я», ключ разработчика выписан |
| **Регистрация не найдена** | «Вайбкод пока не знает этот Битрикс24» с инструкцией шага 1 | Модуль на Битрикс24 ещё не активирован |
| **Бот-компаньон не подключён** | «Бот-компаньон ещё не подключён» | Битрикс24 платформе известен, но бота, с которым можно говорить, на нём нет |
| **Активация продолжается** | «Подключение активируется» | Бот-компаньон устанавливается либо Битрикс24 временно недоступен |
| **Отклонено** | «Подтверждение отклонено» | Пользователь нажал «Нет» в боте |
| **Срок истёк** | «Срок подтверждения истёк» | С момента запроса прошло больше 10 минут |
| **Ключ не выписан** | «Не удалось выписать ключ» с кодом ошибки | Подтверждение прошло, но ключ разработчика выписать не удалось |

## Что делать в типичных ситуациях

### «Вайбкод пока не знает этот Битрикс24»

Этот Битрикс24 ещё не зарегистрирован на платформе. Попросите администратора выполнить шаг 1: установить модуль «VibeCode Connector» и нажать «Подключить к Вайбкоду». После этого вернитесь в мастер и нажмите «Я подключил — повторить».

### «Бот-компаньон ещё не подключён»

Проверьте три условия: модуль «VibeCode Connector» установлен и активирован, кнопка «Подключить к Вайбкоду» нажата, и на Битрикс24 разрешён входящий защищённый доступ со стороны платформы Вайбкод — межсетевой экран и трансляция сетевых адресов (NAT) не должны его блокировать.

### «Подключение активируется»

Бот-компаньон ещё устанавливается либо Битрикс24 временно недоступен. Повторите попытку через пару минут.

### Бот пишет «Запрос на привязку отклонён» — а вы ничего не отклоняли

Если подключение запускали не вы, запрос отправил кто-то другой, чтобы привязать ваш Битрикс24 к своей учётной записи Вайбкод. Нажать «Нет» было верным решением. Сообщите администратору Битрикс24: так выглядит попытка получить доступ к вашему Битрикс24 через вашу учётную запись.

### «Срок подтверждения истёк» — прошло больше 10 минут

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

### Бот пишет «Кнопка устарела» — нажимаю «Да, это я», а ничего не происходит

Так бывает, когда открыто старое сообщение от бота, а мастер за это время создал новый код подтверждения — например, если Вайбкод открыт в нескольких вкладках. Вернитесь в мастер, убедитесь, что он показывает свежий запрос, и нажмите кнопку подтверждения заново.

### Сообщение от бота не пришло

В мастере есть кнопка «Отправить ещё раз». Если чат с ботом уже открыт, закройте вкладку мессенджера и нажмите кнопку подтверждения снова. Когда попытки отправки исчерпаны, начните подключение заново.

### Кнопка «Подключить коробочную версию Битрикс24» не появляется

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

Пока идёт постепенное включение, кнопка видна с пометкой «бета», а в окне подключения показан баннер «Пока функция доступна ограниченному кругу пользователей». После полного включения кнопка выглядит так же, без пометки и баннера.

### Бот не появился в моём Битрикс24

Бот-компаньон регистрируется сам, на шаге 1. Если бота нет, один из шагов активации не прошёл: выпуск ключа администратора, установка приложения, регистрация бота. Администратор может нажать «Подключить к Вайбкоду» повторно — повторное нажатие проходит только те шаги, которые не удались.

## Безопасность

- **Карточка инициатора в боте — защитный механизм**, а не оформление. Бот показывает имя и почту того пользователя Вайбкод, который запросил привязку. Не узнаёте его — нажмите «Нет, это не я», и ключ разработчика не будет выписан.
- **Код подтверждения действует 10 минут** и он одноразовый: после подтверждения он аннулируется. Перехват ссылки бесполезен через 10 минут или после первого подтверждения.
- **Ключ разработчика хранится зашифрованным.** В ответах API возвращается только подсказка — последние 4 символа. Сам ключ не отдаётся ни одному клиенту.
- **Защита от запросов во внутреннюю сеть (SSRF).** Адреса вида `localhost`, `127.0.0.1` и записанные числами адреса отклоняются уже при вводе. Имя, которое ведёт во внутреннюю сеть, отсекается на следующем шаге — при исходящем вызове, до обращения к порталу.

## После подключения

Подключённый коробочный Битрикс24 работает так же, как облачный:

- Создавайте ключи API в разделе [Ключи API](/keys) — они работают через те же эндпоинты `/v1/*`
- Создавайте OAuth-приложения в разделе [Ключи авторизации](/apps) — пользователи получают свой ключ разработчика автоматически, тем же подтверждением в боте
- Запускайте AI-агентов и AI Router — доступны те же модели
- Пользуйтесь веб-поиском и аналитикой. Расход списывается из кошелька Битрикс24 так же, как у облачного

Чем коробка отличается от облака:

- **На коробке скоупы ключа проверяет и Битрикс24.** Платформа сверяет скоуп до вызова и отвечает `403 SCOPE_DENIED` — одинаково для коробочного и облачного Битрикс24. Сверх этого на коробке набор скоупов записывается в сам вебхук при выпуске ключа, поэтому вызов вне скоупа отклонит и Битрикс24, кодом `BITRIX_ACCESS_DENIED`. Обрабатывайте оба — подробности в [Ошибках](./errors.md).
- **Платная лицензия коробки сама по себе доступа к Вайбкод не даёт.** Без действующей подписки Маркетплейса коробочный Битрикс24 не отдаёт ключ: установка приложения и выпуск ключа отвечают `403`. В подписочном регионе — Россия и Беларусь — приходит код `B24_MARKET_SUBSCRIPTION_REQUIRED`, понятное сообщение и ссылка на оформление в `error.details.upgradeUrl`. Имя подписки зависит от региона: в России это «BitrixGPT + Маркетплейс», в Беларуси — «Битрикс24 Маркет Плюс». Коробка, у которой регион лицензии не определился, получает `403 INT_TARIFF_REQUIRED` без ссылки: оформить подписку там негде. На `.com` инфраструктура и выпуск ключей дополнительно требуют тарифа Vibe+ (`INT_VIBE_PLUS_REQUIRED`). Полный разбор подписочных отказов — в [Ошибках](./errors.md).
- **Признак `wasEverCommercial` не односторонний.** В ответе [GET /v1/me](/docs/keys-auth/me) у коробочного Битрикс24, за которым не нашлось ни подписки, ни платежей, значение однократно меняется с `true` на `false`. Коробка, у которой регион лицензии не определён, признак сохраняет. Не полагайтесь на его монотонность.
- **Несколько пользователей одного Битрикс24** — каждый проходит шаг 2 сам и получает свой личный ключ разработчика. Учётные записи независимые: отзыв одного ключа не затрагивает остальные.

## Если что-то пошло не так

Откройте раздел [Обратная связь](/feedback) в кабинете Вайбкод или напишите в поддержку. В заявке укажите:

- Адрес Битрикс24 — например, `mybox.example.com`
- На каком состоянии мастера остановилось подключение
- Текст ошибки и её код, если мастер их показал
- Время попытки

С этими данными мы найдём ваш запрос в журнале аудита.

## Что дальше

- [Быстрый старт](./quickstart.md) — создайте первый ключ и попробуйте API
- [Ключи и авторизация](./keys-auth.md) — типы ключей, скоупы, лимиты
- [Entity API](./entity-api.md) — CRUD по сущностям Битрикс24
- [Бот-платформа](./bots.md) — создание чат-ботов на платформе Вайбкод