Для AI-агентов: markdown этой страницы — /docs-content/apps/placements/unbind.md индекс документации — /llms.txt

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

POST /v1/placements/unbind

Убирает приложение из точки интерфейса Битрикс24, в которой оно было зарегистрировано, и снимает код этого места с приложения. Вызов безопасно повторять: код, который у приложения не числится привязанным, отвязка принимает как уже снятый.

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

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

Поле Тип Обяз. Описание
placement string да Код места встраивания. Привязанные к приложению коды — Привязанные места, полный перечень — Доступные места
handler string нет Адрес обработчика, регистрацию по которому нужно снять. Без этого поля снимаются все регистрации приложения на указанном месте

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/placements/unbind \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"placement": "CRM_DEAL_DETAIL_TAB"}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/placements/unbind', {
  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' }),
})
const { data } = await res.json()
if (data.alreadyUnbound) {
  console.log('Место уже не привязано к приложению')
}

Поля ответа

Поле Тип Описание
success boolean true при успешном выполнении
data.placement string Код места встраивания, по которому выполнена отвязка
data.alreadyUnbound boolean Присутствует со значением true, когда указанный код у приложения не числился привязанным

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

Отвязка привязанного места:

JSON 
{
  "success": true,
  "data": {
    "placement": "CRM_DEAL_DETAIL_TAB"
  }
}

Код места у приложения не привязан:

JSON 
{
  "success": true,
  "data": {
    "placement": "CRM_QUOTE_DETAIL_TAB",
    "alreadyUnbound": true
  }
}

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

400 — код места не опознан:

JSON 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "placement: Placement must be in VALID_PLACEMENTS or match the dynamic CRM pattern CRM_(DYNAMIC|SMART)_<entityTypeId>_(DETAIL_TAB|DETAIL_ACTIVITY|LIST_MENU|LIST_TOOLBAR|DETAIL_TOOLBAR|ACTIVITY_TIMELINE_MENU)"
  }
}

Ошибки

HTTP Код Описание
400 OAUTH_APP_REQUIRED Запрос выполнен личным ключом vibe_api_…. Отвязка доступна только ключу авторизации приложения
400 VALIDATION_ERROR Тело не прошло проверку: код места не опознан либо handler не является адресом
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 Ключ в режиме только чтения. Откройте путь из error.details.switchUrl: личный ключ ведёт на /keys, ключ приложения с карточкой — на /applications, самостоятельный OAuth-ключ — на /apps, management-ключ — на /management-keys. Там переключите режим на чтение и запись
404 APP_NOT_FOUND К ключу не привязано приложение
413 PAYLOAD_TOO_LARGE Тело отправлено не как JSON и длиннее одного байта. Укажите заголовок Content-Type: application/json
415 FST_ERR_CTP_INVALID_MEDIA_TYPE Тело отправлено не как JSON и равно одному байту — та же причина, другая ветка проверки
502 BITRIX_UNAVAILABLE Битрикс24 отклонил снятие регистрации. Место остаётся в списке приложения. После включения проверки тем же кодом отвечает неподтверждённое снятие на любом транспорте — см. врезку ниже

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

Отвязка идёт ОДНИМ транспортом, а не двумя. Платформа выбирает его сама по аккаунту и приложению: на коробочном аккаунте и на облачном, переведённом на ключ разработчика, — транспорт ключа разработчика, иначе — OAuth-транспорт приложения. Вызов никогда не ходит обоими сразу, поэтому «сняли одним, подтвердили другим» здесь не бывает.

Ожидание подтверждения сейчас раскатывается по аккаунтам, поэтому вариантов два:

  • Пока возможность не включена на аккаунте — неподтверждённый ответ не останавливает отвязку: место убирается из списка приложения, а запрос отвечает успехом. На аккаунте регистрация при этом может остаться.
  • После включения — неподтверждённый ответ отвечает 502 BITRIX_UNAVAILABLE и оставляет код в списке приложения, чтобы список не расходился с аккаунтом. Повторите запрос.

Проверка действует на всех трёх транспортах отвязки одинаково — на коробочном, на облачном с ключом разработчика и на OAuth-транспорте приложения. Подтверждением считается число снятых регистраций, которое называет Битрикс24; ответ без него подтверждением не является. Поэтому после включения успех этого запроса означает именно «Битрикс24 подтвердил снятие», а не «Битрикс24 принял вызов».

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

  • Передавайте в handler то же значение, что и при привязке. Адрес приводится к зарегистрированному обработчику по тем же правилам, что и при привязке, поэтому отвязка находит регистрацию и убирает место с аккаунта.

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