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

`GET /v1/placements/available`

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

Предусловия вызова — [что нужно до привязки](/docs/apps#места-встраивания).

## Примеры

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

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

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

```bash
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 — [Ошибки](/docs/errors).

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

- **`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`. Числовая часть зависит от аккаунта, поэтому такие коды перечислить заранее нельзя.
- **Код из справочника ещё не означает, что место откроется на аккаунте.** Аккаунт отдаёт приложению только те места, права на которые у приложения есть, — см. [что нужно до привязки](/docs/apps#места-встраивания).

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

- [Места встраивания](/docs/apps/placements)
- [Привязанные места](/docs/apps/placements/list)
- [Привязать место](/docs/apps/placements/bind)
- [Отвязать место](/docs/apps/placements/unbind)
- [Скоупы](/docs/scopes)