Planeje um fluxo de API de verificação de telefones em tempo real para o Telegram

Um guia técnico para projetar um fluxo de API de verificação de telefones em tempo real com o TG Validator, abordando os endpoints síncronos individual e múltiplo, os limites de concorrência, a formatação E.164 e a interpretação dos sinais.

Um fluxo de verificação do TG Validator é construído sobre verificações em tempo real: envie um identificador E.164 para POST /api/v1/check, ou até 100 identificadores para o endpoint múltiplo síncrono POST /api/v1/batch-check, e os resultados de registro concluídos voltam na resposta HTTP da própria requisição. Controle a concorrência no lado do cliente de acordo com a documentação da API. Para uma lista inteira muito maior do que uma requisição em tempo real, uma tarefa em massa assíncrona também está disponível como complemento.

Entendendo o modelo de verificação síncrona

O modelo principal do TG Validator é síncrono. Use POST /api/v1/check para um identificador ou o endpoint múltiplo síncrono POST /api/v1/batch-check para até 100 identificadores; os resultados concluídos voltam na mesma resposta HTTP, sem etapa de envio de tarefa, polling, callback ou download, e sem exigência de que os números sejam do mesmo país. Como alternativa para uma lista grande inteira, também há uma tarefa em massa assíncrona (/api/v1/bulk-tasks): envie o arquivo, receba um id de tarefa e, em seguida, consulte a tarefa e baixe o arquivo de resultados quando ela terminar. Você escolhe o país ao qual os números pertencem ao enviar a tarefa, e a lista deve ser essencialmente desse único país. O restante deste guia se concentra no caminho síncrono.

Preparando seus dados para a verificação

Antes de iniciar as requisições, garanta que todos os números de telefone do seu conjunto de dados estejam formatados de acordo com o plano internacional de numeração E.164. A API exige um cabeçalho X-API-Key e um cabeçalho Content-Type: application/json. Use POST /api/v1/check com service_type=tg e um identifier E.164, ou use o endpoint múltiplo síncrono POST /api/v1/batch-check com service_type=tg e um array identifiers de até 100 números E.164. Como o TG Validator se dedica exclusivamente ao Telegram, o tipo de serviço deve ser sempre tg.

Arquitetando um fluxo de API de verificação de telefones em tempo real

Gerenciar a vazão é o componente mais crítico de um fluxo de API de verificação de telefones em tempo real. A API do TG Validator limita quantas verificações uma conta pode ter em andamento ao mesmo tempo, e a documentação da API indica o teto atual. Sua aplicação no lado do cliente deve controlar o ritmo das requisições para permanecer dentro desse limite. Se o seu sistema ultrapassar esse patamar, a API rejeitará as requisições. As rejeições por limite de concorrência não são cobradas e não geram resultado de verificação, o que significa que sua aplicação deve ser projetada para pausar e repetir essas requisições específicas com segurança.

Interpretando o sinal de registro

A API retorna um envelope de resposta documentado com código, mensagem e dados. Dentro desse envelope, o status de registro no Telegram fica no campo data.registered. Esse resultado funciona estritamente como um sinal de presença da conta no momento da verificação. O produto não retorna campos avatar nem business, mantendo o payload totalmente focado no status de registro.

Monitoramento e tratamento de erros

Use o código de resposta da API para tratar as falhas que podem ser repetidas; consulte a documentação da API para ver os códigos de erro e os limites atuais.

Perguntas frequentes

O que devo fazer se atingir o limite de concorrência?

A API permite a cada conta apenas um número limitado de verificações simultâneas, conforme indicado na documentação da API. Se você o ultrapassar, a API rejeita a requisição sem cobrar do seu saldo nem gerar resultado. Sua aplicação deve capturar o código de erro de concorrência, pausar brevemente e repetir a requisição.

Um status 'registered' confirma que o usuário pode ser contatado?

Não. O sinal de registro indica apenas a presença de uma conta no Telegram no momento exato da verificação.

Como o fluxo deve lidar com uma lista maior do que uma requisição?

Mantenha o endpoint múltiplo síncrono como caminho principal, com até 100 identificadores por requisição, dentro do limite de concorrência documentado. Para uma lista inteira muito maior do que isso, também há uma tarefa em massa assíncrona (enviar, aguardar, baixar); você escolhe o país ao qual os números pertencem no momento do envio, a lista deve ser essencialmente desse único país, e as quantidades mínima e máxima por produto constam na documentação da API.

Como as verificações com falha são tratadas na cobrança?

Verificações com falha, que excederam o tempo limite ou sem resultado determinado não mantêm a cobrança. Consulte a página de preços para ver os detalhes atuais de planos e saldo.