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

POST /v1/placements/bind

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

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

Поля запроса (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"
  }
}

Ошибки

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

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

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

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

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