# Mindbox API и вебхуки: как передавать события, которые не покрывают стандартные интеграции

> Возвраты из 1С, офлайн-чеки, события приложения — стандартная интеграция их не видит. Разбираем, как передать их в Mindbox через API и вебхуки и где обмен ломается.

**Рубрика:** Статьи  
**Дата:** 2026-08-29

Стандартная интеграция подключена, модуль на сайте стоит, заказы в Mindbox едут — на этом обычно все и заканчивается. А потом выясняется, что триггер на возврат не стреляет, потому что статус «возврат» живет в 1С и наружу не отдается. Что письмо с просьбой оценить покупку не уходит, потому что статус «выдан» до платформы не доезжает. Что RFM-сегменты врут, потому что офлайн-чеки с касс никуда не попадают.

Платформа при этом честно делает свою работу — просто она не знает о половине того, что происходит с клиентом. Все, что не покрыто стандартными модулями, доносится до Mindbox через API и вебхуки. Валерия Старостина, CRM-маркетолог ClientCore, рассказывает, какие события передавать в первую очередь, как устроен обмен и в каких местах он чаще всего ломается.

> **Читайте также:** [Промокоды и акции в Mindbox: как скидочные механики влияют на маржу и повторные покупки](https://clientcore.ru/blog/articles/promokody-i-akcii-v-mindbox-kak-skidochnye-mehaniki-vliyayut-na-marzhu-i-povtornye-pokupki)

## Что покрывает стандартная интеграция и где она заканчивается

JS-сниппет на сайте и готовый модуль для CMS дают базовый набор: просмотры страниц и товаров, корзина, оформленный заказ, подписка на рассылки. Импорт заказов через XML-фид добавляет историю продаж. Для старта этого хватает — welcome-цепочка, брошенная корзина и реактивация заработают.

Проблемы начинаются, когда бизнес выходит за пределы сайта. За бортом стандартной интеграции обычно остаются:

- полный жизненный цикл заказа из ERP или 1С: собран, передан в доставку, ждет в пункте выдачи, выдан, возвращен;
- офлайн-продажи с касс розничных точек;
- события мобильного приложения;
- сервисные события из личного кабинета: продление подписки, запись на ТО, окончание страховки;
- сигналы из внешних систем: коллтрекинг, бронирования, складское наличие.

Каждое из этих событий — потенциальный триггер, который приносит деньги. Пока его нет в Mindbox, механики на нем не существует.

> Классическая картина на аудите: модуль на сайте стоит, заказы едут, все довольны. Спрашиваю: а статус „возврат“ у вас что-нибудь триггерит? Тишина. Он живет в 1С, наружу его никто не отдает, и механики возврата отказника просто нет. А ведь цепочка после возврата — выяснить причину, предложить обмен, дать бонус — возвращает заметную часть таких клиентов.
>
> — Валерия Старостина, CRM-маркетолог, ClientCore

## Как устроен обмен через Mindbox API

Mindbox API — это REST-интерфейс: внешняя система отправляет HTTP-запрос с JSON в теле, платформа принимает и обрабатывает. Авторизация — по ключу, у каждой точки интеграции свой endpoint. Официальная документация Mindbox API живет на developers.mindbox.ru: там описания операций, примеры запросов и ответов, коды ошибок.

Единица обмена — операция. Системные операции покрывают стандартные действия: зарегистрировать клиента, создать заказ, изменить подписку. Кастомные операции вы заводите сами в админке под свою задачу — например, «Запись на сервис» или «Окончание абонемента» — со своим набором полей. После этого внешняя система может их вызывать, а в Mindbox на событие вешается триггерный сценарий.

Два момента, которые стоит знать до старта. Первый: операции бывают синхронные и асинхронные. Синхронная сразу возвращает результат, асинхронная — принимает запрос в обработку и отдает operationId, по которому позже проверяется статус. Второй: клиент идентифицируется через ids — набор идентификаторов (email, телефон, внешний ID из вашей системы). Чем аккуратнее выстроена идентификация, тем меньше двойников в базе. К ней мы еще вернемся — это одна из главных точек отказа.

## Вебхуки Mindbox: входящие и исходящие

Когда говорят «миндбокс вебхуки», обычно смешивают два разных механизма, и из-за этого в ТЗ разработчику случается путаница.

Входящий поток — это вызовы API-операций от ваших систем: 1С отправляет смену статуса заказа, бэкенд приложения — событие, касса — офлайн-чек. Строго говоря, это API-вызовы, хотя в народе их вебхуками и называют.

Исходящие вебхуки — обратное направление: Mindbox сам стучится на ваш URL, когда срабатывает событие. Настраивается это как действие в триггерном сценарии. Типовые сценарии:

- передать задачу в колл-центр, когда VIP-клиент бросил корзину;
- уведомить менеджера в мессенджере о крупном заказе;
- отправить офлайн-конверсию в рекламный кабинет;
- синхронизировать событие с BI или корпоративным хранилищем.

К принимающей стороне одно требование, но жесткое: отвечать быстро и кодом 200. Если ваш сервер тормозит или отвечает ошибкой, платформа будет повторять попытки, а потом зафиксирует сбой — и событие потеряется.

## Какие события передавать в первую очередь

Не все события одинаково полезны. Приоритет расставляем по деньгам: сначала те, на которых завязана измеримая механика.

**Полные статусы заказа.** Недооцененный пласт. Заказ лежит в пункте выдачи и его не забирают — цепочка «заберите, он ждет до пятницы» поднимает выкупаемость. Заказ выдан — через три дня уходит просьба оставить отзыв. Возврат — запускается сценарий с предложением обмена. Все это работает, только если статусы доезжают из ERP.

**Офлайн-продажи.** Без чеков с касс RFM-сегментация считается по половине покупок. Клиент, который каждый месяц покупает в рознице, для Mindbox выглядит спящим — и получает реактивационную цепочку со скидкой, которую вы дарите зря.

**События мобильного приложения.** Через SDK или server-to-server: регистрация, добавление в избранное, незавершенное действие. На них строятся пуши и In-App сценарии.

**Сервисные события.** Для сервисных компаний и подписочных моделей это ядро: окончание подписки, приближение ТО, дедлайн по документам. Письмо «ваша страховка заканчивается через две недели» — одна из сильных механик, и держится она целиком на кастомном событии.

**Сигналы извне.** Товар из избранного появился в наличии, цена снизилась, пропущенный звонок от клиента. Источники разные, схема одна: внешняя система дергает операцию, Mindbox запускает сценарий.

## Где ломается обмен: типичные точки отказа

Самая частая поломка — дубли. Сайт отправил заказ, не дождался ответа из-за таймаута и отправил повторно. Для заказов это лечится идентификатором: повторный вызов с тем же externalId обновляет заказ, а не создает новый. Для кастомных операций такой защиты нет — контроль дублей остается на вашей стороне.

Вторая классика — рассинхрон идентификаторов. Сайт привязывает заказ к email, 1С — к номеру телефона, касса — к номеру карты лояльности. В Mindbox один человек живет как три разных клиента: история покупок рвется, сегменты едут, персонализация мажет мимо.

Третья группа проблем — техническая мелочевка с тяжелыми последствиями. Даты без таймзоны, из-за чего письмо «ваш заказ ждет» приходит ночью. Отсутствие очереди на стороне отправителя: при пиковой нагрузке события упираются в лимиты API и молча теряются. Импорт исторических заказов боевой операцией «Создать заказ» — и клиентам летят триггерные письма за покупки двухлетней давности. Для истории есть отдельный механизм импорта, который не запускает сценарии.

> Рекорд по дублям — клиент, у которого сайт после таймаута переотправлял заказ до трех раз. Каждый заказ считался трижды, RFM разъехался, сегмент VIP раздулся вдвое. Маркетинг радовался росту выручки триггеров, пока финансисты не спросили, откуда расхождение с кассой.
>
> — Валерия Старостина, CRM-маркетолог, ClientCore

**Норма**

- повторная отправка с тем же идентификатором заказа обновляет его
- отправитель держит очередь и дожимает события ретраями при ошибках и таймаутах
- даты передаются с таймзоной, идентификаторы клиента едины во всех системах

**Red flag**

- событие уходит один раз, ответ сервера никто не проверяет
- на сайте клиент — это email, в 1С — телефон, на кассе — номер карты
- исторические продажи гонятся через боевую операцию, триггеры отрабатывают на старые заказы

## Как диагностировать потерю событий

Первый инструмент — журнал обращений к API в админке Mindbox. Там видно, какие вызовы приходили, с какими параметрами и чем закончились: ошибки валидации, неверный ключ, неизвестная операция. Если событие есть в вашей системе, но его нет в журнале — оно просто не отправилось, и копать надо на стороне источника.

Второй — сверка по количеству. Выгружаем заказы из ERP и из Mindbox за одинаковый период и считаем расхождение. Такую сверку мы делаем на каждом аудите: например, для Tripster аудит CRM-маркетинга показал, где на самом деле теряется выручка ([кейс](https://clientcore.ru/blog/articles/otzyv-tripster-o-clientcore-audit-crm-marketing-mindbox)) — и заметная часть таких находок почти всегда лежит в данных, которые не доезжают до платформы.

Третий — алерты. Если по событию «заказ выдан» в обычный день приходит 300 вызовов, а вчера пришло 12, что-то сломалось. Без алерта это обнаружат через месяц, по упавшей выручке триггеров.

> Сверка — дело одного вечера. Расхождение в пределах 2–3% — это отмены и тестовые заказы, жить можно. Больше 5% — ищем, на каком статусе теряются. И чаще всего виноват не API, а очередное обновление 1С, после которого выгрузка молча отвалилась.
>
> — Валерия Старостина, CRM-маркетолог, ClientCore

## Как внедрять, чтобы не пришлось переделывать

Начинаем с карты событий: таблица, где на каждое событие указаны источник, идентификатор клиента, набор полей и механика, которая на нем завязана. Карту заполняет маркетолог вместе с разработчиком. Если отдать интеграцию чистым технарям «по документации», получите события, у которых названия и поля не совпадают с тем, что ждут триггерные сценарии, — и все переделывается.

Дальше — тестовый проект. Mindbox предоставляет песочницу: там отлаживаются операции, проверяются дубли и форматы, и только потом обмен переключается на боевую базу. Финальный шаг — мониторинг: алерты на падение числа событий и регулярная сверка с источниками.

Когда обмен отлажен, ручной надзор ему не нужен. Для Urbantiger мы выстроили CRM-процесс, который работает без ежедневного контроля ([кейс](https://clientcore.ru/blog/articles/otzyv-urbantiger-o-clientcore-crm-kommunikacii)) — и надежная передача событий там один из фундаментов.

**Норма**

- карта событий согласована маркетингом до начала разработки
- запуск на тестовом проекте, потом боевой
- после релиза стоят алерты на аномалии в потоке событий

**Red flag**

- ТЗ разработчику писали без участия маркетолога
- тестирование на боевой базе «по-быстрому»
- настроили и забыли — про мониторинг вспомнили, когда выручка уже упала

> **Читайте также:** [Расчет времени отправки в Mindbox: как ИИ-тайминг влияет на выручку рассылок](https://clientcore.ru/blog/articles/raschet-vremeni-otpravki-v-mindbox-kak-ii-tayming-vliyaet-na-vyruchku-rassylok)

---

[Открыть статью на сайте](https://clientcore.ru/blog/articles/mindbox-api-i-vebhuki-kak-peredavat-sobytiya-kotorye-ne-pokryvayut-standartnye-integracii)