# Como conectar uma API de CPF a um bot do Telegram usando Node.js > Aprenda a conectar uma API de CPF a um bot do Telegram com Node.js. Guia completo com código e exemplos práticos! **Publicado:** 11/09/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/conectar-api-cpf-bot-telegram-nodejs --- 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**](https://www.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: ```bash 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: ```javascript 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: ```bash 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: ```json { "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](https://www.gov.br/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. ### Leia também - [Como consultar CPF via API usando Postman e cURL](https://cpfhub.io/blog/consultar-cpf-api-postman-curl) - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) --- ## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.