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

POST /v1/placements/bind

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

Предусловия вызова — что нужно до привязки.

На облачном аккаунте платформа сначала использует выбранный для него транспорт. Если ключ разработчика отклонён с HTTP 401 только из-за учётных данных и вместе с ключом приложения передан действующий Authorization: Bearer, привязка автоматически повторяется по OAuth. Явный код подписочного гейта остаётся окончательным при любом HTTP-статусе и никогда не повторяется по OAuth. Успешный ответ означает, что один из этих независимых каналов подтвердил запись.

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

Примеры

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

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-приложение

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": 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
  }
}

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

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

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

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

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

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

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

Ошибки

Поля `B24_ACCESS_DENIED`

Эти поля нужны для диагностики, а не для выбора клиентом следующего транспорта: платформа уже выполнила или отклонила OAuth fallback. Клиент ветвится по внешнему error.code; набор внутренних кодов Битрикс24 не является стабильным API-enum.

Полный список общих ошибок API — Ошибки.

Таблица ошибок сегментная: она описывает коды этой площадки. На международной площадке отказ доступа аккаунта выражается кодом INT_TARIFF_REQUIRED; переносить коды между площадками и строить по ним общий клиентский enum не следует.

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

• Место может требовать права у приложения Битрикс24, а не у ключа. Битрикс24 предлагает точку встраивания только приложениям, чьи права покрывают нужный модуль: вкладки задач требуют право задач, пункты профиля — право пользователей, и так далее. Требуемое право по каждому коду приходит в доступных местах полем requiredScope, а сводка гейтов — в самоописании ключа блоком placements.bindPrerequisite. Права приложения фиксируются при установке: изменить их у живого приложения нельзя, нужен перевыпуск ключа авторизации.
• Обязательные настройки места платформа подставляет сама. Значок чат-виджета и адрес страницы ошибки фонового обработчика подставляются, если вы их не передали. Список подставленных полей приходит в ответе полем optionsDefaulted.
• Повторная привязка перерегистрирует место. Вызов для уже привязанного кода не отклоняется: платформа снимает прежнюю регистрацию и привязывает место заново, поэтому новые адрес обработчика и подпись вступают в силу. Это единственный способ изменить подпись уже привязанного места.
• LEFT_MENU добавляет второй пункт меню. Приложение стоит в меню аккаунта с момента создания. Привязка LEFT_MENU добавляет к нему ещё один пункт со своим адресом, а не заменяет первый. Снять лишний пункт — отвязать код LEFT_MENU, пункт, появившийся при создании, при этом остаётся.
• HTTP 401 ключа разработчика, вызванный только учётными данными, не означает, что нужен другой тариф. Это отказ конкретного канала учётных данных. С действующей OAuth-сессией платформа пробует второй канал; без неё возвращает B24_ACCESS_DENIED, сохраняя машинный код и статус Битрикс24. Явные неавторизационные причины, включая подписочный гейт и нехватку прав, окончательны при любом HTTP-статусе и в OAuth fallback не попадают.
• Технический адрес сервера приложения заменяется платформенным. Если handler указывает на технический адрес сервера приложения, на аккаунте регистрируется платформенный обработчик приложения. Внешние адреса регистрируются без изменений.
• Битрикс24 дополняет options своими значениями. Для виджетов чата аккаунт хранит рядом с переданными настройками собственные — область показа, роль и признак экстранета. Они приходят в привязанных местах даже тогда, когда вы их не передавали.
• Подпись одна для всех языков интерфейса. Значение title уходит на аккаунт единственной подписью, отдельный перевод этим вызовом не задаётся. В привязанных местах поле langAll возвращает эту же подпись для каждого языка.
• Успешный ответ означает, что аккаунт принял запись, а не что она осталась на месте. Фактическое состояние аккаунта на любой момент после привязки проверяется полем portalSync в привязанных местах: ok — аккаунт вернул код, drift — код числится в Вайбкод и на аккаунте его нет.
• Одно место может занимать несколько приложений. Битрикс24 различает регистрации по приложению, поэтому привязка того же кода вторым приложением аккаунта не отклоняется и первую регистрацию не снимает. Общий адрес платформенного обработчика у разных приложений этому не мешает.

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

• Места встраивания
• Доступные места
• Привязанные места
• Отвязать место
• Самоописание ключа
• Приложения