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

Долгий метод в бизнес-процессе

Сложность: продвинутый | Скоупы: bizproc | Стек: cURL / JavaScript (Node.js, Express)

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

Что понадобится

  1. Приложение с включённым внешним API и выпущенным ключом. Переключатель и выдача ключа — в карточке приложения, условия и отказы описаны на странице Внешний API приложения. Этим ключом бизнес-процесс вызывает приложение.
  2. Ключ платформы для ответа — vibe_api_… со скоупом bizproc, в режиме чтения и записи, привязанный к тому же порталу. Требования к нему разобраны ниже.
  3. Приостанавливаемое действие бизнес-процесса на портале. Оно вызывает приложение, кладёт в тело запроса свой eventToken и засыпает до события. Регистрация такого действия — /v1/bizproc-activities.
  4. 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.

Как устроено решение

  1. Действие бизнес-процесса вызывает приложение по адресу внешнего API и передаёт в теле запроса eventToken — одноразовый ключ своего шага.
  2. Приложение сохраняет eventToken вместе с задачей и отвечает 202 в пределах окна вызова. Действие после этого спит.
  3. Пока работа идёт, приложение пишет в журнал процесса через POST /v1/workflows/activity-log. Состояние процесса это не меняет.
  4. Закончив, приложение вызывает 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

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

Terminal
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

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: 'Выборка собрана, считаем скидку',
  }),
});
JSON
{
  "success": true,
  "data": true
}

Полное описание полей и отказов — Записать в журнал процесса.

Шаг 3. Отправить результат в процесс

Работа закончена — приложение отправляет событие с тем же eventToken. Объект returnValues попадает в выходные параметры действия, и бизнес-процесс продолжает работу.

Поле Тип Обяз. Описание
ПолеeventToken Типstring Обяз.да ОписаниеТот самый токен, который приехал в теле вызова на шаге 1
ПолеreturnValues Типobject Обяз.нет ОписаниеЗначения выходных параметров действия. По умолчанию — пустой объект
ПолеlogMessage Типstring Обяз.нет ОписаниеЗапись в журнал выполнения процесса вместе с событием

cURL

Terminal
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

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}`);
}
JSON
{
  "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 — ключ переведён в режим чтения:

JSON
{
  "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 и новее.

javascript
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);

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