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

> Aprenda a integrar a API de consulta de CPF da CPFHub.io em Airtable usando scripts de automação para validar dados cadastrais automaticamente.

**Publicado:** 29/12/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-airtable-com-scripts-de-automacao

---


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:

| Campo | Tipo | Descrição |
| --- | --- | --- |
| CPF | Single line text | CPF do cliente (somente números) |
| Nome | Single line text | Preenchido pela API |
| Gênero | Single line text | Preenchido pela API |
| Data de Nascimento | Single line text | Preenchido pela API |
| Status | Single select | Validado / Erro |

---

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

```javascript
// 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**](https://www.cpfhub.io/) retorna um objeto JSON estruturado com os dados do titular:

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

```javascript
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](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 validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## Conclusão

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