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

Запросить данные из 1С

POST /v1/onec/tools/{method}/call

Ставит в очередь чтение данных инструментом из каталога 1С. Ответ приходит сразу и несёт идентификатор операции, а сами данные забираются отдельным запросом, когда 1С выполнит чтение.

Учётную запись 1С, от имени которой пойдёт чтение, выбирает платформа по сопоставлению вызывающего. Передать или подменить её в запросе нельзя.

Параметры

Параметр Тип Обяз. Описание
method (path) string да Метод инструмента из каталога. Буквы, знаки, цифры и ._-, до 100 символов. В URL кодируется, само значение сохраняется посимвольно

Поля запроса (body)

Поле Тип Обяз. По умолч. Описание
columns array нет — Колонки из inputSchema.properties.columns.items.enum инструмента, до 200 без повторов. Опущено — вернутся все колонки, доступные учётной записи 1С
filters object нет — Фильтры из inputSchema.properties.filters.properties инструмента. До 50 ключей на объект, до 200 элементов в массиве, до 1024 символов в строке, вложенность до 6 уровней и до 2000 значений суммарно
limit integer нет 1000 Сколько строк прочитать за операцию, от 1 до 10 000
offset integer нет 0 Сколько строк пропустить. Для следующей страницы берите nextOffset из результата операции

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/onec/tools/bank.list/call \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": ["Код", "Наименование"],
    "filters": { "Наименование": "Банк" },
    "limit": 100,
    "offset": 0
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/onec/tools/bank.list/call \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": ["Код", "Наименование"],
    "filters": { "Наименование": "Банк" },
    "limit": 100,
    "offset": 0
  }'

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

javascript 
const method = encodeURIComponent('bank.list')

const res = await fetch(`https://vibecode.bitrix24.tech/v1/onec/tools/${method}/call`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    columns: ['Код', 'Наименование'],
    filters: { Наименование: 'Банк' },
    limit: 100,
    offset: 0,
  }),
})

const { data } = await res.json()
console.log(data.operationId, res.headers.get('Location'))

JavaScript — OAuth-приложение

javascript 
const method = encodeURIComponent('bank.list')

const res = await fetch(`https://vibecode.bitrix24.tech/v1/onec/tools/${method}/call`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    columns: ['Код', 'Наименование'],
    filters: { Наименование: 'Банк' },
    limit: 100,
    offset: 0,
  }),
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.operationId string Идентификатор операции для GET /v1/onec/operations/{operationId}
data.status string Состояние операции сразу после постановки — pending
data.expiresAt string До какого момента операция ждёт выполнения, ISO 8601. После него операция читается со статусом expired

Заголовок ответа Location несёт адрес чтения этой же операции — то же значение, что data.operationId в пути.

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

Статус ответа — 202 Accepted:

JSON 
{
  "success": true,
  "data": {
    "operationId": "cl9x2k4t70000qz8h3m1vb7ry",
    "status": "pending",
    "expiresAt": "2026-09-14T12:15:00.000Z"
  }
}

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

403 — у вызывающего нет активного сопоставления с учётной записью 1С:

JSON 
{
  "success": false,
  "error": {
    "code": "ONEC_USER_NOT_MAPPED",
    "message": "The caller has no active 1C user mapping."
  }
}

Ошибки

HTTP Код Описание
400 ONEC_VALIDATION Метод содержит символы вне букв, знаков, цифр и ._-
400 ONEC_VALIDATION В теле есть поле вне columns, filters, limit, offset
400 ONEC_VALIDATION limit вне диапазона 1–10 000 или offset отрицательный
400 ONEC_VALIDATION columns не массив строк, содержит повторы или длиннее 200 элементов
400 ONEC_VALIDATION filters превышает ограничение по числу ключей, длине строки, вложенности или числу значений
403 ONEC_USER_NOT_MAPPED У вызывающего нет действующего сопоставления с учётной записью 1С
403 ONEC_ACCOUNT_UNAVAILABLE Выбранная учётная запись 1С или её назначение неактивны
404 ONEC_NOT_CONNECTED На портале нет активного подключения 1С либо оно отключено
409 ONEC_SETTINGS_MISSING Модуль Вайбкод в 1С ещё не передал свои настройки
409 ONEC_CAPABILITY_MISSING Модуль не объявил чтение данных среди своих возможностей
409 ONEC_MAPPING_CONFLICT Назначения по подразделениям выбирают разные учётные записи 1С
409 ONEC_MAPPING_VERSION_CONFLICT Назначения изменились во время проверки доступа — повторите вызов
503 ONEC_DIRECTORY_UNAVAILABLE Состав подразделений Битрикс24 проверить не удалось. Операция не создана, повторите позже — это не отказ в доступе
503 ONEC_ASSIGNMENTS_DISABLED Назначения пользователей 1С на портале временно выключены. Операция не создана
404 ROUTE_NOT_FOUND Интеграция 1С на портале недоступна — ответ совпадает с ответом на неизвестный путь
404 ROUTE_NOT_FOUND Метод в URL длиннее 100 символов
403 SCOPE_DENIED Ключу не хватает скоупа vibe:onec
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение» операции не создаёт
401 MISSING_API_KEY Не передан заголовок X-Api-Key
429 RATE_LIMITED Превышен лимит запросов — повторите после времени из заголовка Retry-After
503 user_self_deletion_pending Владелец ключа удаляет свою учётную запись на портале. Заголовок Retry-After равен 604800 — столько длится отсрочка удаления

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

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

Вызов только ставит задачу. 202 означает, что операция принята, а не что данные прочитаны — результат забирается через GET /v1/onec/operations/{operationId}.

Каждый вызов создаёт новую операцию. Повтор с тем же телом не возвращает прежнюю операцию и не отменяет её, а ставит ещё одну. Для повторного чтения той же выборки храните operationId из первого ответа.

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

Значение фильтра интерпретирует 1С. Платформа проверяет только ограничения и передаёт объект как есть, а равенство это или вхождение части строки — решает модуль в 1С.

Фильтр, которого инструмент не объявлял, роняет операцию. Такой вызов принимается с 202, а 1С завершает операцию статусом failed и присылает в поле error код UNKNOWN_FILTER.

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