Как спланировать процесс проверки номеров телефонов в Telegram через API в реальном времени

Техническое руководство по проектированию процесса проверки номеров телефонов через API в реальном времени с TG Validator: синхронные одиночный и множественный эндпоинты, лимиты параллельности, форматирование E.164 и интерпретация сигнала.

Процесс проверки в TG Validator строится на проверках в реальном времени: отправьте один идентификатор в формате E.164 на POST /api/v1/check или до 100 идентификаторов на синхронный множественный эндпоинт POST /api/v1/batch-check, и готовые результаты проверки регистрации вернутся в ответе на исходный HTTP-запрос. Управляйте параллельностью на стороне клиента в соответствии с документацией API. Для целого списка, намного превышающего один запрос в реальном времени, в качестве дополнения также доступно асинхронное задание массовой проверки.

Синхронная модель проверки

Основная модель TG Validator синхронная. Используйте POST /api/v1/check для одного идентификатора или синхронный множественный эндпоинт POST /api/v1/batch-check для до 100 идентификаторов; готовые результаты возвращаются в том же HTTP-ответе — без отправки задания, опроса, обратного вызова или скачивания и без требования, чтобы номера относились к одной стране. В качестве запасного варианта для целого большого списка также доступно асинхронное задание массовой проверки (/api/v1/bulk-tasks): загрузите файл, получите идентификатор задания, затем опрашивайте его статус и скачайте файл результатов, когда задание завершится. При отправке задания вы выбираете страну, к которой относятся номера, и список должен по существу состоять из номеров этой одной страны. Далее в руководстве речь идет о синхронном пути.

Подготовка данных к проверке

Прежде чем отправлять запросы, убедитесь, что все номера телефонов в вашем наборе данных отформатированы по международному плану нумерации E.164. API требует заголовка X-API-Key и заголовка Content-Type: application/json. Используйте POST /api/v1/check с service_type=tg и одним identifier в формате E.164 или синхронный множественный эндпоинт POST /api/v1/batch-check с service_type=tg и массивом identifiers, содержащим до 100 номеров в формате E.164. Поскольку TG Validator работает исключительно с Telegram, тип сервиса всегда должен быть tg.

Архитектура процесса проверки номеров через API в реальном времени

Управление пропускной способностью — важнейший компонент процесса проверки номеров телефонов через API в реальном времени. TG Validator API ограничивает число проверок, которые один аккаунт может выполнять одновременно, а актуальный предел указан в документации API. Ваше клиентское приложение должно ограничивать частоту запросов, чтобы оставаться в этих пределах. Если ваша система превысит этот порог, API отклонит запросы. Отказы из-за лимита параллельности не оплачиваются и не дают результата проверки, поэтому ваше приложение должно быть спроектировано так, чтобы безопасно делать паузу и повторять именно такие запросы.

Интерпретация сигнала регистрации

API возвращает задокументированную обертку ответа с полями code, message и data. Внутри этой обертки статус регистрации в Telegram находится в поле data.registered. Этот результат служит исключительно сигналом наличия аккаунта на момент проверки. Продукт не возвращает поля avatar или business, поэтому ответ полностью сосредоточен на статусе регистрации.

Мониторинг и обработка ошибок

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

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

Что делать, если достигнут лимит параллельности?

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

Подтверждает ли статус «registered», что с пользователем можно связаться?

Нет. Сигнал регистрации указывает только на наличие аккаунта Telegram точно на момент проверки.

Как процессу обрабатывать список, превышающий один запрос?

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

Как неудачные проверки учитываются в биллинге?

За неудачные, прерванные по тайм-ауту и неопределенные проверки плата не удерживается. Актуальные сведения о тарифах и балансе приведены на странице цен.