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

Доступные места

GET /v1/placements/available

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

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

Примеры

curl — личный ключ

Terminal 
curl https://vibecode.bitrix24.tech/v1/placements/available \
  -H "X-Api-Key: YOUR_API_KEY"

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

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

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/placements/available', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Группы:', Object.keys(data.groups))
console.log('Вкладки карточек CRM:', data.groups['CRM Detail Tabs'].map(p => p.code))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/placements/available', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log('Всего кодов, принимаемых при привязке:', data.total)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.groups object Группы мест встраивания. Ключ — название группы, значение — массив кодов этой группы
data.groups[группа][].code string Код места встраивания. Это значение передаётся в placement при привязке
data.groups[группа][].title string Название кода словами
data.groups[группа][].description string Описание точки интерфейса, в которой откроется приложение
data.groups[группа][].module string Модуль Битрикс24, к которому относится код: crm, tasks, user, im, contact_center, main
data.total number Количество кодов, принимаемых при привязке

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

Показаны 3 группы из 12, остальные устроены так же.

JSON 
{
  "success": true,
  "data": {
    "groups": {
      "Menu": [
        {
          "code": "LEFT_MENU",
          "title": "Left Menu",
          "description": "Item in the portal left menu (the \"tab in menu\" placement most callers want)",
          "module": "main"
        }
      ],
      "Chat": [
        {
          "code": "IM_SIDEBAR",
          "title": "Im Sidebar",
          "description": "Chat sidebar panel embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_NAVIGATION",
          "title": "Im Navigation",
          "description": "Chat navigation tab embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_TEXTAREA",
          "title": "Im Textarea",
          "description": "Chat message-input button embed (requires options.iconName)",
          "module": "im"
        },
        {
          "code": "IM_CONTEXT_MENU",
          "title": "Im Context Menu",
          "description": "Chat message context-menu item embed (options: context, role, extranet)",
          "module": "im"
        }
      ],
      "Contact Center": [
        {
          "code": "CONTACT_CENTER",
          "title": "Contact Center",
          "description": "Tile in the Contact Center section (requires scope contact_center)",
          "module": "contact_center"
        }
      ]
    },
    "total": 55
  }
}

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

401 — не передан заголовок X-Api-Key:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный ключ

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

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

  • total больше, чем сумма длин групп. В проверенном ответе total равен 55, а во всех группах вместе — 44 кода. Это разные наборы: total считает более широкий перечень кодов, допустимых к привязке, чем показывают группы.
  • Коды смарт-процессов в справочник не попадают. Кроме перечисленных кодов привязка принимает коды вида CRM_DYNAMIC_<entityTypeId>_DETAIL_TAB и CRM_SMART_<entityTypeId>_DETAIL_TAB с окончаниями DETAIL_TAB, DETAIL_ACTIVITY, DETAIL_TOOLBAR, LIST_MENU, LIST_TOOLBAR, ACTIVITY_TIMELINE_MENU. Числовая часть зависит от аккаунта, поэтому такие коды перечислить заранее нельзя.
  • Код из справочника ещё не означает, что место откроется на аккаунте. Аккаунт отдаёт приложению только те места, права на которые у приложения есть, — см. что нужно до привязки.

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