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

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

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

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

## Параметры

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

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

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

## Примеры

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

```bash
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-приложение

```bash
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}`](/docs/onec/operation) |
| `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 — [Ошибки](/docs/errors).

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

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

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


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


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

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

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

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