Проверка номера и Caller ID с numverify + Python

пользователь общается по традиционному проводному телефону

Зачем это нужно

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

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

Коротко: валидированный номер повышает качество данных и снижает операционные риски.

Важно: ни один сервис не гарантирует 100% точность. Используйте проверку как часть многоступенчатой валидации.

Установка модуля requests

requests — простая и надёжная библиотека для HTTP‑запросов в Python. Установите её так:

pip install requests

Совет: для проектов используйте виртуальное окружение (venv, pipenv или Poetry).

Как получить API‑ключ numverify

Перейдите на сайт numverify и нажмите Sign Up for Free.
Выберите подходящий тариф и создайте аккаунт.
Войдите в Dashboard и скопируйте Access/API key — он понадобится в коде.

страница входа Numverify

страница тарифов Numverify

страница создания аккаунта Numverify

Примечание: бесплатные тарифы часто имеют ограничение по количеству вызовов в месяц. Подбирайте план в зависимости от объёма.

Базовый пример: запрос и разбор ответа

Ниже — чистый и практичный пример на Python: используется params для безопасной передачи параметров и базовая обработка ошибок.

import requests
import sys

API_KEY = 'YOUR_API_KEY'  # замените на ваш ключ
BASE_URL = 'http://apilayer.net/api/validate'

def fetch_phone_info(number: str) -> dict:
    params = {'access_key': API_KEY, 'number': number}
    try:
        resp = requests.get(BASE_URL, params=params, timeout=10)
        resp.raise_for_status()
    except requests.RequestException as e:
        raise RuntimeError(f'Ошибка сети или запроса: {e}')

    try:
        data = resp.json()
    except ValueError:
        raise RuntimeError('Сервер вернул невалидный JSON')

    return data

if __name__ == '__main__':
    number = input('Введите номер с кодом страны (например +71234567890): ').strip()
    print('--------------------------------------')
    try:
        info = fetch_phone_info(number)
    except RuntimeError as err:
        print(err)
        sys.exit(1)

    if info.get('valid'):
        print('Number:', info.get('number'))
        print('Local format:', info.get('local_format'))
        print('International format:', info.get('international_format'))
        print('Country prefix:', info.get('country_prefix'))
        print('Country code:', info.get('country_code'))
        print('Country name:', info.get('country_name'))
        print('Location:', info.get('location'))
        print('Carrier:', info.get('carrier'))
        print('Line type:', info.get('line_type'))
    else:
        print('Неверный ключ API или номер. Пожалуйста, проверьте данные.')

Короткие пояснения по полям ответа (по одному предложению каждый):

valid — булево значение, указывает, распознан ли номер как действительный;
number — номер в переданном формате;
local_format / international_format — представления номера;
country_prefix — международный префикс (например +7, +1);
country_code — двухбуквенный код страны (ISO);
country_name — название страны;
location — город/регион (при наличии данных);
carrier — оператор связи;
line_type — тип линии (mobile, fixed line, VoIP и т.п.).

Полезный сниппет: пакетная обработка списка номеров

Если нужно проверить сотни или тысячи номеров, обрабатывайте их пакетно и соблюдайте лимиты API (rate limiting):

def bulk_check(numbers: list):
    results = []
    for n in numbers:
        try:
            info = fetch_phone_info(n)
        except RuntimeError:
            info = {'number': n, 'error': 'request_failed'}
        results.append(info)
    return results

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

Критерии приёмки

Сервис корректно обрабатывает валидные и невалидные номера (позитивный/негативный сценарий).
Корректно обрабатываются сетевые ошибки и неожиданный JSON.
Для пакетной обработки соблюдаются лимиты API и выбранного тарифного плана.
Чувствительные ключи хранятся вне репозитория (переменные окружения, секреты CI).

Когда это не работает

Номера, попадающие под локальные правила нумерации, могут быть помечены как валидные, но всё же не принимать SMS (например, виртуальные номера).
VoIP и короткие сервисные номера часто имеют неполные метаданные (location/carrier могут быть пустыми).
Некорректный формат ввода (отсутствует + и код страны) приводит к неверной проверке.
Ограничения тарифного плана или блокировки IP могут прерывать массовую валидацию.

Альтернативы numverify и сравнение

Twilio Lookup — помимо валидации поддерживает дополнительные данные и Carrier Lookup; работает интегрированно с экосистемой Twilio.
Nexmo (Vonage) Number Insight — платный сервис с подробной информацией и SSO.
Truecaller — фокус на идентификации и спам‑фильтрации, даёт данные о владельцах в некоторых регионах.
HLR lookup — специализированные провайдеры дают актуальный статус SIM и роуминг.

Короткая матрица выбора:

Если нужен широкий стек коммуникаций (SMS/Voice): выбирайте Twilio/Vonage.
Если нужен простой и быстрый парсинг номера и Caller ID — numverify или Truecaller.
Для проверки статуса SIM и роуминга используйте HLR‑решения.

Безопасность, конфиденциальность и GDPR

Не храните личные номера без основания для обработки. Оценивайте правовую основу (согласие, выполнение договора и т.д.).
Шифруйте ключи API и используйте ротацию секретов.
Минимизируйте хранение персональных данных: храните только те поля, которые действительно нужны.
Для пользователей из ЕС убедитесь, что выбранный провайдер соответствует требованиям GDPR и имеет Data Processing Agreement.

Важно: при отправке номеров в облачные сервисы вы передаёте персональные данные — документируйте трансферы и правовую основу.

Чек‑лист интеграции (роль‑ориентированный)

Разработчик:
- реализовать обработку ошибок и таймауты;
- реализовать кеширование ответов по номеру;
- хранить ключи в секретном хранилище;
DevOps/SRE:
- настроить мониторинг ошибок и метрики (ошибки 4xx/5xx, latency);
- контролировать расходы и лимиты API;
Продукт/Legal:
- проверить соответствие политике конфиденциальности и требованиям региона;
- определить политику хранения и удаления номеров.

Мини‑методология автоматизации (шаги)

Валидировать формат номера на фронтенде (регулярное выражение, +код страны).
Отправить на бекенд для проверки через numverify.
Проверить поле valid и принять решение (разрешить регистрацию, потребовать верификацию по SMS и т.д.).
Кешировать результат и логировать метаданные (не хранить полный номер без необходимости).
Периодически пересматривать тариф и качество данных.

Примеры выводов

пример вывода программы с данными Caller ID

На экране вы увидите перечисленные поля: номер, локальный/международный формат, префикс, страна, регион, оператор и тип линии.

Тестовые сценарии / Кейс‑тесты

Позитивный: валидный номер +7XXXXXXXXXX → valid True и заполненные поля.
Негативный: случайный набор цифр → valid False.
Ошибка сети: симулировать таймаут и проверить понятное сообщение об ошибке.
Граничный: виртуальный/VoIP номер — проверить, какие поля пустые.

Короткое резюме

Использование numverify совместно с requests даёт быстрый способ добавить валидацию телефонных номеров и получить Caller ID‑метаданные. Это повышает качество данных, помогает в таргетинге и улучшает доставляемость сообщений, но требует внимания к безопасности данных и тарифным ограничениям.

Ключевые шаги: получить API‑ключ, реализовать запрос с обработкой ошибок, кешировать ответы и соблюдать требования конфиденциальности.

Extras: