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

> Aprenda a consumir APIs REST de CPF em Node.js usando Axios e Fetch. Exemplos práticos, tratamento de erros e boas práticas.

**Publicado:** 15/05/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-apis-rest-de-cpf-em-nodejs-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](https://nodejs.org/docs/latest/api/fetch.html), sem necessidade de instalação.

```javascript
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

```bash
npm install axios
```

### Consulta básica

```javascript
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

| Recurso | Fetch (nativo) | Axios |
| --- | --- | --- |
| Instalação | Nenhuma (Node 18+) | `npm install axios` |
| Timeout | Manual (AbortController) | Configurável |
| Interceptors | Não nativo | Sim |
| Retry automático | Manual | Via interceptors |
| Instância reutilizável | Não | Sim (create) |
| Tratamento de erros | Manual (check response.ok) | Automático (throw em 4xx/5xx) |

---

## Retry com Axios interceptors

```javascript
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

```javascript
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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura)
- [Como consumir API de CPF em TypeScript com tipagem segura](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-typescript-com-tipagem-segura)
- [Autenticação em APIs REST: como garantir segurança na consulta de CPF](https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf)

---

## 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**](https://www.cpfhub.io/) tem plano gratuito com 50 consultas/mês para você começar.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)