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

Поиск шаблонов

POST /v1/bizproc-templates/search

Отбирает шаблоны бизнес-процессов по условиям и возвращает их списком. Отличие от списка шаблонов — условия отбора передаются в теле запроса, поэтому сложный фильтр не нужно укладывать в адресную строку.

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

Поле Тип По умолч. Описание
filter object — Фильтрация по полям GET /v1/bizproc-templates/fields.
Синтаксис фильтрации. Пример: { "entity": "CCrmDocumentLead" }.
Значения moduleId и entity — первые два элемента documentType, они перечислены в Загрузить шаблон
select string[] — Поля в ответе: id, moduleId, entity, documentType, autoExecute, name, description, modified, isModified, userId. Без select возвращается полный набор объявленных полей
order object — Сортировка. Пример: { "id": "desc" }
limit number 50 Количество записей в ответе, до 5000. Ноль не означает «без ограничения» — он игнорируется, приходят 50 записей и предупреждение LIMIT_ZERO_IGNORED
offset number 0 Смещение выборки
autoWindow boolean true Разбивать выборку недельными окнами при фильтре по диапазону modified шире 14 дней. false отключает разбиение

Примеры

Искать шаблоны можно только ключом авторизации — оба примера отправляют ключ авторизации и заголовок Authorization: Bearer. Токен сессии выдаёт OAuth-авторизация и живёт 24 часа без продления — Передача ключа.

curl — ключ авторизации

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/bizproc-templates/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "moduleId": "crm" },
    "select": ["id", "name", "entity", "autoExecute"],
    "order": { "id": "desc" },
    "limit": 3
  }'

JavaScript — ключ авторизации

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/bizproc-templates/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { moduleId: 'crm' },
    select: ['id', 'name', 'entity', 'autoExecute'],
    order: { id: 'desc' },
    limit: 3,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Найдено шаблонов: ${meta.total}`)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив шаблонов. Состав полей элемента определяется параметром select, полная схема — Поля шаблона. Файл шаблона templateData в ответах не приходит
meta.total number Количество шаблонов, попавших под фильтр
meta.hasMore boolean Есть ли записи за пределами limit
meta.durationMs number Длительность запроса в миллисекундах
meta.warnings array Предупреждения о разборе запроса. Каждое — объект с полями code, field и message, например неизвестное имя поля в select с кодом UNKNOWN_SELECT_FIELD
meta.autoWindowed boolean true, если выборка была разбита по временным окнам
meta.windowCount number Число окон, на которые разбит диапазон дат. Приходит при autoWindowed равном true
meta.batchWaves number Число волн параллельных запросов при разбиении по окнам

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1237,
      "name": "Согласование договора",
      "entity": "CCrmDocumentDeal",
      "autoExecute": 1
    },
    {
      "id": 1153,
      "name": "Заявка на закупку",
      "entity": "CCrmDocumentDeal",
      "autoExecute": 0
    },
    {
      "id": 1143,
      "name": "Обработка обращения",
      "entity": "CCrmDocumentLead",
      "autoExecute": 0
    }
  ],
  "meta": {
    "total": 18,
    "hasMore": true,
    "durationMs": 113
  }
}

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

403 — запрос отправлен API-ключом:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_REQUIRED",
    "message": "bizproc-templates require an OAuth app key (vibe_app_*) with an Authorization: Bearer session — a personal vibe_api_* key lacks the per-user OAuth context Bitrix24 needs for these methods. Create an OAuth app (POST /v1/apps) and retry with its key. On this 403 switch keys — do NOT delete or recreate the app (that discards anything already registered under it, e.g. a bizproc robot you just registered)."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_FILTER_OPERATOR Неизвестный оператор в фильтре. Сообщение перечисляет поддерживаемые операторы
400 INVALID_FILTER_OPERATOR Логический ключ $or или $and в фильтре. Условие ИЛИ задаётся оператором $in для одного поля или параллельными запросами через POST /v1/batch, условие И — соседними ключами одного фильтра
400 UNSTABLE_OFFSET_PAGINATION offset больше нуля вместе с фильтром по диапазону дат шире 14 дней. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой по id, либо режьте диапазон дат на части сами
403 OAUTH_REQUIRED Запрос отправлен API-ключом. Искать шаблоны можно только ключом авторизации
401 TOKEN_MISSING Ключ авторизации без заголовка Authorization: Bearer
401 WRONG_AUTH_SCHEME Ключ авторизации отправлен в заголовке Authorization: Bearer. Сам ключ передаётся в X-Api-Key, а Authorization: Bearer несёт токен сессии
401 INVALID_SESSION Токен сессии истёк или недействителен — пройдите авторизацию заново
403 SCOPE_DENIED Ключу не хватает скоупа bizproc

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

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

Идентификатор в select перечисляется явно. К выбранным полям id не добавляется — если он нужен для последующего обновления или удаления, включите его в select сами.

При разбиении по окнам meta.total считает только прочитанные окна. Фильтр по диапазону modified шире 14 дней читает выборку недельными окнами и останавливается, когда набрал limit записей: в meta.total тогда приходит количество из уже прочитанных окон, оно меньше полного. Точное количество даёт запрос с autoWindow: false либо чтение всей выборки одним запросом с limit до 5000.

Неизвестное имя поля не прерывает запрос. В filter выборка не сужается, в order порядок не меняется, в select поле отсутствует в записях, а в meta.warnings приходит предупреждение с кодом UNKNOWN_SELECT_FIELD. Имена полей сверяйте со схемой GET /v1/bizproc-templates/fields.

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