## Список баз 1С портала

`GET /v1/onec/instances`

Возвращает базы 1С, подключённые к порталу, и идентификатор каждой из них для выбора базы в остальных эндпоинтах интеграции. Нужен, когда к порталу подключено несколько баз и вызов обязан назвать нужную.

Список отдаётся только тому, у кого есть доступ к 1С на портале: сопоставление с учётной записью 1С или назначение через подразделение хотя бы в одной базе. Пустой список доступа не требует. Ключ в режиме «только чтение» обслуживается.

## Примеры

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

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

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/onec/instances', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
for (const base of data.instances) {
  console.log(base.instanceId, base.name, base.status)
}
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.instances` | array | Базы 1С портала. Пустой массив, когда ни одна база ещё не подключилась |
| `data.instances[].instanceId` | string | Идентификатор базы в формате UUID — значение параметра `instanceId` для [`GET /v1/onec/tools`](/docs/onec/tools), [`POST /v1/onec/tools/{method}/call`](/docs/onec/call) и [`GET /v1/onec/operations/{operationId}`](/docs/onec/operation) |
| `data.instances[].name` | string \| null | Название базы, которое модуль Вайбкод передал при подключении |
| `data.instances[].status` | string | Состояние подключения базы. `CONFIGURING` — модуль подключился, но ещё не передал настройки, `ONLINE` — база на связи, `OFFLINE` — база не отвечает. Отключённые базы в список не попадают |

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

К порталу подключены две базы:

```json
{
  "success": true,
  "data": {
    "instances": [
      {
        "instanceId": "3f2b8c1e-5d4a-4e7b-9c10-2a6f8d9e0b41",
        "name": "Бухгалтерия",
        "status": "ONLINE"
      },
      {
        "instanceId": "a71c09d2-8e3f-4b65-b2d8-6c4e1f7a9053",
        "name": "Склад",
        "status": "OFFLINE"
      }
    ]
  }
}
```

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

403 — ключу не хватает скоупа:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires the 'vibe:onec' scope."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 404 | `ROUTE_NOT_FOUND` | Интеграция 1С на портале недоступна — ответ совпадает с ответом на неизвестный путь |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `vibe:onec` |
| 403 | `ONEC_USER_NOT_MAPPED` | У владельца ключа нет доступа ни к одной базе 1С портала: нет действующего сопоставления или назначения через подразделение, учётная запись 1С неактивна либо пользователь больше не состоит в портале |
| 403 | `ONEC_USER_NOT_MAPPED` | Вызов ключом авторизации `vibe_app_…`, когда к порталу подключена хотя бы одна база: доступ к 1С выдаётся сотруднику, а не приложению, поэтому раздел работает только с личным ключом |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 429 | `RATE_LIMITED` | Превышен лимит запросов — повторите после времени из заголовка `Retry-After` |
| 503 | `ONEC_DIRECTORY_UNAVAILABLE` | Состав подразделений Битрикс24 проверить не удалось, список не отдан. Повторите после времени из заголовка `Retry-After` — это не отказ в доступе |
| 503 | `ONEC_ASSIGNMENTS_DISABLED` | Назначения пользователей 1С на портале временно выключены, список не отдан |
| 503 | `user_self_deletion_pending` | Владелец ключа удаляет свою учётную запись на портале. Заголовок `Retry-After` равен `604800` — столько длится отсрочка удаления |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

**`instanceId` можно не передавать, если выбирать не из чего.** Остальные эндпоинты интеграции выбирают базу сами, когда у портала одна база, которая подключена сейчас или подключалась раньше. Ключ подключения, выпущенный под новую базу и ещё не использованный, на выбор не влияет. Если таких баз две и больше, вызов без `instanceId` отвечает `400 ONEC_INSTANCE_REQUIRED` и операцию не создаёт. Это касается и базы, у которой перевыпущен ключ: до переподключения модуля её нет в списке, но при выборе она по-прежнему учитывается. Поэтому одна база в списке ещё не значит, что `instanceId` можно опустить. Передавайте `instanceId` из списка, и перевыпуск ключей соседних баз на вызовы не повлияет.

**Отключённая база пропадает из списка и отвечает как неизвестная.** Вызов с `instanceId` отключённой базы получает `404 ONEC_NOT_CONNECTED` — тот же ответ, что на идентификатор чужого портала.

**Перевыпуск ключа подключения не меняет `instanceId`.** Идентификатор задаёт сама база 1С, поэтому его можно хранить в настройках приложения. Пока модуль Вайбкод не подключился с новым ключом, базы нет в списке, а вызов с её `instanceId` отвечает `404 ONEC_NOT_CONNECTED`. После подключения база возвращается с прежним `instanceId`.

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

- [Каталог инструментов 1С](/docs/onec/tools)
- [Запросить данные из 1С](/docs/onec/call)
- [Получить результат операции 1С](/docs/onec/operation)
- [Интеграция 1С](/docs/onec)
- [Ключи и авторизация](/docs/keys-auth)
- [Ошибки](/docs/errors)