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

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

GET /v1/onec/instances

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

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

Примеры

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

Terminal 
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, POST /v1/onec/tools/{method}/call и GET /v1/onec/operations/{operationId}
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 — Ошибки.

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

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

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

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

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

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