Нормализация телефонных номеров для SMS: формат E.164 и правила хранения

Телефонный номер может попасть в CRM как 8 999 123-45-67, +7 (999) 123-45-67, 89991234567 или строка с добавочным номером. Для человека эти варианты выглядят одинаково, но SMS-интеграция видит разные значения. Без нормализации появляются дубли контактов, ошибки маршрутизации и неверные результаты поиска по истории отправок.

Нормализация — это преобразование пользовательского ввода в единое каноническое представление. Для международных номеров обычно ориентируются на план нумерации ITU-T E.164: код страны и национальная часть, не более 15 цифр. Стандарт задаёт структуру номера, но не заменяет проверку того, что конкретный номер существует и доступен. Эти задачи разделены: сначала формат, затем валидация базы перед рассылкой.

Почему удаления пробелов недостаточно

Простой фильтр «оставить только цифры» превращает +7 999... в 7999..., но не отвечает на главный вопрос: какой код страны подразумевал пользователь. Локальное значение 9991234567 нельзя надёжно дополнить кодом без контекста страны. Начальная 8 в российском интерфейсе часто является префиксом набора, а в другой стране может быть частью номера.

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

Канонический формат

В базе удобно хранить номер в виде + и последовательности цифр: +79991234567. Пробелы, скобки и дефисы остаются лишь частью отображения. Каноническое значение используется для дедупликации, стоп-листов, поиска, лимитов частоты и вызова SMS API.

Полезно разделить поля:

• phone_e164 — нормализованный номер;
• phone_raw — исходный ввод для диагностики, если его хранение оправдано;
• country_code — определённая страна или регион;
• parse_status — результат разбора и причина отказа;
• verified_at — момент отдельной проверки владения или доступности, если она была.

Не следует считать verified_at вечной гарантией. Номера отключаются и переходят новым владельцам, поэтому актуальность проверки зависит от сценария.

Безопасный конвейер обработки

Надёжная последовательность выглядит так:

1. Принять строку как текст, не как число. Иначе можно потерять + или ведущие нули.
2. Удалить разрешённые символы оформления, но отдельно обработать добавочный номер.
3. Определить страну из явного +код либо из доверенного контекста формы.
4. Разобрать номер библиотекой, которая знает национальные планы нумерации.
5. Проверить возможную длину и структуру для выбранной страны.
6. Сохранить каноническое значение и статус разбора.
7. Перед массовой отправкой применить дополнительные проверки базы и стоп-листа.

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

Формат не равен существованию

Структурно корректный номер может быть не выделен, отключён или недоступен для SMS. И наоборот, перенос номера между операторами не меняет его E.164-представление. Поэтому нельзя определять текущего оператора только по префиксу; для этого используют актуальные данные MNP и при необходимости HLR-проверку.

Проверка владения — ещё одна отдельная операция. Если пользователь подтвердил номер кодом, это доказывает доступ к нему в конкретный момент, но не разрешение на любую рекламную рассылку. Согласия и назначение сообщения учитываются независимо.

Дедупликация и стоп-листы

Сравнивать контакты нужно по каноническому значению. Иначе один и тот же адресат может попасть в сегмент несколько раз из-за разных скобок и префиксов. То же правило относится к стоп-листам SMS: отказ должен блокировать все варианты записи одного номера.

При миграции старой базы сначала выполните преобразование в preview-режиме. Отдельно посчитайте неразобранные значения и коллизии, когда несколько карточек получили один phone_e164. Автоматически объединять такие карточки нельзя: у них могут различаться договоры, согласия и история взаимодействий.

Что передавать в SMS API

Уточните контракт конкретного провайдера. Одни API принимают значение с +, другие требуют только цифры. Внутренняя модель при этом должна оставаться единой: преобразование в формат провайдера выполняет адаптер непосредственно перед запросом.

Не храните провайдерский вариант как главный. Иначе при смене шлюза формат распространится по CRM, очередям и отчётам, а миграция потребует массовой переделки данных.

Ошибки, которые стоит показывать пользователю

Сообщение «неверный номер» слишком общее. Для формы полезно различать: не выбрана страна, недопустимые символы, слишком короткая или длинная национальная часть, добавочный номер в поле мобильного телефона. При импорте CSV те же причины лучше вернуть отдельным отчётом со строками, а не молча исправлять догадками.

В журнале не обязательно сохранять полный номер. Для диагностики часто достаточно маски, внутреннего contact ID и хеша канонического значения. Это снижает объём персональных данных в логах.

Чек-лист внедрения

• выбран единый внутренний формат с кодом страны;
• регион по умолчанию задаётся только в известном контексте;
• исходный ввод не превращается в число;
• добавочные номера не попадают в адрес SMS;
• библиотека планов нумерации регулярно обновляется;
• дедупликация и стоп-листы работают по каноническому значению;
• коллизии старой базы выносятся на ручную проверку;
• адаптер провайдера сам преобразует номер под его API;
• формат, доступность, владение и согласие не смешиваются в один флаг.

Итог

Нормализация телефонных номеров — базовый слой SMS-интеграции. Единое E.164-представление делает предсказуемыми дедупликацию, лимиты, стоп-листы и миграцию между провайдерами. Но корректная строка ещё не доказывает существование номера, владение им или право отправлять рекламу: каждую из этих проверок нужно вести отдельно.