Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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, даже если после этого функцию выключили на самом портале или карточку сделали неактивной.
Пример ответа
{ "success": true, "data": { "status": "accepted", "idempotencyKey": "order-8812-paid" } }
Пример ответа при ошибке
409 — карточка решения неактивна на портале:
{ "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и 503LOOKUP_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, 503CHANNEL_UNAVAILABLE,POOL_EXHAUSTED,STORAGE_FAILED,EVENT_IN_PROGRESS. - Тот же ключ безопасен когда угодно, если в истории не было «да» или после закрытия их не было.
- Потолок без «да»: вся история — не дольше 24 часов от первой попытки, а после закрывающего ответа — от него. Ответы 409 и
QUOTA_EXCEEDEDвы сами не почините: повторяйте их не чаще раза в час. По истечении покажите событие человеку как недоставленное с последнимcode. Повторная отправка — его действием, тем же ключом.
Лимиты
Не больше 60 событий в минуту на ключ и 120 в минуту на портал, все решения портала вместе. В заголовке x-ratelimit-limit виден лимит на ключ: 60 там, где счётчик общий, и доля одного узла платформы, где нет. Лимит портала виден только отказом 429.