Como criar um bot no Telegram para consultar CPF usando Python

Com Python e a API CPFHub.io, é possível criar um bot funcional no Telegram para consultas de CPF em menos de 80 linhas de código. Basta uma conta gratuita na CPFHub.io, um token gerado via @BotFather e a biblioteca python-telegram-bot — o bot recebe um número de CPF, valida o formato localmente e retorna nome, gênero e data de nascimento em ~900ms.

Introdução

Criar um bot no Telegram para consultar CPF é uma forma prática de disponibilizar validações de identidade para equipes internas — como atendimento ao cliente, compliance ou operações. Com Python e a API da CPFHub.io, o processo é direto: o Telegram cuida da interface de mensagens e a CPFHub.io cuida da consulta aos dados cadastrais. A documentação oficial da API do Telegram descreve todos os recursos disponíveis para bots, incluindo gerenciamento de grupos e controle de acesso por usuário.

Pré-requisitos

• Python 3.9+

• Biblioteca python-telegram-bot (pip install python-telegram-bot)

• Biblioteca requests (pip install requests)

• Token do bot Telegram (criado via @BotFather)

• Conta gratuita na CPFHub.io

1. Crie o bot no Telegram

1. Abra o Telegram e busque por @BotFather.

2. Envie /newbot e siga as instruções.

3. Copie o token gerado (ex: 123456789:ABCdefGhIJKlmNoPQRsTUVwxYZ).

2. Configure as variáveis de ambiente

Crie um arquivo .env:

TELEGRAM_BOT_TOKEN=seu_token_aqui
CPFHUB_API_KEY=sua_chave_aqui

3. Código completo do bot

Crie o arquivo bot.py:

import os
import re
import requests
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

CPFHUB_API_KEY = os.environ['CPFHUB_API_KEY']
TELEGRAM_BOT_TOKEN = os.environ['TELEGRAM_BOT_TOKEN']

def validar_cpf_sintatico(cpf: str) -> bool:
    cpf = re.sub(r'\D', '', cpf)
    if len(cpf) != 11 or len(set(cpf)) == 1:
    return False
    for i in range(9, 11):
    soma = sum(int(cpf[j]) * ((i + 1) - j) for j in range(i))
    digito = (soma * 10 % 11) % 10
    if digito != int(cpf[i]):
    return False
    return True

def consultar_cpf(cpf: str) -> dict:
    cpf = re.sub(r'\D', '', cpf)
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
    response = requests.get(url, headers=headers, timeout=10)
    return response.json()

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
    'Bem-vindo! Envie um CPF (apenas numeros) para consultar.'
    )

async def handle_cpf(update: Update, context: ContextTypes.DEFAULT_TYPE):
    texto = re.sub(r'\D', '', update.message.text)

    if len(texto) != 11:
    await update.message.reply_text('Envie um CPF valido com 11 digitos.')
    return

    if not validar_cpf_sintatico(texto):
    await update.message.reply_text('CPF com formato invalido (digitos verificadores incorretos).')
    return

    await update.message.reply_text('Consultando CPF...')

    try:
    resultado = consultar_cpf(texto)

    if resultado.get('success'):
    dados = resultado['data']
    resposta = (
    f"CPF: {dados['cpf']}\n"
    f"Nome: {dados['name']}\n"
    f"Genero: {dados['gender']}\n"
    f"Nascimento: {dados['birthDate']}"
    )
    else:
    resposta = 'CPF nao encontrado na base.'

    except requests.exceptions.Timeout:
    resposta = 'Tempo de resposta excedido. Tente novamente.'
    except Exception as e:
    resposta = f'Erro na consulta: {str(e)}'

    await update.message.reply_text(resposta)

def main():
    app = Application.builder().token(TELEGRAM_BOT_TOKEN).build()
    app.add_handler(CommandHandler('start', start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_cpf))
    app.run_polling()

if __name__ == '__main__':
    main()

4. Executando o bot

export TELEGRAM_BOT_TOKEN=seu_token_aqui
export CPFHUB_API_KEY=sua_chave_aqui
python bot.py

O bot ficará ativo e responderá no Telegram quando alguém enviar um CPF.

5. Como funciona o fluxo

1. O usuário envia um número de CPF no chat.

2. O bot valida o formato localmente (dígitos verificadores).

3. Se válido, consulta a API da CPFHub.io.

4. Retorna nome, gênero e data de nascimento.

5. Se inválido ou não encontrado, retorna mensagem de erro.

6. Boas práticas e segurança

• Restrinja o acesso — Limite o bot a usuários ou grupos autorizados usando IDs do Telegram.

• Não exponha dados sensíveis — Nunca exiba o CPF completo em logs ou mensagens para terceiros.

• Respeite a LGPD — Use o bot apenas para consultas autorizadas e com consentimento.

• Variáveis de ambiente — Nunca hardcode tokens ou chaves de API no código.

7. Possíveis melhorias

• Adicionar comando /ajuda com instruções.

• Implementar whitelist de usuários autorizados.

• Adicionar logs de consulta para auditoria.

• Usar Redis para cache de CPFs já consultados.

• Integrar com banco de dados para histórico.

Perguntas frequentes

Qual é a latência esperada ao consultar CPF pelo bot no Telegram?

A API CPFHub.io responde em ~900ms. O bot do Telegram adiciona uma latência mínima de rede, então o usuário recebe a resposta em aproximadamente 1 a 2 segundos após enviar o CPF — tempo adequado para uso em operações internas de atendimento ou compliance.

Como restringir o acesso ao bot para apenas usuários autorizados?

Implemente uma whitelist de IDs do Telegram: antes de processar qualquer mensagem, verifique se update.effective_user.id está na lista de IDs permitidos. Se não estiver, responda com uma mensagem genérica e encerre o handler. Isso impede que o bot seja usado por pessoas fora da equipe autorizada.

O que acontece quando o limite de consultas gratuitas é atingido?

A API CPFHub.io não bloqueia o acesso ao atingir o limite do plano gratuito (50 consultas/mês). Cada consulta adicional é cobrada a R$0,15 — o bot continua funcionando normalmente. Para equipes com volume maior, o plano Pro oferece 1.000 consultas mensais por R$149.

Como integrar o bot com um banco de dados para histórico de consultas?

Após cada consulta bem-sucedida, salve no banco um registro com o ID do usuário do Telegram, o CPF consultado (preferencialmente hasheado), o timestamp e o resultado (encontrado/não encontrado). Ferramentas como SQLite (para uso local) ou PostgreSQL (para produção) funcionam bem com Python e podem ser integradas ao handler existente sem alterar a lógica de consulta à API.

Conclusão

Com menos de 80 linhas de Python, você cria um bot funcional no Telegram que consulta CPFs em tempo real usando a API da CPFHub.io. O fluxo é simples: o usuário envia o CPF, o bot valida o formato localmente, consulta a API e devolve os dados cadastrais. Para equipes de atendimento, compliance ou operações, essa integração elimina a necessidade de acessar sistemas internos para verificações rápidas de identidade.

O próximo passo é adicionar controle de acesso por whitelist de usuários e um log de consultas para auditoria — funcionalidades que levam mais uma hora de código e tornam o bot pronto para uso em produção.

Crie sua conta gratuita em cpfhub.io e faça até 50 consultas por mês sem cartão de crédito. Quando o volume crescer, o excedente custa R$0,15 por consulta — sem bloqueios nem interrupções.