API определения оператора связи: один запрос, один результат по исходному оператору

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

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

Что возвращает API определения оператора связи

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

Завершенный результат для одного номера, описанный простыми словами, содержит:

• Исходный оператор: оператор, которому был выделен диапазон.
• Базовый оператор: сеть, стоящая за этим оператором, если значение доступно.
• Тип номера: тип диапазона, например, мобильный или фиксированный.
• Код страны, регион и город: место, где был распределен диапазон, а не текущее местоположение человека или устройства.

Используйте эти данные как контекст распределения для группировки, тестирования маршрутизации и проверки. Результат определения оператора не подтверждает, что номер активен, может принимать вызовы или SMS, либо принадлежит конкретному лицу.

Отправка одного номера в API определения оператора связи

Маршрут для одного номера — это короткий синхронный запрос. Типичная интеграция состоит из пяти шагов:

1. Храните ключ на доверенном сервере. REST API проходит аутентификацию с помощью заголовка X-API-Key. Вызывайте его со своего бэкенда или планировщика задач, но никогда не делайте этого из кода браузера или мобильного приложения, где ключ может быть скопирован.
2. Нормализуйте ввод до формата E.164. План ITU-T E.164 определяет международный формат. CarrierLookup ожидает знак «плюс», код страны и номер абонента без пробелов, тире или скобок. Британский номер 020 7946 0000 превращается в +442079460000. Библиотеки, такие как libphonenumber, могут анализировать локальные форматы, если известна страна записи.
3. Отправьте запрос на POST /api/v1/check. Один номер на запрос. Отдельный выбор страны не требуется, так как код страны является частью номера.
4. Дождитесь синхронного ответа. Результат возвращается в том же ответе; опрашивать систему не нужно.
5. Сохраните результат с датой проверки. Данные о распределении стабильны для диапазона, но запись времени выполнения каждой проверки упрощает аудит.

Если ввод отклонен из-за формата, исправьте номер и отправьте повторно. Отклонение по формату не дает информации об операторе.

Чтение завершенных, пустых и неопределенных результатов

Самая распространенная ошибка интеграции — считать три разных исхода одним. Сначала выполняйте ветвление по бизнес-коду, а затем по значениям.

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

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

Обработка тайм-аутов, параллелизма и баланса

Публичный API документирует небольшой набор элементов управления использованием, а не квоту в минуту. Учетная запись имеет пять общих слотов для параллельных синхронных запросов, и одновременно может выполняться только один мультизапрос. Для одиночных запросов установлен документированный предел тайм-аута в 60 секунд, поэтому установите тайм-аут вашего HTTP-клиента чуть выше этого значения, а не на несколько секунд.

Практические рекомендации:

• Используйте очередь вместо перегрузки. Если ваша задача регистрации или импорта создает всплески, используйте небольшой пул воркеров, чтобы одновременно выполнялось не более пяти проверок.
• Повторяйте неопределенные результаты с интервалами. Используйте задержку и ограничение на количество повторов; частые немедленные повторы редко помогают.
• Логируйте бизнес-код и сообщение. Они объясняют причины сбоев гораздо лучше, чем просто HTTP-статус.
• Проверяйте баланс без затрат. GET /api/v1/balance возвращает остаток баланса бесплатно, что подходит для предварительной проверки перед запуском большой задачи.

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

Когда переходить к POST /api/v1/batch-check или файловым задачам

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

• POST /api/v1/batch-check принимает от 1 до 100 номеров в формате E.164 в одном синхронном запросе, причем номера могут быть из разных стран. Результаты возвращаются в том же порядке, что и ввод, поэтому вы можете сопоставить каждую строку по позиции. Каждая строка содержит флаг exists; false означает отсутствие нормального результата для этой строки, а не то, что номер недействителен или отключен. Если мультизапрос превышает время ожидания, весь запрос завершается с ошибкой без частичных результатов, а зарезервированная сумма возвращается в полном объеме, поэтому сохраняйте пакеты умеренными и повторяйте пакет целиком.
• Панель управления принимает до 500 номеров для синхронной мультипроверки без написания кода.
• Файловые задачи (Bulk) подходят для целых списков: асинхронная загрузка файла TXT или CSV для одной выбранной страны, который опрашивается до тех пор, пока не будет готов единый CSV-файл. Применяются лимиты для каждого продукта; см. документацию API.

Те же проверки доступны для ИИ-ассистентов через официальный эндпоинт MCP, который охватывает одиночные и мультипроверки, но не файловые задачи.

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

Как командам отличить пустой результат по оператору от неудачной проверки?

Проверяйте бизнес-код перед чтением любых значений. Код успеха с пустыми полями оператора — это завершенная проверка, которую следует сохранить как «недоступно». Ненулевой код означает, что проверка была неопределенной или не удалась; ничего не следует записывать как результат, а запись можно повторно проверить позже или отправить на ручную проверку. Разделение этих двух путей позволяет избежать пометки корректных записей как отсутствующих данных.

Показывает ли API определения оператора сеть, которую номер использует сегодня?

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

Должен ли фронтенд вызывать API определения оператора напрямую?

Не должен. Заголовок X-API-Key предоставляет доступ к балансу учетной записи, поэтому вызовы должны выполняться на доверенном сервере. Распространенный шаблон — отправка номера телефона фронтендом на ваш собственный бэкенд, который нормализует его до E.164, вызывает POST /api/v1/check, сохраняет результат и возвращает только то, что необходимо отобразить в интерфейсе.

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

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

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