Чем миндбокс вебхуки отличаются от API?

Строго говоря, это направления одного обмена. API — когда внешняя система сама вызывает операции Mindbox и передает данные внутрь. Вебхуки в узком смысле — исходящие: Mindbox дергает ваш URL при срабатывании события или шага сценария, например передает задачу в колл-центр или конверсию в рекламный кабинет. На практике «вебхуками» называют и входящие вызовы, поэтому в ТЗ лучше прямо писать: кто инициатор и какая операция вызывается.

Можно ли передать кастомные события без разработчика?

Полностью без разработчика — нет, но его роль бывает минимальной. Для 1С есть готовые модули, которые закрывают типовые статусы заказов, и настройка ложится на штатного 1С-специалиста по понятному ТЗ. Для нестандартных источников — собственного бэкенда, мобильного приложения — нужен код: вызов операции, обработка ответа, очередь. На стороне Mindbox кастомную операцию и сценарий собирает CRM-маркетолог без программирования.

Сколько времени занимает такая интеграция?

Одна кастомная операция с готовым источником — вопрос нескольких дней с тестированием. Полноценный обмен: статусы заказов, офлайн-продажи, идентификация, очередь — обычно 2–6 недель, и основное время съедает не API, а согласование карты событий и правки на стороне источника.

События после запуска дублируются. Что проверять в первую очередь?

Идентификатор сущности: для заказов повтор с тем же externalId должен обновлять запись. Если дубли все равно плодятся — смотрите, не генерирует ли источник новый идентификатор при каждой отправке. Дальше — логика ретраев: корректно ли отправитель обрабатывает таймауты, не шлет ли повтор при успешном, но медленном ответе. Журнал обращений к API в Mindbox покажет оба вызова и поможет понять, на чьей стороне проблема.

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

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

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

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

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

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

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

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

Как устроен обмен через 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 и молча теряются. Импорт исторических заказов боевой операцией «Создать заказ» — и клиентам летят триггерные письма за покупки двухлетней давности. Для истории есть отдельный механизм импорта, который не запускает сценарии.

Норма

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

Red flag

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

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

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

Второй — сверка по количеству. Выгружаем заказы из ERP и из Mindbox за одинаковый период и считаем расхождение. Такую сверку мы делаем на каждом аудите: например, для Tripster аудит CRM-маркетинга показал, где на самом деле теряется выручка (кейс) — и заметная часть таких находок почти всегда лежит в данных, которые не доезжают до платформы.

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

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

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

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

Когда обмен отлажен, ручной надзор ему не нужен. Для Urbantiger мы выстроили CRM-процесс, который работает без ежедневного контроля (кейс) — и надежная передача событий там один из фундаментов.