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

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

GET /v1/placements

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

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

Примеры

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

Terminal 
curl https://vibecode.bitrix24.tech/v1/placements \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/placements', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log('Подтверждено аккаунтом:', data.handlers)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.placements string[] Коды мест встраивания, привязанных приложением
data.appId string Идентификатор приложения. Список приложений — GET /v1/apps
data.appTitle string Название приложения
data.handlers array Данные обработчиков, полученные от аккаунта. Поле необязательное — приходит только вместе с токеном сессии
data.handlers[].placement string Код места встраивания
data.handlers[].handler string Адрес обработчика, зарегистрированный на аккаунте
data.handlers[].misbound boolean true, когда обработчик зарегистрирован на технический адрес сервера приложения. Такое место не пройдёт авторизацию внутри Битрикс24
data.handlers[].title string Подпись места на аккаунте
data.handlers[].options array | object Настройки места. Пустой массив, когда настроек нет
data.handlers[].langAll object Подписи места по языкам. Ключ — код языка, значения — TITLE, DESCRIPTION, GROUP_NAME
warnings string[] Появляется, когда хотя бы у одного места misbound равен true

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

Токен сессии передан, аккаунт подтвердил вкладку в карточке сделки:

JSON 
{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU", "CRM_DEAL_DETAIL_TAB"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Дашборд продаж",
    "handlers": [
      {
        "placement": "CRM_DEAL_DETAIL_TAB",
        "handler": "https://example.com/tab",
        "misbound": false,
        "title": "Документы по сделке",
        "options": [],
        "langAll": {
          "en": { "TITLE": "Документы по сделке", "DESCRIPTION": "", "GROUP_NAME": "" },
          "ru": { "TITLE": "Документы по сделке", "DESCRIPTION": "", "GROUP_NAME": "" }
        }
      }
    ]
  }
}

Аккаунт не вернул ни одного из привязанных кодов — handlers приходит пустым:

JSON 
{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Дашборд продаж",
    "handlers": []
  }
}

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

400 — запрос выполнен личным ключом:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_APP_REQUIRED",
    "message": "Placement management is only available for OAuth app keys"
  }
}

Ошибки

HTTP Код Описание
400 OAUTH_APP_REQUIRED Запрос выполнен личным ключом vibe_api_
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный ключ
404 APP_NOT_FOUND К ключу не привязано приложение

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

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

  • Пустой handlers при непустом placements — признак расхождения. Место числится привязанным в Вайбкод, но аккаунт его не вернул: на стороне Битрикс24 такого места нет. Восстанавливается повторным вызовом Привязать место.
  • Поле handlers может отсутствовать и при переданном токене сессии — когда у приложения нет привязанных мест или ответ от аккаунта получить не удалось. Отсутствие поля не означает, что мест нет — сверьтесь по data.placements.
  • Место с misbound равным true чинится повторной привязкой. Вызов Привязать место подставит платформенный адрес обработчика вместо технического адреса сервера приложения.

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