Como verificar o registro no Telegram de um CSV de números de telefone em tempo real

Um guia técnico para verificar em tempo real o registro no Telegram de um CSV de números de telefone com o TG Validator, com foco na preparação dos dados, nos endpoints síncronos individual e múltiplo, no gerenciamento de concorrência e na interpretação dos resultados.

O TG Validator verifica o registro no Telegram em tempo real: envie um número E.164 para POST /api/v1/check, ou até 100 números para o endpoint múltiplo síncrono POST /api/v1/batch-check, e o resultado concluído é retornado na mesma resposta HTTP. Para verificar um CSV, padronize a coluna em E.164, envie-a pelo endpoint múltiplo com até 100 identificadores por requisição e gerencie a concorrência no lado do cliente de acordo com a documentação da API. Um arquivo inteiro, muito maior do que uma requisição em tempo real, também pode ser enviado como tarefa em massa assíncrona.

Preparando seus dados para a verificação

Ao processar um CSV de contatos, o primeiro passo é padronizar a entrada. O TG Validator exige que todos os números de telefone enviados estejam no formato E.164. Esse plano internacional de numeração garante que cada número seja globalmente único, normalmente começando com um '+' seguido do código do país e do número do assinante. Padronizar a coluna do CSV em E.164 antes de iniciar as requisições à API evita erros de número de telefone inválido e garante que o sistema consiga verificar com precisão o status de registro no Telegram.

Entendendo o fluxo da API do TG Validator

O modelo principal do TG Validator é o de requisição e resposta síncronas, tanto para verificações individuais quanto para verificações múltiplas. Use POST /api/v1/check para um número, ou o endpoint múltiplo síncrono POST /api/v1/batch-check com service_type=tg para até 100 identificadores E.164 de um CSV; ambos retornam na mesma resposta HTTP, sem etapa de envio de tarefa, polling ou download.

Gerenciando a vazão e os limites da API

Processe o CSV com o endpoint múltiplo síncrono, com até 100 identificadores por requisição, e respeite os controles de uso da API da plataforma. O TG Validator aplica um limite de concorrência por usuário; por isso, confirme o valor atual na documentação da API antes de decidir quantas requisições seu script mantém abertas. Para um arquivo inteiro muito maior do que uma requisição em tempo real, também há uma tarefa em massa assíncrona (enviar, aguardar, baixar); consulte a documentação da API para ver os limites atuais. Se o seu script ultrapassar esses limites, a API retornará códigos de erro específicos indicando que todos os espaços de concorrência estão ocupados ou que a verificação excedeu o tempo limite. Rejeições desse tipo não são cobradas e não geram resultado de verificação. Implementar um intervalo de espera ou uma fila que limite a concorrência no seu script de processamento do CSV garante uma execução tranquila, sem erros desnecessários.

Interpretando os resultados e tratando erros

A API retorna um envelope de resposta documentado que contém code, msg e data. Nas verificações do Telegram, o campo data.registered fornece o sinal de presença da conta. Em uma verificação do Telegram concluída, o data retornado contém apenas service_type, identifier e registered; campos internos de registro, transação, status e cobrança não são retornados.

Perguntas frequentes

Em que formato devem estar os números de telefone para a verificação?

Todos os números de telefone devem ser enviados no formato E.164, que garante que cada número seja globalmente único ao começar com um '+' seguido do código do país e do número do assinante.

O que acontece se eu ultrapassar o limite de concorrência?

Se você ultrapassar o limite de concorrência documentado, a API retorna um código de erro. Essas rejeições por limite não são cobradas e não geram resultado de verificação.

Posso verificar vários números em uma única requisição?

Sim. O endpoint múltiplo síncrono POST /api/v1/batch-check aceita até 100 identificadores E.164 e retorna os resultados concluídos na mesma resposta HTTP. Para um arquivo inteiro muito maior do que isso, também há uma tarefa em massa assíncrona (você escolhe o país ao qual os números pertencem no momento do envio, e a lista deve ser essencialmente desse único país), mas os endpoints síncronos continuam sendo a forma principal de verificar.