## Привязать место встраивания

`POST /v1/placements/bind`

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

Предусловия вызова — [что нужно до привязки](/docs/apps#места-встраивания).

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `placement` | string | да | Код места встраивания. Перечень кодов, доступных аккаунту — [Доступные места](/docs/apps/placements/available) |
| `handler` | string | да | Абсолютный адрес страницы приложения, которая откроется в этом месте |
| `title` | string | да | Подпись места в интерфейсе аккаунта, от 1 до 255 символов |
| `options` | object | нет | Настройки места встраивания. Кроме перечисленных ниже полей принимаются любые другие — например `context`, `role`, `extranet` у места `IM_CONTEXT_MENU`. Значение каждого поля — строка, число или логическое значение, вложенные объекты и массивы не принимаются |
| `options.iconName` | string | нет | Имя значка, от 1 до 255 символов. Требуется местам `IM_SIDEBAR`, `IM_NAVIGATION`, `IM_TEXTAREA` — без него Битрикс24 отклоняет привязку. Месту `IM_CONTEXT_MENU` значок не нужен |
| `options.errorHandlerUrl` | string | нет | Адрес страницы ошибки для места `PAGE_BACKGROUND_WORKER`. Если поле не передано, платформа подставляет действующий адрес обработчика |
| `options.iconSvg` | string | нет | Значок в формате SVG, до 10 000 символов |
| `options.width` | number | нет | Ширина области встраивания. Целое положительное число |
| `options.height` | number | нет | Высота области встраивания. Целое положительное число |
| `options.color` | string | нет | Имя цвета из палитры чата Битрикс24 — например `AZURE`, `GREEN`, `PURPLE`. Не шестнадцатеричный код, до 64 символов |

## Примеры

### curl — OAuth-приложение

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/placements/bind \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "placement": "CRM_DEAL_DETAIL_TAB",
    "handler": "https://example.com/deal-tab",
    "title": "Аналитика по сделке"
  }'
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/placements/bind', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    placement: 'CRM_DEAL_DETAIL_TAB',
    handler: 'https://example.com/deal-tab',
    title: 'Аналитика по сделке',
  }),
})

const { data } = await res.json()
console.log('Зарегистрированный адрес обработчика:', data.handler)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешной привязке |
| `data.placement` | string | Код привязанного места встраивания |
| `data.handler` | string | Адрес обработчика, зарегистрированный на аккаунте |
| `data.title` | string | Подпись места в интерфейсе аккаунта |
| `data.options` | object | Действующий набор настроек места. Приходит, когда настройки переданы в запросе или подставлены платформой |
| `data.alreadyBound` | boolean | `true`, когда место уже числилось привязанным и регистрация выполнена заново |
| `data.handlerRewritten` | boolean | `true`, когда переданный адрес обработчика заменён на платформенный |
| `data.requestedHandler` | string | Адрес обработчика из запроса. Приходит вместе с `handlerRewritten` |

## Пример ответа

Переданный адрес обработчика заменён на платформенный:

```json
{
  "success": true,
  "data": {
    "placement": "CRM_DEAL_DETAIL_TAB",
    "handler": "https://vibecode.bitrix24.tech/v1/bitrix-handler",
    "title": "Аналитика по сделке",
    "requestedHandler": "https://app-a1b2c3d4.vibecode.bitrix24.tech/deal-tab",
    "handlerRewritten": true
  }
}
```

Повторная привязка того же кода:

```json
{
  "success": true,
  "data": {
    "placement": "CRM_DEAL_DETAIL_TAB",
    "handler": "https://example.com/deal-tab",
    "title": "Сделка: сводка",
    "alreadyBound": true
  }
}
```

Привязка места `PAGE_BACKGROUND_WORKER` без `options` — платформа подставила адрес страницы ошибки:

```json
{
  "success": true,
  "data": {
    "placement": "PAGE_BACKGROUND_WORKER",
    "handler": "https://example.com/worker",
    "title": "Фоновый сценарий",
    "options": {
      "errorHandlerUrl": "https://example.com/worker"
    }
  }
}
```

## Пример ответа при ошибке

400 — в теле запроса нет обязательного поля:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Required"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `OAUTH_APP_REQUIRED` | Вызов сделан личным ключом. Привязка работает только с ключом авторизации приложения |
| 400 | `VALIDATION_ERROR` | Тело запроса не прошло проверку — пропущено обязательное поле или код места не входит в перечень допустимых |
| 400 | `PLATFORM_HANDLER_UNRESOLVABLE` | Переданный адрес указывает на технический адрес сервера приложения, а платформенный обработчик определить не удалось. Место не зарегистрировано |
| 400 | `APP_NOT_REGISTERED` | У приложения нет идентификатора приложения Битрикс24 |
| 400 | `BOX_NO_DEVELOPER_KEY` | У автора приложения не настроен ключ разработчика |
| 401 | `SESSION_REQUIRED` | Не передан заголовок `Authorization: Bearer` с токеном сессии |
| 403 | `PLACEMENT_SCOPE_MISSING` | У ключа нет скоупа `placement` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только чтения. Переключите его на чтение и запись |
| 403 | `SESSION_REQUIRES_ADMIN` | Ключ разработчика принадлежит пользователю без прав администратора аккаунта |
| 403 | `B24_MARKET_SUBSCRIPTION_REQUIRED` | Нужна активная подписка BitrixGPT + Маркетплейс |
| 403 | `B24_MARKET_TRIAL_USED` | Пробный период подписки BitrixGPT + Маркетплейс уже использован — нужна платная подписка |
| 403 | `INT_TARIFF_REQUIRED` | Нужен коммерческий тариф Битрикс24 |
| 404 | `APP_NOT_FOUND` | К ключу не привязано приложение |
| 413 | `FST_ERR_CTP_BODY_TOO_LARGE` | Тело отправлено не как JSON и длиннее одного байта. Укажите заголовок `Content-Type: application/json` |
| 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | Тело отправлено не как JSON и равно одному байту — та же причина, другая ветка проверки |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 отклонил регистрацию места. Код и статус ответа Битрикс24 приходят в `details` |
| 503 | `NETWORK_DEVKEY_REQUIRED` | Ключ разработчика для автора приложения ещё не выдан |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- **Повторная привязка перерегистрирует место.** Вызов для уже привязанного кода не отклоняется: платформа снимает прежнюю регистрацию и привязывает место заново, поэтому новые адрес обработчика и подпись вступают в силу. Это единственный способ изменить подпись уже привязанного места.
- **Технический адрес сервера приложения заменяется платформенным.** Если `handler` указывает на технический адрес сервера приложения, на аккаунте регистрируется платформенный обработчик приложения. Внешние адреса регистрируются без изменений.
- **Битрикс24 дополняет `options` своими значениями.** Для виджетов чата аккаунт хранит рядом с переданными настройками собственные — область показа, роль и признак экстранета. Они приходят в [привязанных местах](/docs/apps/placements/list) даже тогда, когда вы их не передавали.
- **Подпись одна для всех языков интерфейса.** Значение `title` уходит на аккаунт единственной подписью, отдельный перевод этим вызовом не задаётся. В [привязанных местах](/docs/apps/placements/list) поле `langAll` возвращает эту же подпись для каждого языка.

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

- [Места встраивания](/docs/apps/placements)
- [Доступные места](/docs/apps/placements/available)
- [Привязанные места](/docs/apps/placements/list)
- [Отвязать место](/docs/apps/placements/unbind)
- [Данные ключа](/docs/keys-auth/me)
- [Приложения](/docs/apps)