API определения оператора: добавление контекста об операторе и типе линии в бэкенд регистрации

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

API определения оператора в процессе регистрации по номеру телефона — это серверный вызов, который принимает предоставленный номер и возвращает оператора, к которому изначально был отнесен этот диапазон, тип номера и географию распределения. С помощью CarrierLookup бэкенд нормализует номер в формат E.164, отправляет его на POST /api/v1/check с использованием API-ключа, хранящегося на сервере, и сохраняет результат рядом с учетной записью в качестве контекста для проверки. Оптимальное место для этого вызова — после принятия формы и до принятия решения о маршрутизации или ручной проверке, чтобы медленный или неопределенный результат поиска никогда не блокировал завершение регистрации пользователем.

Поиск по номеру телефона vs определение оператора по IP

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

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

Где должен находиться вызов API определения оператора при регистрации

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

1. Примите форму. Проверьте, что поле телефона заполнено и имеет правдоподобный формат.
2. Нормализуйте в E.164. Преобразуйте ввод в формат с символом «плюс», кодом страны и цифрами абонента без пробелов, как определено в ITU-T E.164. Синхронные проверки не требуют отдельного выбора страны, так как код страны внутри номера уже содержит эту информацию.
3. Создайте учетную запись в состоянии ожидания контекста. Не держите HTTP-ответ открытым в ожидании результата поиска, если ваша страница регистрации имеет жесткие ограничения по задержке.
4. Вызовите POST /api/v1/check из задания или воркера для одного номера.
5. Сохраните результат с временем поиска и статусом, таким как «завершен», «пусто» или «не определено».
6. Примените свои правила. Маршрутизируйте учетную запись, добавьте ее в очередь на ручную проверку или не предпринимайте никаких действий.

Выполнение вызова в очереди позволяет сохранить отзывчивость процесса регистрации и обеспечивает естественную среду для повторных попыток.

Что сохранять из каждого результата поиска

Завершенная проверка описывает распределение номера простыми терминами: исходный оператор, базовый оператор (если бренд работает в другой сети), тип номера (например, мобильный или фиксированный), код страны, а также регион и город, привязанные к диапазону. Сохраняйте их в полях, названия которых отражают их суть, например original_carrier вместо carrier и allocation_region вместо location. Регион и город описывают место, где был распределен диапазон, а не текущее местоположение пользователя.

Сохраняйте рядом с ними еще три значения:

• Временная метка поиска, чтобы проверяющие знали, насколько актуален контекст.
• Результат: завершено со значениями, завершено с пустыми значениями или не определено.
• Отправленные входные данные, точная строка E.164, что упрощает последующие аудиты и повторные проверки.

Завершенный результат может законно вернуться с пустыми полями оператора. Сохраняйте это как «завершено-пусто», а не как сбой и не как доказательство чего-либо в отношении учетной записи. Это различие важно, когда кто-то создает дашборд на основе этих полей.

Обработка таймаутов, неопределенных результатов и отклоненных входных данных

Три типа сбоев требуют разных путей обработки кода, и их объединение — самая распространенная ошибка интеграции.

Публичный API документирует лимиты времени ожидания для одиночных и множественных запросов, а также ограниченное количество общих слотов для синхронных запросов на учетную запись. Держите параллелизм ваших воркеров ниже этого общего бюджета, а не отправляйте по одному запросу на каждую регистрацию параллельно во время пиковых нагрузок. За неудачные или неопределенные проверки плата не взимается, поэтому политика повторных попыток не должна беспокоиться о двойном списании средств, но она должна ограничивать количество попыток (например, три попытки в течение часа), а затем оставлять учетную запись со статусом «не определено» для проверяющего.

Хранение API-ключа на сервере

REST API проходит аутентификацию с помощью заголовка X-API-Key, который должен отправляться только с доверенного сервера. Никогда не вызывайте поиск из JavaScript в браузере или мобильного приложения; любой может извлечь ключ, отправленный клиенту, и потратить ваш баланс.

Практические меры контроля в соответствии с OWASP Secrets Management Cheat Sheet:

• Загружайте ключ из менеджера секретов или хранилища секретов платформы развертывания, а не из исходного кода.
• Предоставьте доступ к нему только воркеру, выполняющему поиск.
• Ротируйте ключ по расписанию и немедленно после подозрения на утечку.
• Никогда не записывайте ключ или полные заголовки запросов в логи приложения.
• Следите за балансом учетной записи с помощью GET /api/v1/balance, который считывает баланс без списания средств, и настройте оповещения о резких падениях, не соответствующих объему регистраций.

Также защитите сам триггер. Ограничьте частоту запросов к вашему собственному эндпоинту регистрации, чтобы автоматизированные отправки форм не превратились в поток платных проверок.

Использование результата в маршрутизации и проверке

Относитесь к оператору и типу номера как к входным данным для правил, которыми управляет ваша команда, а не как к окончательным вердиктам. Примеры, которые используют команды:

• Тесты маршрутизации. Группируйте новые учетные записи по исходному оператору и сравнивайте эффективность различных провайдеров обмена сообщениями для каждой группы в ваших собственных метриках.
• Очереди на проверку. Отправляйте учетные записи, тип номера которых не соответствует ожиданиям продукта (например, номер фиксированной линии в приложении, ориентированном на мобильные устройства), проверяющему с приложенным контекстом.
• Качество данных. Отмечайте регистрации, где код страны номера и страна, выбранная в форме, не совпадают, чтобы служба поддержки могла запросить исправление.

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

Часто задаваемые вопросы

Как команды могут проверить множество существующих учетных записей, зарегистрированных до интеграции?

Используйте POST /api/v1/batch-check для накопленной базы в группах до 100 номеров E.164 за запрос. Результаты возвращаются в порядке ввода, и каждая строка указывает, существует ли нормальный результат. Строки без нормального результата следует пометить для повторной попытки позже, а не записывать как пустые. Очень большие исторические списки лучше обрабатывать как асинхронную задачу массовой обработки файлов, отправляемую по странам.

Как бэкенд может избежать оплаты за один и тот же номер дважды?

Используйте кэш, ключом в котором является нормализованная строка E.164, с указанием времени поиска. Когда номер уже имеет завершенный результат недавней проверки, используйте его повторно вместо нового вызова API. Контекст распределения меняется медленно, поэтому многие команды обновляют данные только при редактировании записи или когда сохраненный результат старше выбранного ими периода, например нескольких месяцев.

Как разработчики могут протестировать интеграцию перед запуском?

Направьте воркер на конфигурацию для тестирования (staging) с собственным API-ключом и небольшим балансом, затем запустите скриптовый набор случаев: валидный мобильный номер, номер фиксированной линии, ввод, который не проходит нормализацию E.164, и принудительный таймаут. Убедитесь, что каждый путь записывает ожидаемый статус результата и что в логах не появляется ключ или заголовок, прежде чем переключать производственный трафик.

Узнать больше

Выберите информацию о продукте, которая соответствует следующему шагу в вашем рабочем процессе.

• Просмотреть документацию по продукту →
• Связаться с командой →