API для массового определения оператора: отправка файла и получение CSV

Руководство для разработчиков по работе с массовыми задачами CarrierLookup: отправка файлов в формате TXT или CSV с указанием страны, опрос статуса и чтение итогового CSV-файла.

API для массового определения оператора CarrierLookup работает как асинхронная файловая задача. Отправьте multipart-запрос на POST /api/v1/bulk-tasks, указав поле страны перед файлом, а затем считывайте статус через GET /api/v1/bulk-tasks/{id} не чаще одного раза в 30 секунд, пока состояние не примет значение success или failed. Успешно выполненная задача возвращает один CSV-файл для скачивания, содержащий данные об исходном операторе, базовом операторе, типе номера и географии распределения. Этот метод подходит для обработки больших списков номеров одной страны. Применяются ограничения для каждого продукта, поэтому сначала ознакомьтесь с ними в документации API.

Подготовка файла перед вызовом API

Чистый файл экономит больше времени, чем любая логика повторных попыток. Массовый метод принимает одностолбцовые файлы TXT или CSV, где на каждой строке указан один номер с кодом страны. Формат XLSX не поддерживается, поэтому сначала экспортируйте электронные таблицы в простой текст или CSV.

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

Краткая процедура подготовки:

1. Экспортируйте один столбец и удалите заголовки или примечания.
2. Приведите каждую строку к цифровому формату с кодом страны.
3. Разделите основной список по странам и создайте отдельный файл для каждой страны.
4. Сверьте файл с текущими ограничениями в документации API. Стандартный лимит размера файла, указанный там, может быть изменен сервисом в реальном времени, поэтому актуальное значение имеет приоритет.

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

Отправка задачи с помощью multipart-запроса

Отправляйте запрос POST /api/v1/bulk-tasks с доверенного сервера. Проходите аутентификацию через заголовок X-API-Key и никогда не раскрывайте ключ в коде браузера.

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

Пример вызова с помощью curl:

curl -X POST https://carrierlookup.online/api/v1/bulk-tasks \
  -H "X-API-Key: $CARRIERLOOKUP_API_KEY" \
  -F "country=GB" \
  -F "file=@uk_numbers.csv"

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

Опрос статуса задачи без перегрузки API

Считывайте статус с помощью GET /api/v1/bulk-tasks/{id}. Задача может находиться в одном из трех состояний: processing, success или failed.

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

import time, requests

def wait_for_task(task_ref, headers):
    while True:
        r = requests.get(f"https://carrierlookup.online/api/v1/bulk-tasks/{task_ref}", headers=headers, timeout=30)
        state = r.json()["data"]["status"]
        if state in ("success", "failed"):
            return state
        time.sleep(30)

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

Загрузка и чтение CSV

Когда состояние изменится на success, загрузите результат. Вы получите один CSV-файл, а не ZIP-архив. Он содержит идентификатор, оператора, базового оператора, тип номера, код страны, регион и город для номеров, по которым были получены результаты.

Три правила чтения:

• Идентификатор не содержит знака «плюс». Это просто цифры с кодом страны без пробелов. Приведите свои ключи к такому же формату перед объединением данных.
• Пустые ячейки означают «Не определено». Оставляйте их как есть и не интерпретируйте как отрицательный результат.
• Оператор — это исходный оператор. Это не текущий оператор после переноса номера. Регион и город описывают географию распределения номера, а не текущее местоположение человека или устройства.

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

Ошибки, резервирование и баланс

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

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

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

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

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

Размещайте поле страны перед полем файла в multipart-запросе, отправляйте файл в формате простого TXT или CSV с одним номером (с кодом страны) на каждой строке и передавайте API-ключ в заголовке X-API-Key с доверенного сервера. Проверьте, в каком порядке ваш HTTP-клиент упорядочивает поля формы.

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

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

Как командам обрабатывать сбой массовой задачи?

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

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

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

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