Для AI-агентов: markdown этой страницы — /docs-content/applications/long-method.md индекс документации — /llms.txt
Долгий метод в бизнес-процессе
Сложность: продвинутый | Скоупы: bizproc | Стек: cURL / JavaScript (Node.js, Express)
Рецепт для приложения, чья работа не укладывается в окно вызова: приложение принимает задачу от приостановленного действия бизнес-процесса Битрикс24, отвечает сразу и досылает результат отдельным запросом, когда закончит. Бизнес-процесс всё это время спит на своём шаге, а его состояние держит портал. Долгий метод по контракту решения устроен иначе — адрес ответа и одноразовый токен там приезжают заголовками вызова, а исход на портал доставляет платформа: Отправить результат долгого метода.
Что понадобится
- Приложение с включённым внешним API и выпущенным ключом. Переключатель и выдача ключа — в карточке приложения, условия и отказы описаны на странице Внешний API приложения. Этим ключом бизнес-процесс вызывает приложение.
- Ключ платформы для ответа —
vibe_api_…со скоупомbizproc, в режиме чтения и записи, привязанный к тому же порталу. Требования к нему разобраны ниже. - Приостанавливаемое действие бизнес-процесса на портале. Оно вызывает приложение, кладёт в тело запроса свой
eventTokenи засыпает до события. Регистрация такого действия —/v1/bizproc-activities. - Node.js 18 или новее для примеров.
Отвечать надо своим ключом платформы, а не тем ключом, которым приложение вызвали. Ключ внешнего API заперт перечнем маршрутов: ему открыт ровно один адрес платформы — пересылка вызова в приложение. На POST /v1/workflows/event и POST /v1/workflows/activity-log он получает 403 APP_API_KEY_OUT_OF_SCOPE ещё до обработчика, и никакая настройка этого не меняет.
Годится ключ платформы vibe_api_… — тот же, которым решение уже обращается к API Вайбкод. Платформа такой ключ не выдаёт и сама в приложение не подставляет. Его создаёт человек в разделе Ключи API и передаёт приложению переменной окружения при развёртывании. Имя переменной выбираете вы, по соглашению — VIBE_API_KEY: приложение читает её из своего окружения и отправляет значение заголовком X-Api-Key. Автоматически заведённого ключа «на сервер» не существует, и 401 MISSING_API_KEY от приложения означает, что переменная не доехала. Три требования к ключу:
| Требование | Что будет иначе |
|---|---|
ТребованиеСкоуп bizproc |
Что будет иначе403 SCOPE_DENIED |
| ТребованиеРежим чтения и записи | Что будет иначе403 WRITE_BLOCKED_READONLY_KEY. Ответ несёт адрес страницы, где режим переключается |
| ТребованиеПривязка к порталу | Что будет иначе401 TOKEN_MISSING. Так же отвечает ключ авторизации приложения vibe_app_…, предъявленный без токена сессии сотрудника: у него портальные данные живут в сессии, а не на ключе |
Ответ уходит на портал правами владельца ключа, а не того сотрудника, который запустил бизнес-процесс. Событие и запись в журнал платформа выполняет сохранёнными учётными данными владельца, поэтому выбирайте владельца ключа осознанно: у него должны быть права на те процессы, которым решение отвечает. Текущий набор скоупов ключа и состояние его привязки к порталу показывает GET /v1/me. Где переключается режим ключа — Ключи и авторизация.
Во всех примерах $VIBE_URL — базовый адрес https://vibecode.bitrix24.tech, $VIBE_API_KEY — ключ платформы для ответа из пункта 2, а YOUR_APP_EXTERNAL_API_KEY — ключ внешнего API из пункта 1.
Как устроено решение
- Действие бизнес-процесса вызывает приложение по адресу внешнего API и передаёт в теле запроса
eventToken— одноразовый ключ своего шага. - Приложение сохраняет
eventTokenвместе с задачей и отвечает202в пределах окна вызова. Действие после этого спит. - Пока работа идёт, приложение пишет в журнал процесса через
POST /v1/workflows/activity-log. Состояние процесса это не меняет. - Закончив, приложение вызывает
POST /v1/workflows/eventс тем жеeventTokenи значениями для выходных параметров действия. Процесс просыпается и идёт дальше.
Портальные учётные данные приложению не нужны ни на одном шаге: платформа обращается к порталу сохранёнными данными владельца ключа.
Примеры шагов показывают отдельные вызовы и опираются на переменные, объявленные выше по сценарию. Готовый к запуску обработчик — в разделе «Полный код».
Шаг 1. Принять вызов и ответить сразу
Робот бизнес-процесса отправляет запрос на адрес приложения:
Адрес: https://vibecode.bitrix24.tech/v1/applications/:applicationId/api/<ваш-путь>
Метод: POST
Заголовок: X-Api-Key: YOUR_APP_EXTERNAL_API_KEY
В теле действие передаёт свой eventToken и всё, что нужно приложению для работы. Поле кладёт действие, а не платформа — имя поля выбирает автор действия, и в примерах ниже оно называется eventToken.
К телу платформа добавляет заголовки, которые вызывающий подделать не может — входящие имена с префиксом X-Vibe- срезаются:
| Заголовок | Что несёт |
|---|---|
ЗаголовокX-Vibe-Request-Id |
Что несётИдентификатор вызова. Тот же идентификатор платформа пишет в свой журнал |
ЗаголовокX-Vibe-Caller-Kind |
Что несётЗначение external-api — вызов пришёл этим каналом, а не из интерфейса Битрикс24 |
ЗаголовокX-Vibe-Caller-Portal-Id |
Что несётПортал, которому принадлежит ключ вызова |
ЗаголовокX-Vibe-Caller-Key-Id |
Что несётИдентификатор ключа внешнего API, которым сделан вызов |
Заголовков с адресом ответа, токеном ответа и сроком на этом пути нет — они принадлежат вызову по контракту решения. Нет здесь и заголовков с личностью сотрудника: внешний вызов сессии не несёт. Полный разбор того, что доезжает до приложения, — Что получает приложение.
Ответ 202 говорит роботу, что задача принята. Тело ответа при этом остаётся за приложением: робот раскладывает по переменным бизнес-процесса значения верхнего уровня.
JavaScript
// Обработчик маршрута приложения, который вызывает действие бизнес-процесса.
app.post('/long-method', async (req, res) => {
const { eventToken, dealId } = req.body;
if (!eventToken) {
res.status(400).json({ accepted: false, reason: 'EVENT_TOKEN_REQUIRED' });
return;
}
// Задачу кладём в очередь и возвращаем управление СРАЗУ: ответить надо
// в пределах окна вызова, а работа займёт больше.
queue.push({ eventToken, dealId });
res.status(202).json({ accepted: true });
});
Шаг 2. Записать промежуточный шаг в журнал процесса
Пока работа идёт, приложение отчитывается в журнал выполнения бизнес-процесса. Запись видна тому, кто смотрит процесс на портале, и состояние процесса не меняет — действие остаётся приостановленным.
cURL
curl -X POST "$VIBE_URL/v1/workflows/activity-log" \
-H "X-Api-Key: $VIBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"eventToken":"xxx.yyy.zzz","logMessage":"Выборка собрана, считаем скидку"}'
JavaScript
await fetch(`${VIBE_URL}/v1/workflows/activity-log`, {
method: 'POST',
headers: {
'X-Api-Key': VIBE_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
eventToken,
logMessage: 'Выборка собрана, считаем скидку',
}),
});
{
"success": true,
"data": true
}
Полное описание полей и отказов — Записать в журнал процесса.
Шаг 3. Отправить результат в процесс
Работа закончена — приложение отправляет событие с тем же eventToken. Объект returnValues попадает в выходные параметры действия, и бизнес-процесс продолжает работу.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
ПолеeventToken |
Типstring | Обяз.да | ОписаниеТот самый токен, который приехал в теле вызова на шаге 1 |
ПолеreturnValues |
Типobject | Обяз.нет | ОписаниеЗначения выходных параметров действия. По умолчанию — пустой объект |
ПолеlogMessage |
Типstring | Обяз.нет | ОписаниеЗапись в журнал выполнения процесса вместе с событием |
cURL
curl -X POST "$VIBE_URL/v1/workflows/event" \
-H "X-Api-Key: $VIBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"eventToken":"xxx.yyy.zzz","returnValues":{"discount":12.5,"verdict":"approve"},"logMessage":"Скидка рассчитана"}'
JavaScript
const res = await fetch(`${VIBE_URL}/v1/workflows/event`, {
method: 'POST',
headers: {
'X-Api-Key': VIBE_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
eventToken,
returnValues: { discount: 12.5, verdict: 'approve' },
logMessage: 'Скидка рассчитана',
}),
});
const body = await res.json();
if (!body.success) {
console.error(`событие не принято: ${body.error.code}`);
}
{
"success": true,
"data": true
}
Поле data со значением true означает, что портал принял событие и выполнение процесса возобновлено. Полное описание полей и отказов — Отправить событие в процесс.
Ограничения
Окно вызова на шаге 1. Вызов через внешний API приложения живёт 30 секунд — это общий предел, за которым вызывающий получает 503 APP_API_TIMEOUT. Само приложение обязано начать отвечать раньше: платформа перестаёт ждать его ответ на двадцать пятой секунде и отдаёт вызывающему 503 APP_API_UNAVAILABLE. Расчёт по большой выборке, обращение к внешней системе, генерация документа, ожидание ответа человека в эти окна не помещаются — поэтому приложение отвечает 202 и доводит работу после ответа.
Ответ 202 на шаге 1 не гарантирует, что работа началась. Робот получает подтверждение приёма, и дальше единственный сигнал о ходе работы — записи в журнале процесса. Заводите запись на каждой значимой границе: разбирать застрявший шаг по журналу дешевле, чем по логам приложения. Число записей на один шаг платформа не ограничивает, каждая запись — отдельный вызов API и расходуется по общим лимитам.
Ошибку тоже возвращают событием. Приостановленное действие ждёт POST /v1/workflows/event и ничего не знает о том, что приложение упало. Пока события нет, шаг остаётся приостановленным. Поэтому неудачный расчёт отвечает событием с признаком отказа в returnValues, а не молчанием.
Один eventToken закрывает один шаг. Каждая приостановка процесса выдаёт новый токен, и сразу после POST /v1/workflows/event прежний недействителен. Срок жизни токена платформа не ограничивает и передаёт его в Битрикс24 как есть, а недействительный или уже использованный токен Битрикс24 отклоняет кодом 403 BITRIX_ACCESS_DENIED. Поэтому повтор после сетевого обрыва небезопасен вслепую: тот же код придёт и когда первый запрос дошёл, и когда токен был испорчен, а различить эти два случая по ответу нечем.
Ключ ответа не хранится рядом с ключом вызова. Ключ внешнего API лежит в настройках робота на портале, ключ ответа — в переменных окружения приложения. Отзыв одного другого не трогает, и перевыпуск ключа внешнего API идущие ответы не ломает.
Скоуп проверяется раньше режима ключа. Ключ без скоупа bizproc и в режиме чтения получит 403 SCOPE_DENIED, а не отказ по режиму. Сначала откройте скоуп, потом проверяйте режим.
Отказы при ответе. Таблица собрана по двум адресам ответа — POST /v1/workflows/event и POST /v1/workflows/activity-log. Отказы самого вызова приложения на шаге 1 — в таблице Внешний API приложения.
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодMISSING_PARAMS |
ОписаниеНе передан eventToken. На записи в журнал так же отвечает запрос без logMessage |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеЗаголовок с ключом не передан |
| HTTP401 | КодINVALID_API_KEY |
ОписаниеКлюч не опознан: такой строки на платформе нет |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеУ ключа нет привязки к порталу. Текст ответа называет причину и то, что с ней делать |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа bizproc. Проверяется первым — раньше режима ключа |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеКлюч переведён в режим чтения. Поле details.switchUrl называет страницу, где режим меняется |
| HTTP403 | КодAPP_API_KEY_OUT_OF_SCOPE |
ОписаниеОтвет отправлен ключом внешнего API приложения. Этому ключу открыта только пересылка вызова в приложение |
| HTTP403 | КодBITRIX_ACCESS_DENIED |
ОписаниеБитрикс24 отклонил запрос: токен недействителен, истёк или уже использован |
| HTTP409 | КодBIZPROC_MODULE_NOT_ENABLED |
ОписаниеБизнес-процессов на портале нет: модуль не входит в тариф либо выключен в настройках портала. Попросите администратора портала включить бизнес-процессы — до этого оба адреса отвечают так же при любом числе повторов |
| HTTP422 | КодBITRIX_ERROR |
ОписаниеОшибка на стороне Битрикс24 |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов. Повторите через 1–2 секунды |
| HTTP502 | КодBITRIX_UNAVAILABLE |
ОписаниеБитрикс24 недоступен |
403 — ключ переведён в режим чтения:
{
"success": false,
"error": {
"code": "WRITE_BLOCKED_READONLY_KEY",
"message": "Key is in read-only mode. Switch the key to read and write in /keys to allow Bitrix24 data changes.",
"details": {
"method": "bizproc.event.send",
"keyName": "Solution deploy key",
"currentMode": "READONLY",
"switchUrl": "/keys"
}
}
}
Полный список общих ошибок API — Ошибки.
Полный код
Обработчик принимает вызов действия, отвечает 202 и доводит задачу в фоне, отчитываясь в журнал процесса. Все переменные объявлены внутри, запускается как есть на Node.js 18 и новее.
import express from 'express';
const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true })); // робот шлёт поля формы, не JSON
const VIBE_URL = process.env.VIBE_URL ?? 'https://vibecode.bitrix24.tech';
const VIBE_API_KEY = process.env.VIBE_API_KEY;
if (!VIBE_API_KEY) throw new Error('Переменная окружения VIBE_API_KEY не задана');
async function callVibe(path, body) {
const res = await fetch(`${VIBE_URL}/v1${path}`, {
method: 'POST',
headers: {
'X-Api-Key': VIBE_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const payload = await res.json();
if (!payload.success) {
throw new Error(`${path}: ${payload.error.code} — ${payload.error.message}`);
}
return payload.data;
}
async function runLongWork(eventToken, dealId) {
try {
await callVibe('/workflows/activity-log', {
eventToken,
logMessage: `Считаем скидку по сделке ${dealId}`,
});
const discount = await computeDiscount(dealId); // ваша долгая работа
await callVibe('/workflows/event', {
eventToken,
returnValues: { discount, verdict: discount > 0 ? 'approve' : 'reject' },
logMessage: 'Скидка рассчитана',
});
} catch (err) {
// Процесс спит и ждёт события. Ошибку тоже надо вернуть событием,
// иначе шаг останется приостановленным до срока, заданного на портале.
await callVibe('/workflows/event', {
eventToken,
returnValues: { discount: 0, verdict: 'error' },
logMessage: `Расчёт не удался: ${err.message}`,
}).catch(() => {});
}
}
app.post('/long-method', (req, res) => {
const { eventToken, dealId } = req.body;
if (!eventToken || !dealId) {
res.status(400).json({ accepted: false, reason: 'EVENT_TOKEN_AND_DEAL_REQUIRED' });
return;
}
// Ответ уходит СРАЗУ, работа идёт после него.
res.status(202).json({ accepted: true });
void runLongWork(eventToken, String(dealId));
});
async function computeDiscount(dealId) {
await new Promise((resolve) => setTimeout(resolve, 60_000));
return 12.5;
}
app.listen(process.env.PORT || 3000);