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

Каталог инструментов 1С

GET /v1/onec/tools

Возвращает инструменты, которые опубликовал модуль Вайбкод в 1С, и состояние их версии. Каждый инструмент несёт свой метод, название, описание и схему параметров, с которой его можно запросить.

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

Параметры

Параметр Тип Обяз. Описание
ПараметрinstanceId (query) Типstring Обяз.нет ОписаниеИдентификатор базы 1С в формате UUID. Список: GET /v1/onec/instances. Обязателен, когда к порталу подключено или уже подключалось несколько баз, — в том числе на время перевыпуска ключа одной из них. При одной базе можно не передавать

Примеры

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

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

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

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

const { data } = await res.json()
for (const tool of data.tools) {
  console.log(tool.method, tool.title)
}

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.loaded Типboolean ОписаниеКаталог загружен и применён. false — модуль ещё не присылал свой список инструментов
Полеdata.revision Типstring | null ОписаниеВерсия содержимого каталога: значение, объявленное модулем, либо отпечаток sha256:…, если модуль его не объявил
Полеdata.updatedAt Типstring | null ОписаниеКогда применён текущий каталог, ISO 8601. null при loaded: false
Полеdata.stale Типboolean ОписаниеМодуль объявил версию, отличную от применённой — каталог обновляется
Полеdata.advertisedVersion Типstring | null ОписаниеПоследняя версия, объявленная модулем
Полеdata.appliedVersion Типstring | null ОписаниеВерсия, зафиксированная применённым каталогом
Полеdata.tools Типarray ОписаниеИнструменты каталога. Пустой массив при loaded: false
Полеdata.tools[].method Типstring ОписаниеИдентификатор инструмента для POST /v1/onec/tools/{method}/call
Полеdata.tools[].title Типstring ОписаниеНазвание инструмента для отображения
Полеdata.tools[].description Типstring ОписаниеОписание инструмента. Пустая строка, когда модуль описания не дал
Полеdata.tools[].inputSchema Типobject ОписаниеСхема JSON для полей запроса вызова: columns, filters, limit, offset

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

Каталог загружен, модуль объявил новую версию — она применяется:

JSON 
{
  "success": true,
  "data": {
    "loaded": true,
    "revision": "18",
    "updatedAt": "2026-09-08T12:00:00.000Z",
    "stale": true,
    "advertisedVersion": "19",
    "appliedVersion": "18",
    "tools": [
      {
        "method": "bank.list",
        "title": "Банки",
        "description": "Список банков",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "columns": {
              "type": "array",
              "items": { "type": "string", "enum": ["Код"], "oneOf": [{ "const": "Код", "description": "Код" }] },
              "maxItems": 200,
              "uniqueItems": true
            },
            "filters": {
              "type": "object",
              "additionalProperties": false,
              "maxProperties": 50,
              "properties": {
                "Контекст": {
                  "type": "object",
                  "additionalProperties": false,
                  "maxProperties": 50,
                  "properties": { "Код": { "type": "string", "maxLength": 1024 } }
                }
              }
            },
            "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000 },
            "offset": { "type": "integer", "minimum": 0, "default": 0 }
          }
        }
      }
    ]
  }
}

1С ещё не присылала свой список инструментов:

JSON 
{
  "success": true,
  "data": {
    "loaded": false,
    "revision": null,
    "updatedAt": null,
    "stale": false,
    "advertisedVersion": null,
    "appliedVersion": null,
    "tools": []
  }
}

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

404 — на портале нет активного подключения 1С:

JSON 
{
  "success": false,
  "error": {
    "code": "ONEC_NOT_CONNECTED",
    "message": "There is no 1C connection."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодONEC_INSTANCE_REQUIRED ОписаниеК порталу подключено или уже подключалось несколько баз 1С, а instanceId не передан
HTTP404 КодONEC_NOT_CONNECTED ОписаниеНа портале нет активного подключения 1С либо оно отключено
HTTP404 КодONEC_NOT_CONNECTED ОписаниеБазы с переданным instanceId на портале нет, она отключена, её ключ подключения перевыпущен и модуль Вайбкод ещё не подключился с новым ключом, либо значение не в формате UUID
HTTP404 КодROUTE_NOT_FOUND ОписаниеИнтеграция 1С на портале недоступна — ответ совпадает с ответом на неизвестный путь
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа vibe:onec
HTTP403 КодONEC_USER_NOT_MAPPED ОписаниеУ владельца ключа нет доступа к этой базе 1С: нет действующего сопоставления или назначения через подразделение, учётная запись 1С неактивна либо пользователь больше не состоит в портале
HTTP403 КодONEC_USER_NOT_MAPPED ОписаниеВызов ключом авторизации vibe_app_…: доступ к 1С выдаётся сотруднику, а не приложению, поэтому раздел работает только с личным ключом
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов — повторите после времени из заголовка Retry-After
HTTP503 КодONEC_DIRECTORY_UNAVAILABLE ОписаниеСостав подразделений Битрикс24 проверить не удалось, каталог не отдан. Повторите после времени из заголовка Retry-After — это не отказ в доступе
HTTP503 КодONEC_ASSIGNMENTS_DISABLED ОписаниеНазначения пользователей 1С на портале временно выключены, каталог не отдан
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа удаляет свою учётную запись на портале. Заголовок Retry-After равен 604800 — столько длится отсрочка удаления

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

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

Пустой каталог — это ответ, а не отказ. Инструменты в такой ответ не домысливаются, поэтому вызывать по угаданному методу нечего — дождитесь непустого каталога.

stale: true не мешает работать. Пока обновление не завершилось, каталог отдаёт последний применённый список, и вызовы по его методам принимаются.

Схема inputSchema — источник допустимых columns и filters. Список колонок лежит в properties.columns.items.enum, состав фильтров — в properties.filters.properties. Инструмент может не иметь ни выбираемых колонок, ни фильтров: тогда columns приходит с maxItems: 0, а filters.properties пустой.

Имя метода приходит как его объявила 1С — включая кириллицу и регистр. Как кодировать его в URL, описано на странице запроса данных.

Каталог не заказывается запросом. Этот вызов читает уже применённый список, а его обновлением управляет 1С.

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