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

Bernardo Rocha

Publicado em 9 de abril de 20254 min de leitura

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.

Neste guia, explicaremos como integrar a API da CPFHub.io usando Node.js, cobrindo desde os pré-requisitos até exemplos práticos com as bibliotecas

axios

node-fetch

1. Pré-requisitos

Antes de iniciar, verifique se você tem:

✅ Node.js instalado (versão 14 ou superior recomendada).
✅ Conta na CPFHub.io para obter a chave de API.
✅ Bibliotecas axios ou node-fetch para requisições HTTP.

Se ainda não tem uma conta, cadastre-se em CPFHub.io e gere sua chave de API.

2. Instalando as dependências

Recomendamos o uso do

axios

para facilitar as chamadas HTTP. Para instalar, execute:

npm install axios

Se preferir utilizar

node-fetch

, instale com:

npm install node-fetch

3. Fazendo uma consulta de CPF com Node.js

Usando axios

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

axios

const axios = require('axios');

const API_KEY = 'SUA_CHAVE_DE_API';
const URL = 'https://api.cpfhub.io/api/cpf';

const payload = {
    cpf: '123.456.789-00',
    birthDate: '15/06/1990'
};

const headers = {
    'Content-Type': 'application/json',
    'x-api-key': API_KEY
};

axios.post(URL, payload, { headers })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error('Erro na consulta:', error.response ? error.response.data : error.message);
    });

Usando node-fetch

Se preferir utilizar

node-fetch

, veja o exemplo abaixo:

const fetch = require('node-fetch');

const API_KEY = 'SUA_CHAVE_DE_API';
const URL = 'https://api.cpfhub.io/api/cpf';

const payload = {
    cpf: '123.456.789-00',
    birthDate: '15/06/1990'
};

fetch(URL, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
    },
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Erro na consulta:', error));

4. Exemplo de resposta da API

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

{
  "success": true,
  "data": {
    "name": "João da Silva",
    "status": "Regular",
    "situation": "Ativo",
    "birthDate": "15/06/1990",
    "cpfNumber": "12345678900",
    "registrationDate": "anterior a 10/11/1990",
    "verificationDigit": "03",
    "receipt": {
      "emissionTime": "22:08:26",
      "emissionDate": "13/01/2025",
      "controlCode": "XXXX.XXXX.XXXX.XXXX"
    },
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678900&cc=XXXXXX&de=13012025&he=220826&dv=03&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/api/view-proof/12345678900/XXXXXXXXXXXXX"
  }
}

✅ O que essa resposta indica?

success: Se a consulta foi realizada com sucesso.
name: Nome completo do titular do CPF.
status: Indica se o CPF está regular ou irregular.
situation: Situação cadastral do CPF.
birthDate: Data de nascimento associada ao CPF.
validationUrl: Link direto para consulta na Receita Federal.

5. Tratamento de erros

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

axios.post(URL, payload, { headers })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        if (error.response) {
            console.error('Erro:', error.response.data);
        } else {
            console.error('Erro inesperado:', error.message);
        }
    });

Mensagens de erro comuns:

Código	Mensagem	Motivo
400	CPF inválido	O CPF informado não segue o formato correto
401	Chave de API inválida	A chave de API fornecida está errada ou expirada
403	Acesso negado	Sua conta não tem permissão para esta consulta
500	Erro interno	Problema temporário na API

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

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

axios

node-fetch

, é possível realizar consultas rápidas e seguras para evitar fraudes e melhorar a experiência do usuário. Se sua empresa busca uma solução confiável para validação de CPF, conheça a API da CPFHub.io e implemente uma integração eficiente agora mesmo!