Conector Airtable

Conecte suas bases do Airtable ao Brevo para sincronização de CRM, gestão de catálogo de produtos e workflows de marketing automatizados alimentados por dados estruturados através do Tajo.

Visão geral

Recursos

• Sincronização tabela-para-lista - Sincronize registros de tabelas do Airtable diretamente para listas de contatos do Brevo
• Ponte de catálogo de produtos - Use tabelas do Airtable como catálogos de produtos para recomendações por e-mail
• Sincronização de CRM - Sincronização bidirecional entre CRM no Airtable e contatos do Brevo
• Eventos de envio de formulário - Encaminhe envios de formulários do Airtable como eventos do Brevo
• Filtragem baseada em view - Sincronize views específicas do Airtable para listas segmentadas do Brevo
• Automação por webhook - Dispare campanhas do Brevo quando registros do Airtable mudarem

Pré-requisitos

Antes de começar, certifique-se de que você tem:

1. Uma conta Airtable (plano Free ou superior)
2. Um Personal Access Token ou app OAuth configurado
3. Acesso às bases e tabelas que você quer sincronizar
4. Uma conta Brevo com acesso à API
5. Uma conta Tajo com assinatura ativa

Autenticação

O Airtable suporta Personal Access Tokens e OAuth 2.0.

Opção 1: Personal Access Token (Recomendado)

1. Acesse airtable.com/create/tokens
2. Clique em Create new token
3. Nomeie-o como “Tajo Integration”
4. Adicione os escopos:

data.records:read
data.records:write
data.recordComments:read
schema.bases:read
webhook:manage

5. Adicione acesso a bases específicas ou a todas as bases
6. Clique em Create token

Opção 2: OAuth 2.0

Para integrações multi-usuário, use o fluxo OAuth 2.0:

1. Registre sua integração em airtable.com/create/oauth
2. Configure a URI de redirecionamento: https://app.tajo.io/callbacks/airtable
3. Solicite os mesmos escopos acima

Conectando ao Tajo

tajo connectors install airtable \
  --token $AIRTABLE_TOKEN

Configuração

Configuração básica

connectors:
  airtable:
    enabled: true

    sync:
      records: true
      comments: false

    tables:
      - base_id: "appXXXXXXXXXXXXXX"
        table_name: "Customers"
        view: "Active Customers"
        sync_to_list: 28
      - base_id: "appXXXXXXXXXXXXXX"
        table_name: "Products"
        sync_as: "catalog"

Mapeamento de campos

Mapeie campos do Airtable para atributos de contato do Brevo:

field_mapping:
  # Airtable field -> Brevo attribute
  Name: FIRSTNAME
  Email: email
  Phone: SMS
  Company: COMPANY
  Status: LEAD_STATUS
  Revenue: TOTAL_REVENUE
  "Last Contact": LAST_CONTACT_DATE
  Tags: TAGS
  Notes: NOTES
  "Created Time": SIGNUP_DATE

Sincronização baseada em view

views:
  - base_id: "appXXXXXXXXXXXXXX"
    table_name: "Customers"
    view: "High Value"
    sync_to_list: 29
    filter_by_view: true

  - base_id: "appXXXXXXXXXXXXXX"
    table_name: "Customers"
    view: "Churned"
    sync_to_list: 30
    filter_by_view: true

Endpoints da API

O Tajo integra-se com os seguintes endpoints da Web API do Airtable:

Exemplos de código

Inicializar o conector

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('airtable', {
  token: process.env.AIRTABLE_TOKEN
});

Sincronizar tabela para o Brevo

// Sync an Airtable table to a Brevo list
await tajo.connectors.sync('airtable', {
  type: 'full',
  resources: ['records'],
  baseId: 'appXXXXXXXXXXXXXX',
  tableName: 'Customers',
  view: 'Active Customers',
  targetList: 28
});

const status = await tajo.connectors.status('airtable');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T15:00:00Z',
//   recordsSynced: 2340,
//   tablesMonitored: 2,
//   basesConnected: 1
// }

Tratar webhooks

// Airtable webhooks notify of changes; fetch details with cursor
app.post('/webhooks/airtable', async (req, res) => {
  const { base, webhook, timestamp } = req.body;

  // Fetch changed records using webhook cursor
  const changes = await tajo.connectors.getWebhookPayloads('airtable', {
    baseId: base.id,
    webhookId: webhook.id,
    cursor: timestamp
  });

  for (const change of changes) {
    await tajo.connectors.handleEvent('airtable', {
      type: change.actionType,
      payload: change
    });
  }

  res.status(200).send('OK');
});

Criar registro a partir do Brevo

// Create an Airtable record when a Brevo contact converts
tajo.events.on('contact.attribute_updated', async (event) => {
  if (event.attribute === 'LIFECYCLE_STAGE' && event.value === 'customer') {
    await tajo.connectors.create('airtable', {
      baseId: 'appXXXXXXXXXXXXXX',
      tableName: 'Customers',
      fields: {
        Name: event.contact.name,
        Email: event.contact.email,
        Status: 'Customer',
        'Converted Date': new Date().toISOString().split('T')[0]
      }
    });
  }
});

Limites de taxa

O Airtable aplica limites de taxa por base:

Solução de problemas

Problemas comuns

Modo de depuração

connectors:
  airtable:
    debug: true
    log_level: verbose
    log_api_calls: true

Testar conexão

tajo connectors test airtable
# ✓ API authentication successful
# ✓ Base access verified
# ✓ Table schema readable
# ✓ Record listing operational
# ✓ Webhook registration available

Melhores práticas

1. Restrinja tokens a bases específicas - Não conceda acesso a todas as bases a menos que seja necessário
2. Use views para sincronização filtrada - Sincronize views específicas em vez de tabelas completas para reduzir o volume de dados
3. Agrupe operações de registros em lotes - Agrupe criações e atualizações em lotes de 10
4. Trate a paginação - O Airtable retorna 100 registros por página; itere com offset
5. Use webhooks para tempo real - Registre webhooks em vez de fazer polling para detectar mudanças
6. Mapeie tipos de campo precisamente - Combine tipos de campo do Airtable (select, number, date) com os tipos de atributo do Brevo

Segurança

• Personal Access Tokens - Com escopo para bases e operações específicas
• OAuth 2.0 - Fluxo de autorização seguro com refresh tokens
• Somente HTTPS - Toda comunicação com a API é criptografada via TLS 1.2+
• Controle de acesso em nível de base - Tokens com escopo para bases individuais
• Armazenamento criptografado - Tokens criptografados em repouso no Tajo
• Verificação HMAC de webhook - Verifique a autenticidade das notificações de webhook

Recursos relacionados

• Conector Notion
• Conector GitHub
• Skill de sincronização de clientes
• API de contatos do Brevo