Integração Airtable - Lumina Flow Builder

Visão Geral

A integração Airtable permite que seus fluxos do WhatsApp se conectem diretamente com bases de dados do Airtable, possibilitando criar, buscar, atualizar e deletar registros de forma automatizada.

Operações Disponíveis

Operações Básicas (CRUD)

Operação	Descrição	Arquivo
CREATE	Criar novo registro	create.md
GET	Buscar registro por ID	get.md
UPDATE	Atualizar registro existente	update.md
DELETE	Deletar registro permanentemente	delete.md

Operações de Consulta

Operação	Descrição	Arquivo
LIST	Listar múltiplos registros	list.md
SEARCH	Buscar com filtros complexos	search.md

Operações em Lote

Operação	Descrição	Arquivo
BATCH CREATE	Criar múltiplos registros (máx 10)	batchCreate.md
BATCH UPDATE	Atualizar múltiplos registros (máx 10)	batchUpdate.md

Configuração Inicial

1. Obter API Key do Airtable

1. Acesse: https://airtable.com/account
2. Clique em "Generate API key"
3. Copie o token que começa com pat...

2. Obter Base ID

1. Abra sua base no Airtable
2. Veja a URL: https://airtable.com/appXXXXXXXXXXXXXX/...
3. O Base ID é o código que começa com app

3. Nome da Tabela

Use o nome exato da tabela como aparece no Airtable (case-sensitive).

Casos de Uso Comuns

1. Sistema de Cadastro de Leads

START → INPUT (nome) → EMAIL (email) → PHONE (telefone)
  → AIRTABLE CREATE (criar lead) → MESSAGE (confirmação) → END

Usa: CREATE

2. Consulta de Status de Pedido

START → INPUT (ID do pedido) → AIRTABLE GET (buscar pedido)
  → MESSAGE (exibir status) → END

Usa: GET

3. Atualização de Status Após Pagamento

START → WEBHOOK (pagamento aprovado) → AIRTABLE UPDATE (atualizar status)
  → MESSAGE (notificar cliente) → END

Usa: UPDATE

4. Verificar Duplicata Antes de Cadastrar

START → EMAIL (coletar email) → AIRTABLE SEARCH (buscar por email)
  → CONDITION (existe?)
    → TRUE: MESSAGE (já cadastrado)
    → FALSE: AIRTABLE CREATE (criar novo) → MESSAGE (sucesso)
  → END

Usa: SEARCH, CREATE

5. Processamento em Lote

START → AIRTABLE LIST (buscar leads novos) → LOOP (para cada lead)
  → AIRTABLE UPDATE (marcar como processado) → END

Usa: LIST, UPDATE

6. Cancelamento de Pedido (LGPD)

START → INPUT (ID pedido) → AIRTABLE GET (buscar pedido)
  → MESSAGE (confirmar?) → INPUT (confirmação)
  → CONDITION (confirmou?)
    → TRUE: AIRTABLE DELETE (deletar)
    → FALSE: MESSAGE (cancelado)
  → END

Usa: GET, DELETE

7. Importação em Massa

START → VARIABLE (array de leads) → AIRTABLE BATCH CREATE (criar todos)
  → MESSAGE (confirmação) → END

Usa: BATCH CREATE

Estrutura de um Node Airtable

Exemplo Completo

{
  "id": "airtable_1",
  "type": "airtable",
  "position": { "x": 300, "y": 100 },
  "data": {
    "label": "Criar Lead",
    "operation": "create",
    "config": {
      "apiKey": "patABC123456789xyz",
      "baseId": "appXYZ123456",
      "tableName": "Leads"
    },
    "fields": {
      "Nome": "{{nomeUsuario}}",
      "Email": "{{emailUsuario}}",
      "Data": "{{hoje}}",
      "Origem": "WhatsApp"
    },
    "responseVariable": "leadCriado"
  }
}

Campos Comuns

Campo	Descrição	Obrigatório
operation	Tipo de operação (create, get, update, etc)	Sim
config.apiKey	Token de autenticação do Airtable	Sim
config.baseId	ID da base (app...)	Sim
config.tableName	Nome da tabela	Sim
responseVariable	Nome da variável para armazenar resultado	Não (padrão: "airtableResult")

Campos Específicos por Operação

CREATE / UPDATE: - fields: Objeto com campos a criar/atualizar

UPDATE / DELETE / GET: - recordId: ID do registro (rec...)

SEARCH: - filterFormula: Fórmula de filtro Airtable - maxRecords: Limite de resultados (padrão: 100)

LIST: - maxRecords: Limite de resultados (padrão: 100) - view: Nome da view (opcional)

BATCH CREATE / BATCH UPDATE: - records: Array de registros (máx 10)

Acessando Resultados

Após CREATE

{{variavel.id}}              // ID do registro criado
{{variavel.fields.Nome}}     // Campo específico
{{variavel.createdTime}}     // Data de criação

Após GET / UPDATE

{{variavel.id}}              // ID do registro
{{variavel.fields.Campo}}    // Qualquer campo

Após LIST / SEARCH

{{variavel.records.length}}           // Quantidade de registros
{{variavel.records[0].id}}            // ID do primeiro registro
{{variavel.records[0].fields.Nome}}   // Campo do primeiro registro

Após DELETE

{{variavel.success}}         // true se deletado
{{variavel.recordId}}        // ID do registro deletado

Após BATCH CREATE / BATCH UPDATE

{{variavel.records.length}}           // Quantidade atualizada/criada
{{variavel.records[0].id}}            // ID do primeiro registro
{{variavel.records[0].fields.Campo}}  // Campo específico

Variáveis Úteis do Sistema

Variável	Descrição	Exemplo
{{hoje}}	Data atual (YYYY-MM-DD)	"2025-01-15"
{{agora}}	Data e hora atual (ISO)	"2025-01-15T14:30:00Z"
{{nomeUsuario}}	Nome do usuário WhatsApp	"José Roberto"
{{telefoneUsuario}}	Telefone do usuário	"+5511999999999"

Fórmulas de Filtro (SEARCH)

Sintaxe Básica

// Igualdade
{Campo} = 'valor'

// Múltiplas condições (AND)
AND({Campo1} = 'A', {Campo2} = 'B')

// Ou (OR)
OR({Status} = 'Novo', {Status} = 'Pendente')

// Busca parcial
FIND('texto', {Campo})

// Comparação numérica
{Valor} > 100

// Data
IS_BEFORE({DataVencimento}, TODAY())

Exemplos Práticos

// Buscar por email
{Email} = 'jose@exemplo.com'

// Buscar leads ativos
AND({Status} = 'Ativo', {Origem} = 'WhatsApp')

// Buscar pedidos pagos
AND({Status} = 'Pago', {Valor} > 500)

// Buscar nome contendo "Silva"
FIND('Silva', {Nome})

// Buscar tickets abertos e urgentes
AND({Status} = 'Aberto', {Prioridade} = 'Alta')

Boas Práticas

✅ FAZER

1. Sempre validar dados antes de enviar

   INPUT → EMAIL → AIRTABLE CREATE
   

2. Verificar duplicatas antes de criar

   AIRTABLE SEARCH (verificar) → CONDITION → AIRTABLE CREATE
   

3. Usar nomes de campos exatos (case-sensitive)

   "fields": {
     "Nome": "João",     // ✅ Correto
     "nome": "João"      // ❌ Errado se o campo é "Nome"
   }
   

4. Armazenar IDs para operações futuras

   "responseVariable": "leadCriado"
   // Depois: "recordId": "{{leadCriado.id}}"
   

5. Tratar listas vazias

   SEARCH → CONDITION (length > 0) → Processar
   

❌ NÃO FAZER

1. Não expor API Keys em mensagens

   // ❌ NUNCA fazer isso
   "message": "Erro: {{erro}} - API Key: {{apiKey}}"
   

2. Não deletar sem confirmação

   // ❌ Perigoso
   INPUT (ID) → DELETE
   
   // ✅ Correto
   INPUT (ID) → MESSAGE (confirmar?) → INPUT → CONDITION → DELETE
   

3. Não assumir que registro existe

   // ❌ Pode falhar
   GET → UPDATE
   
   // ✅ Correto
   GET → CONDITION (existe?) → UPDATE
   

4. Não criar duplicatas

   // ❌ Sem verificação
   INPUT → CREATE
   
   // ✅ Com verificação
   INPUT → SEARCH → CONDITION → CREATE (se não existe)
   

5. Não exceder limites da API

   // ❌ Mais de 10 registros
   BATCH CREATE com 15 registros
   
   // ✅ Usar LOOP
   LOOP → BATCH CREATE (grupos de 10)
   

Limites da API Airtable

Limite	Valor
Registros por BATCH CREATE	10
Registros por BATCH UPDATE	10
Requisições por segundo	5
Registros por LIST/SEARCH (padrão)	100
Registros por LIST/SEARCH (máximo)	100 por página

Tratamento de Erros

Erros Comuns

1. 401 Unauthorized
2. API Key inválida ou expirada

3. Solução: Verificar token no Airtable

4. 404 Not Found

5. Registro não existe
6. Base ID ou Table Name incorreto

7. Solução: Validar IDs e nomes

8. 422 Unprocessable Entity

9. Fórmula de filtro inválida
10. Campos não existem na tabela

11. Solução: Verificar sintaxe e nomes de campos

12. 429 Too Many Requests

13. Excedeu limite de requisições
14. Solução: Adicionar DELAY entre chamadas

Padrão de Tratamento

AIRTABLE NODE → CONDITION (sucesso?)
  → TRUE: Continuar fluxo
  → FALSE: MESSAGE (erro) → END

Exemplos de Fluxos Completos

1. CRM Simples

Objetivo: Gerenciar leads do WhatsApp no Airtable

START
  → MESSAGE (menu: 1-Cadastrar, 2-Consultar)
  → INPUT (escolha)
  → SWITCH
    CASE 1: INPUT (nome) → EMAIL → SEARCH (verificar)
      → CONDITION → CREATE ou MESSAGE (existe)
    CASE 2: EMAIL → SEARCH → MESSAGE (dados do lead)
  → END

Operações usadas: CREATE, SEARCH

2. Sistema de Pedidos

Objetivo: Gerenciar ciclo completo de pedidos

START
  → LIST (produtos) → MESSAGE (menu)
  → INPUT (escolha produto) → NUMBER (quantidade)
  → CREATE (pedido) → MESSAGE (aguardando pagamento)
  → [webhook pagamento] → UPDATE (status: pago)
  → MESSAGE (confirmação envio) → END

Operações usadas: LIST, CREATE, UPDATE

3. Suporte com Tickets

Objetivo: Sistema de tickets de atendimento

START
  → MESSAGE (descrever problema)
  → INPUT (descrição)
  → CREATE (ticket) → MESSAGE (protocolo: {{ticket.id}})

  [Depois, em outro fluxo]
  → INPUT (número protocolo)
  → GET (ticket) → MESSAGE (status atual)
  → [se resolvido] → UPDATE (feedback coletado)
  → END

Operações usadas: CREATE, GET, UPDATE

Recursos Adicionais

Documentação de Cada Operação

• CREATE - Criar registro
• GET - Buscar por ID
• UPDATE - Atualizar registro
• DELETE - Deletar registro
• LIST - Listar registros
• SEARCH - Buscar com filtros
• BATCH CREATE - Criar múltiplos
• BATCH UPDATE - Atualizar múltiplos

Links Úteis

• Documentação oficial da API Airtable
• Fórmulas do Airtable
• Criar conta Airtable

Suporte

Para dúvidas ou problemas:

1. Consulte a documentação específica da operação
2. Verifique os exemplos de fluxos completos
3. Teste com dados de exemplo antes de usar em produção
4. Valide API Key, Base ID e Table Name

---

Última atualização: 2025-01-15 Total de operações documentadas: 8 Status: ✅ Documentação Completa