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

`POST /v1/solution-events`

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

## Доступ

Вызывайте адрес ключом приложения. Подходит личный ключ приложения или ключ OAuth-приложения, на котором оно построено. Виды ключей описаны в разделе [Ключи и авторизация](/docs/keys-auth). Ключ разработчика, не привязанный к приложению, получит `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 — личный ключ

```bash
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-приложение

```bash
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 | Код | Описание |
|---|---|---|
| 400 | `BODY_INVALID` | Тело не JSON-объект |
| 400 | `UNKNOWN_FIELD` | В теле поле кроме `idempotencyKey` и `data` |
| 400 | `EVENT_KEY_INVALID` | Ключ не передан, не строка, пустой, длиннее 255 или не из печатных символов ASCII |
| 400 | `DATA_INVALID` | `data` не передано, не объект, вложенность глубже 64 или строка либо имя ключа с одиночным суррогатом |
| 413 | `DATA_TOO_LARGE` | `data` больше 262 144 байт или тело больше 1 МиБ |
| 403 | `SOLUTION_KEY_REQUIRED` | Ключ не принадлежит приложению этого портала |
| 403 | `APP_API_KEY_OUT_OF_SCOPE` | Ключ внешнего API приложения открывает только адреса внешнего API приложения |
| 409 | `SOLUTION_EVENTS_NOT_ENABLED` | Функция не включена для портала |
| 409 | `CARD_NOT_PUBLISHED` | Карточка приложения ещё не опубликована в каталоге портала или снимается |
| 409 | `PORTAL_NOT_PAIRED` | У коробочного портала нет живой связи с платформой, восстанавливает администратор портала |
| 409 | `PORTAL_DOMAIN_NOT_SUPPORTED` | Для облачного портала на своём домене события не поддерживаются |
| 409 | `PORTAL_NOT_SUPPORTED` | Модуль на портале старше 26.1100.0: администратору портала — обновить модуль |
| 409 | `PORTAL_FEATURE_DISABLED` | Функция выключена на самом портале |
| 409 | `CARD_NOT_FOUND` | Карточки решения на портале нет: переопубликуйте решение |
| 409 | `CARD_INACTIVE` | Карточка неактивна на портале |
| 409 | `OWNER_INACTIVE` | Владелец карточки неактивен на портале |
| 409 | `SOLUTION_NOT_ELIGIBLE` | Решение недоступно владельцу карточки |
| 409 | `TARIFF_RESTRICTED` | Тариф портала не позволяет события |
| 409 | `CARD_NOT_BOUND` | Карточка не связана с этим подключением платформы |
| 409 | `EVENT_KEY_CONFLICT` | Ключ за 48 часов уже принят с другими данными или для другой карточки |
| 429 | `SOLUTION_EVENTS_RATE_LIMITED` | Больше 60 событий в минуту на ключ или 120 в минуту на портал |
| 502 | `PORTAL_CHANNEL_ERROR` | Ошибка канала на стороне платформы |
| 503 | `CHANNEL_UNAVAILABLE` | Канал к порталу временно недоступен |
| 503 | `PORTAL_TIMEOUT`, `PORTAL_UNAVAILABLE` | Портал не ответил или недоступен |
| 503 | `EVENT_IN_PROGRESS` | Параллельный запрос с тем же ключом ещё обрабатывается |
| 503 | `STORAGE_FAILED`, `LOOKUP_FAILED`, `START_FAILED` | Сбой на портале, ключ не потрачен |
| 503 | `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 — [Ошибки](/docs/errors).

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

| Ответ | Портал мог принять событие? | Что делать |
|---|---|---|
| 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`.

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

- [Внешний API приложения](/docs/applications/external-api)
- [Долгий метод в бизнес-процессе](/docs/applications/long-method)
- [Ключи и авторизация](/docs/keys-auth)
- [Ошибки](/docs/errors)
