Verificação síncrona
Como verificar o registro de números de telefone no Telegram em tempo real
Envie um número de telefone E.164 e leia o status de registro no Telegram na mesma resposta síncrona da API.
O produto responde a uma pergunta precisa
O TG Validator verifica se o número de telefone enviado está registrado no Telegram no momento da requisição.
O produto aceita um número de telefone E.164, usa service_type=tg e retorna o resultado concluído na mesma resposta HTTP. Não há ID de tarefa para consultar por polling nem callback necessário antes que o aplicativo possa ler data.registered.
O escopo termina no status de registro. A resposta não fornece nome de usuário do Telegram, perfil, status de atividade, contatos, grupos nem dados de mensagens. Ela também não identifica a pessoa que controla o número de telefone. Não se trata de recursos ocultos; eles estão fora do contrato do produto.
Um false concluído é diferente de uma verificação que falhou
| Dados retornados | Decisão de registro | Como usar |
|---|---|---|
code=0, registered=true |
Registrado no momento da verificação | Use true como resultado desta requisição |
code=0, registered=false |
Não registrado no momento da verificação | Use false como resultado desta requisição |
| Código de negócio diferente de zero | Nenhuma decisão de registro | Não crie um booleano; trate o erro ou tente novamente conforme a documentação da API |
A distinção importa porque registered=false é uma informação utilizável produzida por uma verificação concluída. Um erro de API é retornado pelo envelope externo, com seu próprio status HTTP e um code numérico; ele não é mais um valor de data.registered.
O caminho da requisição síncrona
- Prepare a entrada E.164 — Parta de um contexto de país conhecido e normalize o número com sinal de mais, código de discagem do país e dígitos.
- Autentique a requisição — Use uma chave de API criada em Configurações e envie-a no cabeçalho documentado.
- Escolha o produto Telegram — Defina
service_type=tg; não deduza o produto a partir de campos não relacionados. - Aguarde a mesma resposta — A verificação é síncrona, então o aplicativo recebe a decisão sem polling.
- Leia os campos exatos do resultado — Use
data.registeredquandocode=0; deixe-o sem valor quando a API retornar um código de negócio diferente de zero. - Registre o momento da verificação — Trate o resultado como uma observação atual, e não como uma garantia por tempo indeterminado.
Onde o comportamento em tempo real ajuda
O contrato síncrono é adequado para softwares que precisam de uma decisão de registro atual antes de prosseguir. Um operador pode verificar um registro no painel, um aplicativo interno pode validar um número enviado ou um worker de back-end pode processar registros um de cada vez.
Para uma lista pequena, o endpoint síncrono em lote aceita até 100 identificadores E.164 e retorna o lote concluído na própria resposta da requisição. O cliente é responsável pelo agendamento e pela concorrência. Isso preserva um contrato de API simples: cada resultado concluído tem uma entrada, um resultado de registro no Telegram e um momento de observação.
Um registro mínimo no aplicativo
Use campos explícitos em vez de um rótulo vago como valid:
| Campo | Finalidade |
|---|---|
source_phone |
Preserva o que o sistema de origem forneceu |
e164_phone |
Armazena o número canônico que foi verificado |
service_type |
Registra tg como o contrato do resultado |
outcome |
A classificação do seu aplicativo: concluída, passível de nova tentativa ou requisição com falha |
registered |
Armazena true/false apenas para verificações concluídas |
checked_at |
Registra a data e hora da observação do registro |
Se um aplicativo precisar de uma resposta mais recente, deve fazer outra chamada síncrona. Ele não deve alterar a data e hora de um valor antigo nem afirmar que um valor em cache é em tempo real.
A regra de integração que evita dados falsos
code=0 confirma que o booleano registered é a resposta de registro concluída.
Essa interpretação em duas etapas mantém os problemas de entrada e as condições temporárias do serviço fora do campo de status do Telegram. Ela também torna a promessa do produto precisa: o TG Validator fornece de forma síncrona uma observação atual do registro quando a verificação é concluída, enquanto o sistema integrador decide quando precisa de uma nova observação.