Como conectar uma API de CPF a um bot do Telegram usando Node.js

Conectar uma API de CPF a um bot do Telegram usando Node.js permite automatizar a verificação de identidade diretamente no aplicativo de mensagens que sua equipe já usa. Com a CPFHub.io e a biblioteca Telegraf, você cria um bot funcional em menos de 30 minutos que retorna nome, gênero e data de nascimento de qualquer CPF consultado — com resposta em aproximadamente 900ms.

Introdução

A integração de APIs de consulta de CPF com bots do Telegram é uma solução prática para empresas que desejam oferecer verificação de identidade automatizada dentro do próprio aplicativo de mensagens. Com um bot no Telegram, usuários podem consultar os dados cadastrais vinculados a um CPF de forma rápida e segura, usando Node.js e conectando à API da CPFHub.io para validar CPFs em tempo real.

1. Pré-requisitos

Antes de começar, você precisará de:

1. Node.js instalado (versão 14 ou superior recomendada).
2. Conta na CPFHub.io para obter a chave de API.
3. Token do bot do Telegram (gerado via BotFather).
4. Bibliotecas telegraf e dotenv para comunicação com a API e o Telegram.

Se ainda não tem uma conta, cadastre-se em CPFHub.io e obtenha suas primeiras 50 consultas gratuitas sem precisar de cartão de crédito.

2. Criando o bot no Telegram

Passo 1: Criar um novo bot

No Telegram, procure o BotFather e envie o comando:

/start
/newbot

O BotFather solicitará:

1. Um nome para o bot (exemplo: CPF Checker Bot).

2. Um nome de usuário (deve terminar com bot, ex: cpf_checker_bot).

Após a criação, você receberá um token de API do Telegram, que será usado na configuração do bot.

3. Configurando o projeto em Node.js

Passo 2: Criar o projeto e instalar dependências

No terminal, crie uma pasta para o projeto e instale as bibliotecas necessárias:

mkdir cpf_bot
cd cpf_bot
npm init -y
npm install telegraf dotenv

Crie um arquivo .env e adicione suas credenciais:

TELEGRAM_BOT_TOKEN=SEU_TOKEN_DO_TELEGRAM
API_CPFHUB_KEY=SUA_CHAVE_DE_API

4. Criando o bot e conectando à API de CPF

Crie um arquivo bot.js e adicione o seguinte código:

require('dotenv').config();
const { Telegraf } = require('telegraf');

const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN);
const API_KEY = process.env.API_CPFHUB_KEY;

// Função para consultar CPF via API
async function consultarCPF(cpf) {
    try {
    const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': API_KEY,
    'Accept': 'application/json'
    }
    });

    const data = await response.json();
    return data;
    } catch (error) {
    console.error('Erro na consulta:', error);
    return null;
    }
}

// Comando /start
bot.start((ctx) => {
    ctx.reply('Bem-vindo ao CPF Checker Bot! Envie um CPF (apenas números) para consultar. Exemplo: 12345678900');
});

// Tratando mensagens
bot.on('text', async (ctx) => {
    const cpf = ctx.message.text.replace(/\D/g, '');

    if (cpf.length !== 11) {
    return ctx.reply('CPF inválido! Envie um CPF com 11 dígitos.');
    }

    ctx.reply('Consultando CPF... Aguarde.');

    const resultado = await consultarCPF(cpf);

    if (resultado && resultado.success) {
    const info = resultado.data;
    ctx.reply(`CPF Válido!
Nome: ${info.name}
Gênero: ${info.gender}
Data de Nascimento: ${info.birthDate}`);
    } else {
    ctx.reply('CPF não encontrado ou inválido.');
    }
});

// Iniciar bot
bot.launch();
console.log('Bot está rodando no Telegram!');

5. Executando o bot

No terminal, execute:

node bot.js

Se tudo estiver correto, você verá a mensagem:

Bot está rodando no Telegram!

Agora, no Telegram, envie uma mensagem ao bot com o CPF:

12345678900

E ele responderá com os dados cadastrais consultados.

6. Exemplo de resposta da API

Após a requisição, a API retornará um JSON com as informações do CPF:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Vantagens desse bot:

• Validação instantânea de CPFs diretamente no Telegram (~900ms de resposta).

• Evita fraudes e consultas manuais.

• Fácil de implementar e escalar para diferentes usos.

• API com 99,9% de uptime e conformidade com a LGPD. A ANPD orienta que o tratamento de dados de identificação deve seguir o princípio da necessidade — armazene apenas o essencial.

Perguntas frequentes

Como o bot do Telegram recebe e processa o CPF enviado pelo usuário?

O bot usa o evento bot.on('text') da biblioteca Telegraf para capturar qualquer mensagem de texto. O código remove caracteres não numéricos com replace(/\D/g, ''), valida se o resultado tem 11 dígitos e então chama a API da CPFHub.io com o CPF limpo. A resposta é formatada e enviada de volta ao usuário em segundos.

A API CPFHub.io funciona para todos os volumes de consulta no bot?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e bots internos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional, sem interromper o serviço.

Como proteger a chave de API do CPFHub.io no projeto Node.js?

Armazene a chave no arquivo .env e nunca a versione no repositório — adicione .env ao .gitignore. Use process.env.API_CPFHUB_KEY no código para ler a variável de ambiente. Em produção, configure a variável diretamente no servidor ou no serviço de hospedagem, sem expô-la no código-fonte.

O bot do Telegram pode ser usado em produção para validação de clientes?

Sim, com as devidas precauções: restrinja o acesso ao bot apenas aos usuários autorizados (usando o ctx.from.id para whitelist), implemente logs de auditoria das consultas, respeite a LGPD não armazenando CPFs no histórico do chat e configure tratamento de erros para garantir que falhas na API não exponham informações sensíveis.

Conclusão

Conectar uma API de CPF a um bot do Telegram usando Node.js é uma forma prática de automatizar a verificação de identidade. Utilizando o Telegraf e a API da CPFHub.io, você cria um bot funcional em poucos passos, com resposta em aproximadamente 900ms e dados cadastrais completos retornados a cada consulta.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.