# Como consumir API de CPF em Notion com integrações via API

> Aprenda a consumir a API de consulta de CPF da CPFHub.io integrada ao Notion usando scripts Node.js e a API oficial do Notion.

**Publicado:** 11/01/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-notion-com-integracoes-via-api

---

É possível integrar a API de CPF da CPFHub.io ao Notion usando um script Node.js simples que lê registros com status "Pendente" em um database, consulta cada CPF e preenche automaticamente nome, gênero e data de nascimento. A integração usa a API oficial do Notion e o endpoint `GET https://api.cpfhub.io/cpf/{CPF}` com autenticação por header `x-api-key`, e pode ser agendada via cron para rodar sem intervenção manual.

## Introdução

O **Notion** se consolidou como uma ferramenta essencial para organização e gestão de dados em equipes de todos os tamanhos. Muitas empresas usam databases do Notion para gerenciar leads, clientes e processos de onboarding. Porém, validar CPFs manualmente nesses fluxos é ineficiente e propenso a erros.

Neste guia você aprende a escrever um script Node.js que conecta a API do Notion com a API da [**CPFHub.io**](https://www.cpfhub.io/), automatizando a validação de CPF diretamente nos seus databases.

---

## 1. Pré-requisitos

* **Node.js 18+** instalado.

* Uma **integração do Notion** criada em [developers.notion.com](https://developers.notion.com/) com permissão de leitura e escrita no database.

* Um **database no Notion** com campos para CPF, Nome, Status e Data de Nascimento.

* Uma conta na [**CPFHub.io**](https://www.cpfhub.io/) com a API key gerada no painel.

---

## 2. Estrutura do database no Notion

Crie um database no Notion com as seguintes propriedades:

| Propriedade | Tipo | Descrição |
| --- | --- | --- |
| CPF | Title | CPF do cliente (somente números) |
| Nome | Rich text | Preenchido pelo script |
| Gênero | Select | Preenchido pelo script (M/F) |
| Data de Nascimento | Rich text | Preenchido pelo script |
| Status | Select | Pendente / Validado / Erro |

Compartilhe o database com a integração do Notion criada.

---

## 3. Instale as dependências

```bash
npm init -y
npm install @notionhq/client
```

---

## 4. Script de integração

Crie o arquivo `validar-cpfs.js`:

```javascript
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const DATABASE_ID = process.env.NOTION_DATABASE_ID;
const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY;

async function consultarCpf(cpf) {
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 5000);

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

 clearTimeout(timeoutId);

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

 return await response.json();
 } catch (error) {
 clearTimeout(timeoutId);
 throw error;
 }
}

async function buscarRegistrosPendentes() {
 const response = await notion.databases.query({
 database_id: DATABASE_ID,
 filter: {
 property: 'Status',
 select: {
 equals: 'Pendente'
 }
 }
 });

 return response.results;
}

async function atualizarRegistro(pageId, dados) {
 await notion.pages.update({
 page_id: pageId,
 properties: {
 'Nome': {
 rich_text: [{ text: { content: dados.name } }]
 },
 'Gênero': {
 select: { name: dados.gender === 'M' ? 'Masculino' : 'Feminino' }
 },
 'Data de Nascimento': {
 rich_text: [{ text: { content: dados.birthDate } }]
 },
 'Status': {
 select: { name: 'Validado' }
 }
 }
 });
}

async function marcarErro(pageId) {
 await notion.pages.update({
 page_id: pageId,
 properties: {
 'Status': {
 select: { name: 'Erro' }
 }
 }
 });
}

async function main() {
 const registros = await buscarRegistrosPendentes();
 console.log(`Encontrados ${registros.length} registros pendentes`);

 for (const registro of registros) {
 const cpf = registro.properties.CPF.title[0]?.plain_text?.replace(/\D/g, '');

 if (!cpf || cpf.length !== 11) {
 console.log(`CPF inválido no registro ${registro.id}`);
 await marcarErro(registro.id);
 continue;
 }

 try {
 const resultado = await consultarCpf(cpf);

 if (resultado.success) {
 await atualizarRegistro(registro.id, resultado.data);
 console.log(`Validado: ${cpf} - ${resultado.data.name}`);
 } else {
 await marcarErro(registro.id);
 console.log(`Falha na validação: ${cpf}`);
 }
 } catch (error) {
 await marcarErro(registro.id);
 console.log(`Erro ao consultar ${cpf}: ${error.message}`);
 }

 // Respeitar rate limit: aguardar 2 segundos entre consultas (plano Gratuito)
 await new Promise(resolve => setTimeout(resolve, 2000));
 }

 console.log('Processamento concluído');
}

main();
```

---

## 5. Execute o script

Defina as variáveis de ambiente e execute:

```bash
export NOTION_TOKEN="secret_seu_token_notion"
export NOTION_DATABASE_ID="seu_database_id"
export CPFHUB_API_KEY="SUA_CHAVE_DE_API"

node validar-cpfs.js
```

O script buscará todos os registros com status "Pendente", consultará cada CPF na API da CPFHub.io e atualizará o Notion com os dados retornados.

---

## 6. Exemplo de resposta da API

Para cada CPF consultado, a API retorna:

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

---

## 7. Automação com agendamento

Para executar o script automaticamente, use o **cron** no Linux/macOS ou um serviço como GitHub Actions:

```bash
# Executar a cada hora (crontab)
0 * * * * cd /caminho/do/projeto && NOTION_TOKEN=xxx NOTION_DATABASE_ID=xxx CPFHUB_API_KEY=xxx node validar-cpfs.js
```

---

## 8. Boas práticas

* **Timeout** -- O script usa `AbortController` com timeout de 5 segundos para evitar travamentos.

* **Rate limit** -- O delay de 2 segundos entre consultas respeita o limite do plano Gratuito (1 req/2s). No plano Pro, reduza para 1 segundo.

* **Variáveis de ambiente** -- Nunca armazene tokens e chaves de API diretamente no código.

* **Idempotência** -- O filtro por status "Pendente" garante que registros já validados não sejam processados novamente.

* **Erro parcial** -- Se um CPF falhar, o script marca como "Erro" e continua processando os demais.

---

## Perguntas frequentes

### O que é necessário para implementar validação de CPF neste contexto?
A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

### 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.

### Quanto tempo leva para integrar a API CPFHub.io?
A integração básica leva menos de 30 minutos: 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`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

### Leia também

- [Como consumir API de CPF em n8n para automações self-hosted](https://cpfhub.io/blog/como-consumir-api-cpf-n8n-automacoes-self-hosted)
- [Como consumir API de CPF em Google Apps Script para automações no Google Sheets](https://cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [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)

---

## Conclusão

Integrar a API da CPFHub.io ao Notion transforma um processo manual e propenso a erros em um fluxo automatizado e auditável, com dados de nome, gênero e data de nascimento preenchidos diretamente no database a cada execução do script.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.