Интеграция API Определение исходного оператора: рабочие процессы для исходного оператора и типа линии

Интегрируйте API Определение исходного оператора для проверки исходного оператора, типа линии и географии нумерации с помощью REST-эндпоинтов в реальном времени и обработки пакетных файлов.

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

Основные данные о распределении и атрибуты типа линии

Телекоммуникационные планы нумерации следуют международным стандартам, таким как ITU-T Recommendation E.164, который определяет глобальные планы нумерации с кодами стран и номерами абонентов. В рамках этих структур регулирующие органы назначают определенные блоки номеров сетевым операторам. CarrierLookup предоставляет доступ к этим фундаментальным свойствам через свою функцию определения исходного оператора.

Схема ответа организует телекоммуникационный контекст в отдельные точки данных:

• carrier: провайдер связи, которому изначально был назначен диапазон нумерации.
• underlying_carrier: провайдер базовой инфраструктуры, связанный с назначенным диапазоном.
• number_type: классификация линии, например, мобильная или стационарная.
• country_code: международный префикс набора номера, соответствующий территории распределения.
• region и city: административная географическая территория, указанная в плане распределения нумерации.

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

Интеграция для одиночных и множественных проверок в реальном времени

Интеграция запросов в реальном времени позволяет бэкенд-системам оценивать номера телефонов синхронно во время приема заявок или рабочих процессов проверки. Запросы проходят аутентификацию с использованием HTTP-заголовка X-API-Key, отправляемого с защищенного сервера приложений.

Рабочий процесс проверки одного номера

Чтобы проверить отдельный идентификатор, отправьте запрос на POST /api/v1/check. Полезная нагрузка требует номер телефона, отформатированный в соответствии с международным стандартом E.164, с ведущим знаком «плюс», кодом страны и цифрами абонента без пробелов и знаков препинания.

После обработки сервер возвращает JSON-ответ, содержащий code, msg и плоский объект data. Полезная нагрузка данных содержит service_type, identifier, carrier, underlying_carrier, number_type, country_code, region и city. Дополнительные поля распределения могут быть пустыми, если конкретные детали не указаны для данного диапазона, однако проверка регистрируется как завершенная.

Рабочий процесс синхронной множественной проверки

Для пакетов, требующих немедленной оценки, организации вызывают POST /api/v1/batch-check. Этот эндпоинт обрабатывает несколько номеров E.164 синхронно в рамках одного вызова. Ответ возвращает высокоуровневые метрики выполнения вместе с упорядоченным массивом:

• service_type: подтверждает выполненный сервис проверки.
• total: количество отправленных идентификаторов.
• succeeded: количество успешно оцененных элементов.
• failed: количество элементов, при обработке которых возникли ошибки.
• results: упорядоченная коллекция элементов, каждый из которых содержит identifier и exists.

В этом синхронном множественном ответе значение exists=false указывает на то, что стандартная запись о распределении не была возвращена, а не на то, что линия отключена или неверно сформирована.

Рабочий процесс асинхронной обработки пакетных файлов

При обработке обширных списков телекоммуникационных записей команды используют асинхронный сервис carrier_batch. Этот рабочий процесс обрабатывает файловые отправки без необходимости поддерживать клиентские соединения открытыми.

Отправка и структура задачи

Отправляйте пакетные запросы через POST /api/v1/bulk-tasks с использованием multipart form data. Загрузка требует файл в формате TXT или CSV, содержащий один идентификатор на строку, а также указанный параметр страны ISO. К размерам задач применяются соответствующие лимиты для каждого продукта, и читатели могут ознакомиться с текущими операционными параметрами в официальной документации API.

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

Жизненный цикл задачи и получение результатов

Клиенты отслеживают прогресс пакета, запрашивая GET /api/v1/bulk-tasks/{id}. График опроса должен следовать размеренному ритму, проверяя статус не чаще одного раза в 30 секунд. Жизненный цикл задачи проходит через три формальных состояния:

• processing: файл проходит системную оценку.
• failed: задача столкнулась с ошибкой выполнения или не прошла требования к приему.
• success: оценка диапазона завершена, и результат доступен.

Когда задача завершается со статусом success, эндпоинт предоставляет один CSV-файл. Структура вывода содержит семь стандартизированных заголовков: identifier, carrier, underlying_carrier, number_type, country_code, region и city. Идентификатор в этом файле представлен в виде цифр с кодом страны, без символов «плюс».

Операционные лимиты и спецификации покрытия

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

Географическое покрытие имеет свои региональные правила. Одиночные проверки номеров в реальном времени поддерживают запросы по материковому Китаю (+86), Гонконгу (+852) и Макао (+853) для умеренных операционных объемов. Однако пакетные файлы не принимают номера из этих трех регионов. Статус покрытия для Тайваня (+886) остается неподтвержденным.

Чтобы проверить статус аккаунта перед выполнением проверок, запросите GET /api/v1/balance для получения текущего баланса без расходования лимитов. Кроме того, новые зарегистрированные пользователи могут связаться с поддержкой, чтобы получить 100 бесплатных проверок для тестирования своих рабочих процессов интеграции с производственными эндпоинтами.

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

Как API обрабатывает номера, которые были перенесены между сетями?

CarrierLookup сообщает оператора, которому диапазон нумерации был изначально назначен административными органами. В телекоммуникациях потребители могут менять провайдеров, сохраняя свой номер, как описано в Porting: Keeping Your Phone Number When You Change Providers. Следовательно, поле carrier отражает это историческое распределение диапазона, а не текущего обслуживающего оператора, сохраняя неизменный структурный атрибут для анализа нумерации.

Что отличает множественную проверку в реальном времени от пакетного сервиса?

Эндпоинт для множественной проверки в реальном времени POST /api/v1/batch-check оценивает номера синхронно, возвращая немедленный JSON-ответ с service_type, total, succeeded, failed и упорядоченными результатами, показывающими identifier и логическое значение exists. Напротив, пакетный сервис обрабатывает списки асинхронно из отправленных CSV или TXT файлов. Как только фоновый анализ завершается, пакетные задачи предоставляют загружаемый CSV-файл, содержащий полные столбцы распределения, включая carrier, underlying_carrier, number_type, country_code, region и city.

Указывают ли поля region и city физическое местоположение устройства?

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

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

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

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