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

Отправить событие решения

POST /v1/solution-events

Решение сообщает порталу Битрикс24 о событии, и на портале запускаются бизнес-процессы с триггером «Событие решения Вайбкод» от имени владельца карточки решения в каталоге портала. Вызов синхронный: платформа сразу передаёт событие порталу.

Доступ

Вызывайте адрес ключом приложения. Подходит личный ключ приложения или ключ OAuth-приложения, на котором оно построено. Виды ключей описаны в разделе Ключи и авторизация. Ключ разработчика, не привязанный к приложению, получит 403 SOLUTION_KEY_REQUIRED. Ключ внешнего API приложения здесь не подходит: 403 APP_API_KEY_OUT_OF_SCOPE. Карточку и портал платформа находит по ключу, передавать их не нужно.

Пока функция не включена для портала, адрес отвечает 409 SOLUTION_EVENTS_NOT_ENABLED.

Ключ в режиме «только чтение» событий не отправляет и получает 403 WRITE_BLOCKED_READONLY_KEY: процессы владельца карточки меняют данные портала.

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

Поле Тип Обяз. Описание
ПолеidempotencyKey Типstring Обяз.да ОписаниеВаш ключ события: от 1 до 255 печатных символов ASCII без пробелов. Непрозрачный идентификатор: не кладите в него почту, телефон, ФИО и другие персональные данные
Полеdata Типobject Обяз.да ОписаниеЛюбой JSON-объект: вложенность не глубже 64, не больше 262 144 байт. В процессе приходит как Data, рядом с CatalogItemId

Других полей в теле быть не должно: иначе 400 UNKNOWN_FIELD.

Размер и байты `data`

  • Размер считается по компактной сериализации data без пробелов и переводов строк, в байтах UTF-8.
  • Портал запоминает событие по ключу и точным байтам data. Повтор отправляйте тем же объектом в том же порядке ключей, иначе получите 409 EVENT_KEY_CONFLICT.
  • Целые числа больше 2^53 теряют точность при разборе: отправляйте их строкой.
  • Ключи-целые "1" и "20" JavaScript ставит в начало объекта. Это не мешает, пока повтор строится тем же кодом.

Примеры

Тело запроса одинаково во всех примерах. Разница только в заголовках.

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/solution-events" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "order-8812-paid", "data": {"orderId": 8812, "status": "paid"}}'

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/solution-events" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "order-8812-paid", "data": {"orderId": 8812, "status": "paid"}}'

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

javascript
const event = { idempotencyKey: 'order-8812-paid', data: { orderId: 8812, status: 'paid' } };

const res = await fetch('https://vibecode.bitrix24.tech/v1/solution-events', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  // Повтор — тем же объектом event: портал сравнивает ключ и точные байты data.
  body: JSON.stringify(event),
});
const body = await res.json();
if (!body.success && body.error.retryable) {
  const waitSeconds = Number(res.headers.get('retry-after') ?? 30);
  // Повторить запрос с тем же event не раньше чем через waitSeconds секунд.
}

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

javascript
const event = { idempotencyKey: 'order-8812-paid', data: { orderId: 8812, status: 'paid' } };

const res = await fetch('https://vibecode.bitrix24.tech/v1/solution-events', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  // Повтор — тем же объектом event: портал сравнивает ключ и точные байты data.
  body: JSON.stringify(event),
});
const body = await res.json();
if (!body.success && body.error.retryable) {
  const waitSeconds = Number(res.headers.get('retry-after') ?? 30);
  // Повторить запрос с тем же event не раньше чем через waitSeconds секунд.
}

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеРезультат передачи события порталу
Полеdata.status Типstring Описаниеaccepted — портал принял событие. duplicate — событие с этим ключом и этими данными уже принято, портал помнит ключ 48 часов
Полеdata.idempotencyKey Типstring ОписаниеВаш ключ события из запроса

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

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

JSON
{ "success": true, "data": { "status": "accepted", "idempotencyKey": "order-8812-paid" } }

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

409 — карточка решения неактивна на портале:

JSON
{ "success": false, "error": { "code": "CARD_INACTIVE", "message": "The solution's catalog card is inactive on the Bitrix24 account.", "retryable": false } }

error.retryable есть только в ответах самого метода: true — повторить с паузой.

Ошибки

HTTP Код Описание
HTTP400 КодBODY_INVALID ОписаниеТело не JSON-объект
HTTP400 КодUNKNOWN_FIELD ОписаниеВ теле поле кроме idempotencyKey и data
HTTP400 КодEVENT_KEY_INVALID ОписаниеКлюч не передан, не строка, пустой, длиннее 255 или не из печатных символов ASCII
HTTP400 КодDATA_INVALID Описаниеdata не передано, не объект, вложенность глубже 64 или строка либо имя ключа с одиночным суррогатом
HTTP413 КодDATA_TOO_LARGE Описаниеdata больше 262 144 байт или тело больше 1 МиБ
HTTP403 КодSOLUTION_KEY_REQUIRED ОписаниеКлюч не принадлежит приложению этого портала
HTTP403 КодAPP_API_KEY_OUT_OF_SCOPE ОписаниеКлюч внешнего API приложения открывает только адреса внешнего API приложения
HTTP409 КодSOLUTION_EVENTS_NOT_ENABLED ОписаниеФункция не включена для портала
HTTP409 КодCARD_NOT_PUBLISHED ОписаниеКарточка приложения ещё не опубликована в каталоге портала или снимается
HTTP409 КодPORTAL_NOT_PAIRED ОписаниеУ коробочного портала нет живой связи с платформой, восстанавливает администратор портала
HTTP409 КодPORTAL_DOMAIN_NOT_SUPPORTED ОписаниеДля облачного портала на своём домене события не поддерживаются
HTTP409 КодPORTAL_NOT_SUPPORTED ОписаниеМодуль на портале старше 26.1100.0: администратору портала — обновить модуль
HTTP409 КодPORTAL_FEATURE_DISABLED ОписаниеФункция выключена на самом портале
HTTP409 КодCARD_NOT_FOUND ОписаниеКарточки решения на портале нет: переопубликуйте решение
HTTP409 КодCARD_INACTIVE ОписаниеКарточка неактивна на портале
HTTP409 КодOWNER_INACTIVE ОписаниеВладелец карточки неактивен на портале
HTTP409 КодSOLUTION_NOT_ELIGIBLE ОписаниеРешение недоступно владельцу карточки
HTTP409 КодTARIFF_RESTRICTED ОписаниеТариф портала не позволяет события
HTTP409 КодCARD_NOT_BOUND ОписаниеКарточка не связана с этим подключением платформы
HTTP409 КодEVENT_KEY_CONFLICT ОписаниеКлюч за 48 часов уже принят с другими данными или для другой карточки
HTTP429 КодSOLUTION_EVENTS_RATE_LIMITED ОписаниеБольше 60 событий в минуту на ключ или 120 в минуту на портал
HTTP502 КодPORTAL_CHANNEL_ERROR ОписаниеОшибка канала на стороне платформы
HTTP503 КодCHANNEL_UNAVAILABLE ОписаниеКанал к порталу временно недоступен
HTTP503 КодPORTAL_TIMEOUT, PORTAL_UNAVAILABLE ОписаниеПортал не ответил или недоступен
HTTP503 КодEVENT_IN_PROGRESS ОписаниеПараллельный запрос с тем же ключом ещё обрабатывается
HTTP503 КодSTORAGE_FAILED, LOOKUP_FAILED, START_FAILED ОписаниеСбой на портале, ключ не потрачен
HTTP503 КодBIZPROC_UNAVAILABLE ОписаниеМодуль бизнес-процессов на портале недоступен

Общие ответы для всех методов ключа: 401 при отсутствии ключа, неверном или истёкшем ключе и NO_PORTAL, 402 ACCOUNT_FROZEN, 403 при блокировках владельца и портала и при режиме ключа, 429 CALLER_RATE_LIMITED, 429 QUOTA_EXCEEDED, 503 POOL_EXHAUSTED, 503 user_self_deletion_pending. Последний значит, что владелец ключа удаляет свою учётную запись на портале: Retry-After равен 604800, повтор бессмыслен до отмены удаления. У общих ответов поля error.retryable нет.

События не тарифицируются как API-вызовы. Но дневная норма ключа общая для всех методов: ключ, исчерпавший её вызовами Битрикс24 при пустом предоплатном балансе, получит 429 QUOTA_EXCEEDED и на событиях.

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

Что делать с ответом

Ответ Портал мог принять событие? Что делать
Ответ200 Портал мог принять событие?да, принял Что делатьГотово, повторять нельзя
Ответ400, 413 Портал мог принять событие?нет Что делатьИсправить запрос
Ответ401, 402, 403 Портал мог принять событие?нет Что делатьИсправить доступ: ключ, режим ключа, оплата, блокировка
Ответ503 user_self_deletion_pending Портал мог принять событие?нет Что делатьВладелец ключа удаляет свою учётную запись на портале. Retry-After равен 604800, то есть 7 дням отсрочки удаления: повторять бессмысленно, пока удаление не отменено
Ответ409 EVENT_KEY_CONFLICT Портал мог принять событие?если раньше была попытка с ответом «да», описанным ниже, — да, уже принял Что делатьБыла такая попытка — событие принято, новый ключ не отправлять, искать, почему изменились байты data. Не было — ключ совпал с другим событием: отправить с новым ключом
Ответ409, прочие коды Портал мог принять событие?нет Что делатьИсправить состояние: функция, карточка, связь коробочного портала, владелец, тариф, модуль портала
Ответ502 Портал мог принять событие?нет Что делатьОшибка канала на стороне платформы, повтором не лечится
Ответ429 QUOTA_EXCEEDED Портал мог принять событие?нет Что делатьПополнить баланс. Норма дневная: проходит после пополнения или со следующими сутками, Retry-After нет
Ответ429, прочие коды Портал мог принять событие?нет Что делатьПовторить с паузой
Ответ503 CHANNEL_UNAVAILABLE, STORAGE_FAILED, LOOKUP_FAILED, START_FAILED, BIZPROC_UNAVAILABLE, POOL_EXHAUSTED Портал мог принять событие?нет Что делатьПовторить с паузой
Ответ503 PORTAL_TIMEOUT, PORTAL_UNAVAILABLE, EVENT_IN_PROGRESS Портал мог принять событие?да Что делатьПовторить с паузой, повтор принятого даст duplicate
Ответ504, 500, таймаут вашего клиента, обрыв без ответа Портал мог принять событие?да Что делатьКак предыдущая строка

Пауза — не меньше Retry-After и вдвое больше с каждой попыткой: 30 с, 1 мин, 2 мин и так до 1 часа. Повторы тратят тот же лимит, что и новые события: повторы при долгом простое портала вытеснят свежие события. Таймаут вашего клиента — не меньше 30 секунд.

История события: когда тот же ключ безопасен

Ключ и данные при повторе — те же. Решайте по всей истории события, а не по последнему ответу. Попытка с ответом «да» — строки таблицы, где портал мог принять событие.

  • Окно 24 часа отсчитывается от первой попытки с ответом «да» и не сбрасывается последующими ответами. Позже событие считайте потерянным или принятым, решение за вами, и покажите это человеку.
  • Историю закрывает ответ портала на попытку, отправленную не раньше чем через 6 минут после последней попытки с ответом «да». 200 — событие принято, конец. 409 PORTAL_FEATURE_DISABLED, CARD_NOT_FOUND, CARD_INACTIVE, OWNER_INACTIVE, SOLUTION_NOT_ELIGIBLE, TARIFF_RESTRICTED, CARD_NOT_BOUND и 503 LOOKUP_FAILED, BIZPROC_UNAVAILABLE, START_FAILED — портал проверил ключ и не нашёл, прежние «да» погашены. EVENT_KEY_CONFLICT при непогашенном «да» значит «принято».
  • Историю не закрывают остальные 409. Это отказы платформы до вызова портала: SOLUTION_EVENTS_NOT_ENABLED, CARD_NOT_PUBLISHED, PORTAL_NOT_PAIRED, PORTAL_DOMAIN_NOT_SUPPORTED, и PORTAL_NOT_SUPPORTED от старого модуля портала. Все они приходят до проверки ключа и о прошлых попытках не знают, как и 502, 429, 401, 402, 403, 503 CHANNEL_UNAVAILABLE, POOL_EXHAUSTED, STORAGE_FAILED, EVENT_IN_PROGRESS.
  • Тот же ключ безопасен когда угодно, если в истории не было «да» или после закрытия их не было.
  • Потолок без «да»: вся история — не дольше 24 часов от первой попытки, а после закрывающего ответа — от него. Ответы 409 и QUOTA_EXCEEDED вы сами не почините: повторяйте их не чаще раза в час. По истечении покажите событие человеку как недоставленное с последним code. Повторная отправка — его действием, тем же ключом.

Лимиты

Не больше 60 событий в минуту на ключ и 120 в минуту на портал, все решения портала вместе. В заголовке x-ratelimit-limit виден лимит на ключ: 60 там, где счётчик общий, и доля одного узла платформы, где нет. Лимит портала виден только отказом 429.

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