Como integrar validação de CPF em Airtable com scripts de automação

Para integrar validação de CPF em Airtable, basta criar uma automação com o trigger "When a record is created" e uma ação "Run a script" que chama a API da CPFHub.io. A cada novo registro, o script consulta o CPF via GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, retorna nome, gênero e data de nascimento e atualiza os campos automaticamente — sem intervenção manual.

Introdução

O Airtable é amplamente utilizado por equipes de operações, marketing e vendas como base de dados colaborativa. Quando esses times precisam validar CPFs de clientes, leads ou parceiros, a integração com uma API de consulta de CPF diretamente no Airtable elimina processos manuais e reduz erros.

1. Estrutura da base no Airtable

Crie uma tabela com os seguintes campos:

2. Crie a automação

No Airtable, acesse Automations e crie uma nova automação:

• Trigger -- "When a record is created" na tabela de CPFs.

• Action -- "Run a script".

Essa configuração fará com que, a cada novo registro com um CPF, o script de validação seja executado automaticamente.

3. Script de consulta à API

No bloco de ação "Run a script", adicione o seguinte código:

// Configuração
const API_KEY = 'SUA_CHAVE_DE_API';
const BASE_URL = 'https://api.cpfhub.io/cpf';

// Obter o registro que acionou a automação
let inputConfig = input.config();
let recordId = inputConfig.recordId;
let cpf = inputConfig.cpf;

// Limpar CPF (remover pontos e traço)
cpf = cpf.replace(/\D/g, '');

if (cpf.length !== 11) {
    let table = base.getTable('Clientes');
    await table.updateRecordAsync(recordId, {
    'Status': { name: 'Erro' }
    });
    console.log('CPF inválido: deve conter 11 dígitos');
    return;
}

// Consultar a API da CPFHub.io
let controller = new AbortController();
let timeoutId = setTimeout(() => controller.abort(), 5000);

try {
    let response = await fetch(`${BASE_URL}/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': API_KEY,
    'Accept': 'application/json'
    },
    signal: controller.signal
    });

    clearTimeout(timeoutId);

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

    let result = await response.json();

    if (result.success) {
    let table = base.getTable('Clientes');
    await table.updateRecordAsync(recordId, {
    'Nome': result.data.name,
    'Gênero': result.data.gender === 'M' ? 'Masculino' : 'Feminino',
    'Data de Nascimento': result.data.birthDate,
    'Status': { name: 'Validado' }
    });
    console.log(`CPF ${cpf} validado: ${result.data.name}`);
    }
} catch (error) {
    let table = base.getTable('Clientes');
    await table.updateRecordAsync(recordId, {
    'Status': { name: 'Erro' }
    });
    console.log(`Erro na consulta: ${error.message}`);
}

4. Configure as variáveis de entrada

Na configuração do script de automação, defina as Input Variables:

• recordId -- Record ID do registro que acionou o trigger.

• cpf -- Campo CPF do registro.

Essas variáveis são mapeadas no painel lateral do Airtable, conectando o trigger ao script.

5. Exemplo de resposta da API

Quando o script consulta um CPF válido, a CPFHub.io retorna um objeto JSON estruturado com os dados do titular:

{
    "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 script então atualiza o registro no Airtable com o nome, gênero e data de nascimento retornados.

6. Validação manual via botão

Além da automação por trigger, você pode criar um Button field no Airtable que executa um script sob demanda. Isso é útil para revalidar registros existentes:

let table = base.getTable('Clientes');
let record = await input.recordAsync('Escolha o registro', table);

if (!record) {
    console.log('Nenhum registro selecionado');
    return;
}

let cpf = record.getCellValueAsString('CPF').replace(/\D/g, '');
let controller = new AbortController();
let timeoutId = setTimeout(() => controller.abort(), 5000);

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

    clearTimeout(timeoutId);
    let result = await response.json();

    if (result.success) {
    await table.updateRecordAsync(record.id, {
    'Nome': result.data.name,
    'Data de Nascimento': result.data.birthDate,
    'Status': { name: 'Validado' }
    });
    console.log(`Validado: ${result.data.name}`);
    }
} catch (error) {
    console.log(`Erro: ${error.message}`);
}

7. Boas práticas

• Rate limit -- O plano Gratuito permite 1 requisição a cada 2 segundos. Se a automação disparar muitos registros simultaneamente, adicione um delay entre consultas.

• Timeout -- Sempre use AbortController com timeout de 5 segundos para evitar que o script trave.

• Segurança -- Armazene a chave de API como variável de ambiente ou input variable da automação. Evite expor no código.

• Logs -- Use console.log para registrar resultados e facilitar a depuração no histórico de execuções.

• Limites do Airtable -- Scripts de automação têm limite de execução de 30 segundos. Para bases grandes, processe em lotes.

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 cerca de 900ms, 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

A integração da API da CPFHub.io no Airtable transforma um processo manual de validação em um fluxo automatizado e confiável, reduzindo erros cadastrais e poupando horas de trabalho operacional.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.