Пакетная проверка номеров телефонов: синхронные мультизапросы против массовых файловых задач

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

Пакетная проверка номеров телефонов в CarrierLookup может выполняться одним из двух способов. Синхронный мультизапрос позволяет отправить до 100 номеров через API или до 500 через панель управления и получить упорядоченные результаты в том же ответе. Массовая файловая задача предполагает загрузку файла в формате TXT или CSV для одной выбранной страны, выполняется асинхронно и завершается получением одного CSV-файла для скачивания. Выбирайте мультизапрос для небольших групп и оперативных задач, а файловую задачу — для обработки больших списков целиком. Оба метода возвращают данные об исходном операторе и контексте распределения номера, а не текущего оператора после переноса (porting) и не сигнал доступности.

Два метода пакетной обработки, две разные задачи

Команды, ищущие решение для пакетной проверки номеров телефонов, часто полагают, что все инструменты работают одинаково. CarrierLookup намеренно предлагает два формата, и их смешение — самая распространенная ошибка при планировании.

Синхронный мультизапрос — это интерактивный вызов. Вы отправляете группу номеров в формате E.164, ожидаете ответа и получаете один упорядоченный результат. Номера в группе могут быть из разных стран, отдельный выбор страны не требуется.

Массовая файловая задача — это фоновый процесс. Вы подготавливаете одностолбцовый файл TXT или CSV, выбираете одну страну, отправляете его и возвращаетесь за результатом позже. Работа выполняется в фоновом режиме, а результатом является файл, а не тело ответа.

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

Как работает синхронный мультизапрос

Используйте POST /api/v1/batch-check с доверенного сервера, передавая API-ключ в заголовке X-API-Key. Панель управления предлагает аналогичный функционал в браузере для групп до 500 номеров.

Каждый номер должен быть записан в формате E.164: знак «плюс», код страны и номер абонента без пробелов и разделителей. Номер с неверным форматом будет отклонен из-за ошибки формата. Это проблема форматирования, которую нужно исправить, а не признак того, что у номера нет оператора.

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

Два момента заслуживают внимания:

• Результат, помеченный как несуществующий, означает, что для этого номера не удалось получить обычный ответ. Это не утверждение о том, что номер недействителен или отключен.
• Если весь запрос превышает время ожидания, он считается неудачным целиком. Частичные результаты не возвращаются, а полная сумма возвращается на ваш баланс.

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

Как работает массовая файловая задача

Используйте POST /api/v1/bulk-tasks с телом multipart. Поместите поле страны перед полем файла, так как порядок важен при отправке multipart. Затем отслеживайте прогресс с помощью GET /api/v1/bulk-tasks/{id}.

Задача может находиться в одном из трех состояний: processing, success или failed. Опрашивайте статус не чаще одного раза в 30 секунд. Более частые запросы увеличивают нагрузку, не ускоряя выполнение задачи, а время завершения не регламентировано, поэтому ориентируйтесь на статус, а не на время.

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

При успешном завершении вы скачиваете один CSV-файл, а не ZIP. Его столбцы: идентификатор, оператор, базовый оператор, тип номера, код страны, регион и город. В CSV идентификатор представлен цифрами с кодом страны без знака «плюс», поэтому нормализуйте свои ключи перед объединением файла с базой данных. Пустые ячейки означают, что значение недоступно.

Выбор в зависимости от размера списка, состава стран и рабочего процесса

Начинайте с анализа структуры ваших данных, а не с общего количества.

1. Смешанная группа номеров из разных стран, требующая немедленного ответа. Используйте синхронный мультизапрос. Файловая задача потребовала бы предварительного разделения списка по странам.
2. Большой список, относящийся преимущественно к одной стране. Используйте файловую задачу. Выберите страну, отправьте файл и позвольте системе предварительной обработки удалить дубликаты и посторонние номера.
3. Большой список с номерами из разных стран. Разделите его по кодам стран, затем отправьте по одной файловой задаче на каждую страну. Номера, которые не подходят под файл страны, можно обработать через мультизапросы порциями до 100 номеров.
4. Поштучная проверка при регистрации или вводе данных в CRM. Используйте проверку одного номера через POST /api/v1/check. Номера из материкового Китая, Гонконга и Макао поддерживаются только через проверку отдельных номеров в реальном времени при небольших объемах, поэтому направляйте их туда, а не в мультизапрос или файл.

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

Биллинг и проверка баланса для обоих методов

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

Файловая задача резервирует оценочную сумму при отправке, а затем списывает средства только за номера, по которым были получены результаты. Неиспользованная часть резерва или весь резерв в случае неудачной задачи возвращается на тот же баланс. Это сверка внутри вашего баланса, а не возврат средств за покупку.

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

Правильное чтение результатов

Независимо от выбранного метода, данные означают одно и то же. Оператор — это тот, которому изначально был выделен диапазон номеров. Это не сеть, обслуживающая номер сегодня, так как перенос номера (porting) может изменить обслуживающую сеть без изменения исходного выделения. Базовый оператор и тип номера добавляют контекст, а регион и город описывают географию выделения, а не текущее местоположение человека или устройства.

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

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

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

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

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

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

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

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

Опрашивайте статус задачи не чаще одного раза в 30 секунд и останавливайтесь, когда состояние станет success или failed. Время завершения не регламентировано, поэтому стройте рабочий процесс вокруг статуса. При успехе скачайте единственный CSV-файл и нормализуйте идентификатор перед объединением с существующими записями.

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

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

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