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

> Aprenda a integrar uma API de consulta de CPF em Node.js utilizando axios e fetch nativo. Passo a passo com exemplos práticos!

**Publicado:** 01/11/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/integrar-api-cpf-nodejs

---


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**](https://www.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:

```bash
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`:

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

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

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

**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:

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

| Código | Significado | Motivo |
| --- | --- | --- |
| 400 | Bad Request | O CPF informado não segue o formato correto |
| 401 | Unauthorized | A chave de API fornecida está errada ou ausente |
| 404 | Not Found | Recurso não encontrado |
| 500 | Internal Server Error | Problema temporário na API |

**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](https://www.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](https://www.gov.br/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.

### Leia também

- [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)
- [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos)
- [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei)

---

## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.