Для 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 ОписаниеСмещение выборки
Полеstart Типnumber По умолч.0 ОписаниеТо же значение смещения, что offset. Если заданы оба поля, действует offset, включая 0; при offset: null действует start.
ПолеautoWindow Типboolean По умолч.true ОписаниеРазбивать выборку недельными окнами при фильтре по диапазону modified шире 14 дней. false отключает разбиение

Примеры

Токен сессии для примеров с ключом OAuth-приложения выдаёт OAuth-авторизация, он живёт 24 часа без продления — Передача ключа.

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

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

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

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_API_KEY',
    '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}`)

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

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 — ключу не хватает скоупа bizproc:

JSON
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'bizproc' scope"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_FILTER_OPERATOR ОписаниеНеизвестный оператор в фильтре. Сообщение перечисляет поддерживаемые операторы
HTTP400 КодINVALID_FILTER_OPERATOR ОписаниеЛогический ключ $or или $and в фильтре. Условие ИЛИ задаётся оператором $in для одного поля или параллельными запросами через POST /v1/batch, условие И — соседними ключами одного фильтра
HTTP400 КодUNSTABLE_OFFSET_PAGINATION ОписаниеДействующее смещение (offset, если передан и не равен null, иначе start) больше нуля при активном разбиении по датам. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой по id, либо режьте диапазон дат на части сами
HTTP401 КодTOKEN_MISSING ОписаниеКлюч OAuth-приложения без заголовка Authorization: Bearer
HTTP401 КодWRONG_AUTH_SCHEME ОписаниеКлюч авторизации отправлен в заголовке Authorization: Bearer. Сам ключ передаётся в X-Api-Key, а Authorization: Bearer несёт токен сессии
HTTP401 КодINVALID_SESSION ОписаниеТокен сессии истёк или недействителен — пройдите авторизацию заново
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа bizproc
HTTP409 КодBIZPROC_MODULE_NOT_ENABLED ОписаниеБизнес-процессов на портале нет: модуль не входит в тариф либо выключен в настройках портала. Попросите администратора портала включить бизнес-процессы — до этого метод отвечает так же при любом числе повторов
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

Полный список общих ошибок 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.

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