Como consumir API de CPF em Notion com integrações 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, 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 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 com a API key gerada no painel.

2. Estrutura do database no Notion

Crie um database no Notion com as seguintes propriedades:

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

3. Instale as dependências

npm init -y
npm install @notionhq/client

4. Script de integração

Crie o arquivo validar-cpfs.js:

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:

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:

{
    "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:

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

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 — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.