Интеграция 1С

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

Скоуп: vibe:onec | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Что нужно для работы | Как устроен обмен | Несколько баз 1С | Быстрый старт | Справочник эндпоинтов | Лимиты | Коды ошибок

Готовые сценарии: Сводка из 1С в чат Битрикс24 и Контрагенты из 1С в компании CRM.

Что нужно для работы

1. 1С подключена к порталу. Администратор портала устанавливает модуль интеграции в 1С, выпускает ключ подключения и подключает базу — в Коворке или в разделе «Интеграция 1С» кабинета. Порядок действий описан в статье Подключение 1С к Битрикс24. Пока платформа не включила интеграцию для портала, все эндпоинты раздела отвечают так же, как неизвестный путь.

2. Личный ключ vibe_api_… со скоупом vibe:onec. Скоуп выбирают при выпуске ключа в кабинете. Нужен именно личный ключ: доступ к 1С и операции привязаны к его владельцу. Ключ авторизации vibe_app_… получает 403 ONEC_USER_NOT_MAPPED, потому что доступ к 1С выдаётся сотруднику, а не приложению. Форматы ключей — Ключи и авторизация.

   Скоуп vibe:onec выдаётся, только если у владельца ключа уже есть доступ к 1С — его выдаёт администратор портала, см. пункт 3. Без доступа выпуск ключа с этим скоупом, добавление скоупа в существующий ключ и создание приложения с этим скоупом отвечают 403 ONEC_ACCESS_REQUIRED. Ключ, у которого скоуп уже есть, можно править без этой проверки. Если платформа не смогла проверить доступ, скоуп выдаётся, а отказ придёт уже на вызовах раздела.

3. Владельцу ключа назначен пользователь 1С. Данные читаются от имени пользователя 1С, которому назначен владелец ключа — лично или через отдел. Назначения настраиваются там же, где подключение, отдельно для каждой базы 1С. Без назначения список баз, каталог и запрос на чтение отвечают 403 ONEC_USER_NOT_MAPPED. Каталог и запрос на чтение проверяют доступ к той базе, к которой обращаются.

Как устроен обмен

1С отвечает не сразу: база может быть недоступна в момент вызова, а выборка может занять несколько минут. Поэтому чтение проходит три шага.

1. Каталог. GET /v1/onec/tools возвращает инструменты, которые опубликовала 1С, — их методы и схемы параметров. В Коворке эти инструменты называются командами. Схема инструмента задаёт допустимые columns и filters.
2. Запрос на чтение. POST /v1/onec/tools/{method}/call принимает параметры выборки и отвечает 202 с operationId. Пользователя 1С платформа выбирает сама — по назначению владельца ключа.
3. Результат. GET /v1/onec/operations/{operationId} возвращает состояние операции, а после succeeded — колонки и строки.

Несколько баз 1С

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

1. Список баз. GET /v1/onec/instances возвращает подключённые базы: instanceId, название и состояние.
2. Выбор базы. Каталог, запрос на чтение и результат операции принимают необязательный параметр instanceId в строке запроса.
3. Когда instanceId можно не передавать. Вызов без параметра работает с базой, если она на портале одна. То же правило действует, если из нескольких баз только одна подключена сейчас или подключалась раньше. Ключ подключения, выпущенный для новой базы и ещё не использованный, на выбор не влияет.
4. Когда instanceId обязателен. В остальных случаях каталог и запрос на чтение без параметра отвечают 400 ONEC_INSTANCE_REQUIRED, и операция не создаётся. База с перевыпущенным ключом пропадает из списка до переподключения модуля, но при выборе по-прежнему учитывается — вызов без instanceId в это время тоже получит 400. Поэтому передавайте instanceId нужной базы из списка. Результат операции находится по operationId и без instanceId.
5. Чужой, отключённый или перевыпускаемый instanceId. Каталог и запрос на чтение отвечают 404 ONEC_NOT_CONNECTED, как на неизвестный идентификатор. Так же они отвечают для базы с перевыпущенным ключом, пока модуль Вайбкод не подключится с новым ключом. Запрос результата в этих случаях отвечает 404 ONEC_OPERATION_NOT_FOUND — так же, как на неизвестную операцию.

Быстрый старт

Каталог инструментов портала:

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

Запрос на чтение по методу из каталога:

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": ["Код", "Наименование"], "limit": 100 }'

В ответе — идентификатор операции:

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

Результат по этому идентификатору:

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

Полный пример

Сценарий целиком: выбрать базу и инструмент из каталога, прочитать все страницы выборки и обработать завершённые статусы операции.

const BASE = 'https://vibecode.bitrix24.tech/v1'
const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }

async function api(path, init) {
  const res = await fetch(`${BASE}${path}`, { headers, ...init })
  const body = await res.json()
  if (!res.ok) throw new Error(`${res.status} ${body.error.code}`)
  return body.data
}

// 0. База: если подключено несколько, instanceId обязателен.
const { instances } = await api('/onec/instances')
if (instances.length === 0) throw new Error('Ни одна база 1С ещё не подключилась')
const base = instances.find((b) => b.status === 'ONLINE') ?? instances[0]
const q = `?instanceId=${encodeURIComponent(base.instanceId)}`

// 1. Каталог выбранной базы: инструмент и его допустимые колонки.
const catalog = await api(`/onec/tools${q}`)
if (!catalog.loaded) throw new Error('1С ещё не прислала каталог инструментов')

const tool = catalog.tools.find((t) => t.method === 'bank.list') ?? catalog.tools[0]
const columns = tool.inputSchema.properties.columns.items?.enum ?? null

// 2. Запрос на чтение одной страницы выборки.
async function queue(offset) {
  const data = await api(`/onec/tools/${encodeURIComponent(tool.method)}/call${q}`, {
    method: 'POST',
    body: JSON.stringify({ ...(columns ? { columns } : {}), limit: 1000, offset }),
  })
  return data.operationId
}

// 3. Проверяем операцию, пока она не завершится.
async function waitFor(operationId) {
  let delay = 1000
  for (;;) {
    const data = await api(`/onec/operations/${operationId}${q}`)
    if (data.status === 'succeeded') return data.result
    if (data.status === 'failed') throw new Error(`1С отказала: ${data.error.code}`)
    if (data.status === 'cancelled') throw new Error('Операция отменена')
    if (data.status === 'expired') throw new Error('1С не прислала данные до expiresAt')
    await new Promise((resolve) => setTimeout(resolve, delay))
    delay = Math.min(delay * 2, 5000)
  }
}

// 4. Страницы: следующая позиция приходит в nextOffset.
const rows = []
let offset = 0
for (;;) {
  const result = await waitFor(await queue(offset))
  rows.push(...result.rows)
  if (!result.truncated || result.nextOffset === null || result.rows.length === 0) break
  offset = result.nextOffset
}

console.log(`${base.name} — ${tool.title}: строк ${rows.length}`)

Справочник эндпоинтов

Лимиты

Действующее для ключа значение частоты приходит в заголовке ответа x-ratelimit-limit. Оно ниже суммарного, потому что лимит делится между репликами. Общие правила — Лимиты и оптимизация.

Коды ошибок

Ошибки интеграции 1С

Системные ошибки

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

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

• Подключение 1С к Битрикс24
• Сводка из 1С в чат Битрикс24
• Контрагенты из 1С в компании CRM
• Ключи и авторизация
• Лимиты и оптимизация
• Ошибки