# Места встраивания

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

**Скоуп:** `placement` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key` (ключ авторизации приложения)

## Операции

- [Привязанные места](./placements/list.md) — `GET /v1/placements`
- [Доступные места](./placements/available.md) — `GET /v1/placements/available`
- [Привязать место](./placements/bind.md) — `POST /v1/placements/bind`
- [Отвязать место](./placements/unbind.md) — `POST /v1/placements/unbind`

## Что нужно до привязки

**Ключ авторизации приложения.** Привязка, отвязка и список привязанных мест работают только с ключом `vibe_app_…`, личный ключ `vibe_api_…` возвращает на них `400 OAUTH_APP_REQUIRED`. Справочник [Доступные места](./placements/available.md) — исключение, он открыт любому действующему ключу. Как получить ключ приложения — [Ключи и авторизация](/docs/keys-auth).

**Скоуп `placement` у ключа.** Без него привязка и отвязка возвращают `403 PLACEMENT_SCOPE_MISSING`. Чтение списков этого скоупа не требует.

**Скоуп Битрикс24 под группу мест.** Аккаунт открывает приложению только те места, права на которые у приложения есть: места группы CRM требуют скоупа `crm`, чат — `im`, задачи — `task`, Контакт-центр — `contact_center`. Без нужного скоупа Битрикс24 отвечает, что место не найдено, и привязка возвращает `502 BITRIX_UNAVAILABLE`. Скоупы задаются при создании приложения и меняются [обновлением приложения](/docs/apps/update).

**Токен сессии на части аккаунтов.** Часть аккаунтов выполняет привязку и отвязку по одному ключу авторизации приложения, часть требует ещё и заголовок `Authorization: Bearer` с токеном сессии, без него отвечает `401 SESSION_REQUIRED`. Передавайте токен вместе с ключом — так вызов проходит в обоих случаях.

**Условие на стороне Битрикс24.** Привязка требует либо активной подписки BitrixGPT + Маркетплейс, либо коммерческого тарифа — что именно, зависит от аккаунта. Точное условие заранее отдаёт блок `placements.bindPrerequisite` в [данных ключа](/docs/keys-auth/me), там же перечислены коды, которыми привязка ответит при невыполненном условии.

## Группы мест встраивания

| Группа | Где появляется приложение |
|--------|---------------------------|
| CRM Lists | Меню на страницах списков лидов, контактов, компаний, сделок, предложений, счетов |
| CRM List Toolbars | Панель кнопок на тех же страницах списков |
| CRM Detail Tabs | Вкладка в карточке элемента CRM |
| CRM Detail Toolbars | Пункт выпадающего меню в панели карточки |
| CRM Detail Activity | Кнопка дела в карточке |
| CRM Activity Timeline | Действие в меню таймлайна |
| Tasks | Контекстное меню списка задач |
| User Profile | Меню и панель кнопок в профиле сотрудника |
| Menu | Пункт левого меню аккаунта |
| Universal | Обработчик ссылок и фоновый сценарий на каждой странице |
| Chat | Панель, вкладка навигации, кнопка поля ввода и пункт контекстного меню сообщения в чате |
| Contact Center | Плитка в разделе «Контакт-центр» |

Справочник одинаков для всех аккаунтов и пополняется со временем, поэтому перечень кодов берите живым вызовом [Доступные места](./placements/available.md), а не фиксируйте в коде. От аккаунта зависит другое — откроет ли Битрикс24 приложению конкретное место, это решают выданные приложению скоупы.

## Типовой сценарий

Приложение добавляет вкладку в карточку сделки.

1. `GET /v1/placements/available` — найти код нужного места, для вкладки в карточке сделки это `CRM_DEAL_DETAIL_TAB`.
2. `POST /v1/placements/bind` с телом `{ placement, handler, title }` — значение `title` станет подписью вкладки на аккаунте.
3. `GET /v1/placements` с токеном сессии — убедиться, что место числится привязанным и адрес обработчика совпадает с ожидаемым.
4. `POST /v1/placements/unbind` — убрать вкладку, когда возможность больше не нужна.

## Смотрите также

- [Приложения](/docs/apps)
- [Публикация приложения](/docs/apps/publish)
- [Данные ключа](/docs/keys-auth/me)
- [Скоупы](/docs/scopes)
- [Работа приложения внутри аккаунта](/docs/infra/app-runtime)