Como consumir APIs REST de CPF em Node.js com Axios e Fetch

Para consumir a API de CPF da CPFHub.io em Node.js, faça uma requisição GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key — usando o Fetch nativo (Node.js 18+) ou o Axios. A API retorna nome, data de nascimento e gênero com latência de aproximadamente 900ms. Você pode usar ambas as abordagens em produção; a escolha depende de precisar de recursos como interceptors e instâncias reutilizáveis, que o Axios oferece de forma nativa.

Usando Fetch (nativo)

Disponível nativamente a partir do Node.js 18, sem necessidade de instalação.

async function consultarCpfFetch(cpf) {
    const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
    });

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

    const dados = await response.json();

    if (!dados.success) {
    return { encontrado: false, motivo: 'CPF nao encontrado' };
    }

    return {
    encontrado: true,
    nome: dados.data.name,
    nascimento: dados.data.birthDate,
    genero: dados.data.gender
    };
}

Usando Axios

Instalação

npm install axios

Consulta básica

const axios = require('axios');

const cpfhubClient = axios.create({
    baseURL: 'https://api.cpfhub.io',
    timeout: 10000,
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
});

async function consultarCpfAxios(cpf) {
    try {
    const { data } = await cpfhubClient.get(`/cpf/${cpf}`);

    if (!data.success) {
    return { encontrado: false, motivo: 'CPF nao encontrado' };
    }

    return {
    encontrado: true,
    nome: data.data.name,
    nascimento: data.data.birthDate,
    genero: data.data.gender
    };

    } catch (error) {
    if (error.response) {
    const status = error.response.status;
    if (status === 401) return { error: 'Chave de API invalida' };
    return { error: `HTTP ${status}` };
    }
    if (error.code === 'ECONNABORTED') {
    return { error: 'Timeout na requisicao' };
    }
    return { error: error.message };
    }
}

Comparativo: Fetch vs. Axios

Retry com Axios interceptors

const axios = require('axios');

const client = axios.create({
    baseURL: 'https://api.cpfhub.io',
    timeout: 10000,
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
});

// Retry interceptor para erros de rede e erros de servidor (5xx)
client.interceptors.response.use(null, async (error) => {
    const config = error.config;
    config.__retryCount = config.__retryCount || 0;

    if (config.__retryCount >= 3) {
    return Promise.reject(error);
    }

    const status = error.response ? error.response.status : 0;
    if (status >= 500) {
    config.__retryCount += 1;
    const delay = Math.pow(2, config.__retryCount) * 1000;
    await new Promise(resolve => setTimeout(resolve, delay));
    return client(config);
    }

    return Promise.reject(error);
});

Uso em Express.js

const express = require('express');
const app = express();

app.get('/api/validar-cpf/:cpf', async (req, res) => {
    const cpf = req.params.cpf.replace(/\D/g, '');

    if (cpf.length !== 11) {
    return res.status(400).json({ error: 'CPF deve ter 11 digitos' });
    }

    const resultado = await consultarCpfAxios(cpf);
    res.json(resultado);
});

app.listen(3000);

Boas práticas

• Variáveis de ambiente — Use process.env.CPFHUB_API_KEY.

• Timeout — Configure entre 5 e 10 segundos. A API tem latência de ~900ms; um timeout de 5s dá margem suficiente para variações de rede.

• Instância reutilizável — Use axios.create() com baseURL e headers.

• Retry — Implemente apenas para erros 5xx (falha de servidor). Erros 4xx indicam problema na requisição e não devem ser retentados.

• Nunca exponha no frontend — Chame a API apenas do backend.

Perguntas frequentes

Qual é a diferença entre usar Fetch e Axios para consumir a API CPFHub.io?

Fetch é nativo no Node.js 18+ e não requer dependências externas, mas exige código manual para timeout (via AbortController) e não lança erro automaticamente em respostas 4xx/5xx. Axios oferece configuração de timeout integrada, instâncias reutilizáveis com axios.create() e interceptors para retry — o que facilita a manutenção em aplicações maiores.

Como configurar o timeout corretamente para a API CPFHub.io?

A latência da API é de aproximadamente 900ms. Um timeout de 5 segundos cobre essa latência com margem para variações de rede. No Axios, defina timeout: 5000 na criação da instância. Com Fetch, use AbortController com setTimeout(() => controller.abort(), 5000) e passe o signal na requisição.

A API retorna erro quando o limite de consultas é atingido?

Não. A CPFHub.io não bloqueia requisições nem retorna erro quando o limite do plano é ultrapassado. O plano gratuito inclui 50 consultas/mês e o Pro inclui 1.000 — ao exceder qualquer um desses volumes, a API continua respondendo normalmente e cobra R$0,15 por consulta adicional. Acompanhe o consumo em app.cpfhub.io/settings/billing.

Devo implementar retry automático ao chamar a API CPFHub.io?

Retry faz sentido para erros de servidor (status 5xx) e falhas de rede — situações temporárias onde uma nova tentativa pode ter sucesso. Para erros 4xx (CPF inválido, chave incorreta), retry não resolve o problema e só gera consultas desnecessárias. Configure o interceptor Axios para retentar apenas em status >= 500 com backoff exponencial.

Conclusão

Tanto Fetch quanto Axios funcionam bem para consumir a API de CPF em Node.js. Fetch é ideal para projetos simples sem dependências extras; Axios oferece mais recursos como interceptors e retry automático. A CPFHub.io tem plano gratuito com 50 consultas/mês para você começar.

Cadastre-se em cpfhub.io