Connettore Airtable

Collega le tue basi Airtable a Brevo per la sincronizzazione CRM, la gestione del catalogo prodotti e flussi di marketing automation basati su dati strutturati tramite Tajo.

Panoramica

Funzionalità

• Sync tabella-lista - Sincronizza i record delle tabelle Airtable direttamente nelle liste contatti Brevo
• Ponte per catalogo prodotti - Usa le tabelle Airtable come cataloghi prodotti per raccomandazioni via email
• Sincronizzazione CRM - Sync bidirezionale tra CRM Airtable e contatti Brevo
• Eventi da invio form - Inoltra gli invii dei form Airtable come eventi Brevo
• Filtri basati su view - Sincronizza specifiche view Airtable su liste Brevo mirate
• Automazione via webhook - Attiva campagne Brevo quando i record Airtable cambiano

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Airtable (piano Free o superiore)
2. Un Personal Access Token o un’app OAuth configurata
3. Accesso alle basi e tabelle che vuoi sincronizzare
4. Un account Brevo con accesso API
5. Un account Tajo con abbonamento attivo

Autenticazione

Airtable supporta Personal Access Token e OAuth 2.0.

Opzione 1: Personal Access Token (consigliato)

1. Vai su airtable.com/create/tokens
2. Clicca su Create new token
3. Nominalo “Tajo Integration”
4. Aggiungi gli scope:

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

5. Aggiungi l’accesso a basi specifiche o a tutte le basi
6. Clicca Create token

Opzione 2: OAuth 2.0

Per integrazioni multi-utente, usa il flusso OAuth 2.0:

1. Registra la tua integrazione su airtable.com/create/oauth
2. Configura la redirect URI: https://app.tajo.io/callbacks/airtable
3. Richiedi gli stessi scope sopra

Connessione a Tajo

tajo connectors install airtable \
  --token $AIRTABLE_TOKEN

Configurazione

Setup di base

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"

Mapping dei campi

Mappa i campi Airtable agli attributi dei contatti Brevo:

field_mapping:
  # Campo Airtable -> attributo Brevo
  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

Sync basato su 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

Endpoint API

Tajo si integra con i seguenti endpoint della Web API di Airtable:

Esempi di codice

Inizializzare il connettore

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
});

Sincronizzare una tabella su Brevo

// Sincronizza una tabella Airtable su una lista Brevo
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
// }

Gestire i webhook

// I webhook Airtable notificano le modifiche; recupera i dettagli con cursor
app.post('/webhooks/airtable', async (req, res) => {
  const { base, webhook, timestamp } = req.body;

  // Recupera i record modificati usando il cursor del webhook
  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');
});

Creare un record da Brevo

// Crea un record Airtable quando un contatto Brevo converte
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]
      }
    });
  }
});

Limiti di rate

Airtable applica limiti di rate per base:

Risoluzione dei problemi

Problemi comuni

Modalità debug

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

Testare la connessione

tajo connectors test airtable
# ✓ Autenticazione API riuscita
# ✓ Accesso alla base verificato
# ✓ Schema tabella leggibile
# ✓ Elenco record operativo
# ✓ Registrazione webhook disponibile

Best practice

1. Limita gli scope dei token a basi specifiche - Non concedere l’accesso a tutte le basi se non necessario
2. Usa le view per sync filtrati - Sincronizza view specifiche anziché tabelle intere per ridurre il volume di dati
3. Raggruppa le operazioni sui record - Combina create e update in batch da 10
4. Gestisci la paginazione - Airtable restituisce 100 record per pagina; itera con offset
5. Usa i webhook per il real-time - Registra webhook invece di effettuare polling
6. Mappa i tipi di campo con precisione - Fai corrispondere i tipi di campo Airtable (select, number, date) ai tipi di attributo Brevo

Sicurezza

• Personal Access Token - Limitati a basi e operazioni specifiche
• OAuth 2.0 - Flusso di autorizzazione sicuro con refresh token
• Solo HTTPS - Tutte le comunicazioni API cifrate tramite TLS 1.2+
• Controllo accessi a livello di base - Token limitati a singole basi
• Archiviazione cifrata - Token cifrati a riposo in Tajo
• Verifica HMAC dei webhook - Verifica l’autenticità delle notifiche webhook

Risorse correlate

• Connettore Notion
• Connettore GitHub
• Skill Customer Sync
• Brevo Contacts API