Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 | ОписаниеЧисло волн параллельных запросов при разбиении по окнам |
Пример ответа
{
"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:
{
"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.