Миграция между провайдерами сообщений без дублей и потери статусов
Пошаговая миграция SMS и бизнес-уведомлений: единая модель статусов, стабильные идентификаторы, теневой тест, поэтапное переключение и откат.
Содержание
Смена провайдера сообщений выглядит как замена URL и ключа, пока не появляются повторные SMS, потерянные статусы и разные трактовки ошибки. Безопасная миграция разделяет приём бизнес-события, маршрутизацию, отправку и учёт результата. Тогда трафик можно переводить постепенно и возвращать без изменения вызывающих систем.
Зафиксируйте текущий контракт
Составьте инвентаризацию типов сообщений, отправителей, шаблонов, стран, кодировок, лимитов и окон доставки. Отдельно перечислите синхронный ответ API, промежуточные состояния и финальные DLR. Одинаковые слова у двух провайдеров могут означать разные этапы.
Внутренняя модель не должна копировать словарь одного поставщика. Обычно достаточно состояний вроде queued, accepted, delivered, failed, expired и unknown, а оригинальный код сохраняется рядом для диагностики. Подход к нормализации подробнее разобран в статье о метриках доставки и DLR.
Стабилизируйте идентификатор сообщения
Бизнес-событие получает внутренний неизменяемый ID до выбора маршрута. Попытка у конкретного провайдера имеет отдельный ID и ссылается на исходное сообщение. Это позволяет отличить повтор технического запроса от новой коммуникации.
Идемпотентность нельзя строить только на provider message ID: он появляется после приёма и меняется при переключении. В журнале нужно связать бизнес-событие, попытку, маршрут, ответ API и каждый callback.
Проверьте нового провайдера до реального трафика
Начните с контрактных тестов и разрешённых тестовых адресатов. Проверьте кодировку, сегментацию, sender ID, тайм-ауты, ограничения частоты, подпись callback, порядок статусов и повторную доставку webhook.
Приём статусов стоит заранее привести к правилам из руководства о надёжных DLR webhook: подпись, защита от replay, идемпотентность и обработка событий не по порядку должны одинаково работать с обоими провайдерами.
Теневой режим не означает двойную отправку клиенту. Один и тот же подготовленный запрос можно пропустить через валидатор нового адаптера без финального submit либо использовать специальный тестовый контур провайдера. Цель — сравнить преобразование и решения маршрутизации, не создавая второе сообщение.
Переключайте измеримыми долями
Порядок может выглядеть так:
- служебные и тестовые номера;
- один некритичный тип уведомлений;
- небольшой процент production-трафика;
- отдельный регион или отправитель;
- основная нагрузка после полного окна наблюдения.
На каждом этапе сравнивайте долю принятых сообщений, доставку в целевое время, задержку по перцентилям, распределение ошибок, число сегментов и бизнес-конверсию. Среднее значение скрывает длинный хвост, поэтому p95 и p99 важнее одного общего числа.
Не отправляйте неизвестный результат повторно вслепую
Если запрос завершился тайм-аутом, сообщение могло быть принято. Немедленная отправка через нового поставщика создаст дубль. Сначала используйте idempotency key или запрос статуса, затем отложенную сверку. Правила управляемого каскада описаны в материале о failover SMS-маршрутов.
Откат — это маршрут, а не восстановление кода
Старый адаптер должен оставаться готовым в течение согласованного периода. Откат переключает только новые события; уже принятые новым провайдером продолжают получать статусы через его webhook. Иначе часть сообщений потеряет финальное состояние.
После полного переноса оставьте сверку двух контуров до истечения максимального TTL сообщения. Затем отзовите старые ключи, закройте callbacks, обновите документацию и сохраните итоговые метрики. Миграция завершена не в момент переключения 100% трафика, а когда ни одно незавершённое сообщение больше не зависит от старого контура.
