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

`GET /v1/placements`

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

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

## Примеры

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

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

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

- **Пустой `handlers` при непустом `placements` — признак расхождения.** Место числится привязанным в Вайбкод, но аккаунт его не вернул: на стороне Битрикс24 такого места нет. Восстанавливается повторным вызовом [Привязать место](/docs/apps/placements/bind).
- **Поле `handlers` может отсутствовать и при переданном токене сессии** — когда у приложения нет привязанных мест или ответ от аккаунта получить не удалось. Отсутствие поля не означает, что мест нет — сверьтесь по `data.placements`.
- **Место с `misbound` равным `true` чинится повторной привязкой.** Вызов [Привязать место](/docs/apps/placements/bind) подставит платформенный адрес обработчика вместо технического адреса сервера приложения.

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

- [Места встраивания](/docs/apps/placements)
- [Доступные места](/docs/apps/placements/available)
- [Привязать место](/docs/apps/placements/bind)
- [Отвязать место](/docs/apps/placements/unbind)
- [Приложения](/docs/apps)
- [Данные ключа](/docs/keys-auth/me)