Места встраивания

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

Скоуп: placement | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key (ключ авторизации приложения)

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

GET /v1/placements

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

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

Примеры

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

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

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

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)

Поля ответа

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

Токен сессии передан, аккаунт вернул оба привязанных кода — portalSync равен ok:

{
  "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": "" }
        }
      },
      {
        "placement": "LEFT_MENU",
        "handler": "https://example.com/menu",
        "misbound": false,
        "title": "Дашборд продаж",
        "options": [],
        "langAll": {}
      }
    ],
    "portalSync": "ok"
  }
}

Аккаунт не вернул привязанный код — расхождение, код назван в missingOnPortal:

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

Токен сессии не передан — сверки не было, handlers отсутствует:

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

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

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

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

Ошибки

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

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

• Расхождение определяется по portalSync, а не по наличию или длине handlers. Отсутствие поля handlers и пустой массив handlers — разные состояния. Пустой массив приходит, когда ответ аккаунта получен и ни одного привязанного кода в нём нет. Отсутствие поля означает, что ответ аккаунта не читался. Вердикт в обоих случаях берите из portalSync, а не из массива: у снятого с каталога приложения пустой handlers приходит вместе с unknown, а не с drift.
• unknown не равнозначно ok. Значение говорит, что привязка не подтверждена, и распадается на два случая. Аккаунт не читался — причины no_oauth_session, empty_vibe_list, b24_unreachable, поля handlers в ответе нет. Аккаунт прочитан, но его состояние не сопоставляется с нашим списком — причина unpublished, и тогда handlers в ответе есть.
• Снятое с каталога приложение расхождением не считается. При unpublished вердикт подавлен: снятые места — ожидаемое следствие операции. Аккаунт при этом всё равно опрашивается, потому что снятие с публикации не гарантирует, что все места действительно ушли, — поэтому handlers и признак misbound в ответе остаются. Что остаётся в placements после снятия и как убрать остаток, разобрано на странице самой операции.
• Расхождение восстанавливается повторной привязкой. Коды из missingOnPortal возвращаются на аккаунт вызовом Привязать место.
• Коды, которых нет в data.placements, расхождением не считаются. Аккаунт может держать места других приложений, и на portalSync это не влияет.
• Место с misbound равным true — отдельное состояние, не расхождение. Аккаунт такое место вернул, поэтому в missingOnPortal он не попадает, а portalSync остаётся ok — либо unknown с причиной unpublished, если приложение снято с каталога. Вызов Привязать место подставит платформенный адрес обработчика вместо технического адреса сервера приложения.

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

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