Guia completo para integrar uma API de CPF usando Node.js

Integrar uma API de CPF em Node.js com a CPFHub.io leva menos de 30 minutos usando fetch nativo (Node.js 18+) ou axios. Uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key retorna nome, gênero e data de nascimento do titular em ~900ms — dados suficientes para validar identidade, prevenir fraudes e atender regulamentações sem sair do ambiente JavaScript.

Introdução

A integração de APIs de consulta de CPF é essencial para empresas que precisam validar a identidade de clientes de forma rápida, segura e automatizada. Fintechs, e-commerces e bancos digitais utilizam essas APIs para prevenir fraudes, atender a regulamentações e melhorar a experiência do usuário.

Este guia mostra como integrar a API da CPFHub.io usando Node.js, cobrindo desde os pré-requisitos até exemplos práticos com as bibliotecas axios e fetch nativo.

1. Pré-requisitos

Antes de iniciar, verifique se você tem:

• Node.js instalado (versão 18 ou superior recomendada, que já inclui fetch nativo).

• Conta na CPFHub.io para obter a chave de API.

• Biblioteca axios (opcional) para requisições HTTP.

Se ainda não tem uma conta, cadastre-se em CPFHub.io e obtenha sua chave de API gratuitamente — sem cartão de crédito.

2. Instalando as dependências

Se preferir usar o axios para facilitar as chamadas HTTP, instale com:

npm install axios

Com Node.js 18+, o fetch já está disponível nativamente e não requer instalação adicional.

3. Fazendo uma consulta de CPF com Node.js

Usando fetch nativo

Aqui está um exemplo de como consultar um CPF utilizando a API da CPFHub.io com fetch:

const API_KEY = 'SUA_CHAVE_DE_API';
const cpf = '12345678900';

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();
console.log(data);

Usando axios

Se preferir utilizar axios, veja o exemplo abaixo:

const axios = require('axios');

const API_KEY = 'SUA_CHAVE_DE_API';
const cpf = '12345678900';

axios.get(`https://api.cpfhub.io/cpf/${cpf}`, {
    headers: {
    'x-api-key': API_KEY,
    'Accept': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error('Erro na consulta:', error.response ? error.response.data : error.message);
});

4. Exemplo de resposta da API

A API retornará um JSON com os dados do CPF consultado:

{
    "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
    }
}

O que essa resposta indica?

• success: Se a consulta foi realizada com sucesso.

• name: Nome completo do titular do CPF.

• nameUpper: Nome em letras maiúsculas.

• gender: Gênero do titular (M/F).

• birthDate: Data de nascimento associada ao CPF.

• day, month, year: Data de nascimento em campos separados para facilitar o uso.

5. Tratamento de erros

Caso ocorra algum erro, é importante capturá-lo corretamente:

try {
    const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': API_KEY,
    'Accept': 'application/json'
    }
    });

    if (!response.ok) {
    throw new Error(`Erro HTTP: ${response.status}`);
    }

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

Códigos de erro comuns:

Dica: Sempre valide os dados antes de enviar a requisição para evitar erros desnecessários.

Perguntas frequentes

Como faço para começar a usar a API de CPF com Node.js?

Crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. O plano gratuito oferece 50 consultas mensais sem cartão de crédito — suficiente para desenvolver e testar a integração completa.

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

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. 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.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Qual é a diferença entre usar fetch nativo e axios para consultar a API?

Para a maioria dos casos, ambos funcionam igualmente bem. O fetch nativo (disponível no Node.js 18+) não exige dependências extras e é a escolha mais leve. O axios oferece interceptors, cancelamento de requisições e tratamento de erros mais ergonômico — vantagens relevantes em projetos maiores com múltiplas integrações de API.

Conclusão

A integração da API de consulta de CPF em Node.js é um processo simples e essencial para validar a identidade de clientes. Com fetch nativo ou axios, é possível realizar consultas rápidas e seguras para evitar fraudes e melhorar a experiência do usuário.

Vantagens da API CPFHub.io:

• Plano gratuito com 50 consultas mensais, sem cartão de crédito.

• Dados padronizados em JSON e atualizados diariamente.

• Resposta em ~900ms com 99,9% de uptime.

• Documentação completa com exemplos em 13+ linguagens.

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