Conector de Supabase

Conecta tu proyecto de Supabase para sincronizar registros de base de datos, datos de autenticación de usuarios, eventos de almacenamiento de archivos y cambios en tiempo real para automatizar la interacción con los clientes.

Resumen

Funcionalidades

• REST API autogenerada, Operaciones CRUD en cualquier tabla de Postgres vía PostgREST, sin necesidad de código
• Sincronización de usuarios de Auth, Sincroniza los usuarios de Supabase Auth (email, teléfono, logins sociales) con tu plataforma de engagement
• Suscripciones en tiempo real, Escucha eventos INSERT, UPDATE y DELETE en cualquier tabla en tiempo real
• Row Level Security, Todo el acceso a la API respeta las políticas RLS de Postgres para datos multitenant seguros
• Integración con Storage, Rastrea subidas de archivos y gestiona activos en varios buckets de Storage
• Edge Functions, Invoca funciones serverless en Deno para lógica personalizada y webhooks
• Búsqueda a texto completo, Aprovecha las capacidades de full-text search de Postgres a través de la API

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Un proyecto de Supabase (app.supabase.com)
2. La URL de la API y las API keys de tu proyecto (en Settings → API)
3. Una cuenta de Tajo con acceso a la API

Autenticación

Supabase usa autenticación por API key. Cada petición requiere la cabecera apikey y, opcionalmente, un bearer token en Authorization para acceso con alcance de usuario.

# Using anon key (respects RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <SUPABASE_ANON_KEY>"

# Using service_role key (bypasses RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_SERVICE_ROLE_KEY>" \
  -H "Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>"

Configuración

Configuración básica

connectors:
  supabase:
    enabled: true
    project_url: "https://xyzcompany.supabase.co"
    api_key: "${SUPABASE_SERVICE_ROLE_KEY}"

    # Data sync options
    sync:
      users: true
      tables:
        - customers
        - orders
        - products
      storage: true
      realtime: true

    # Map Supabase Auth users to contacts
    user_mapping:
      email: email
      phone: SMS
      user_metadata.full_name: FIRSTNAME
      created_at: SIGNUP_DATE

Asignación de campos

Asocia columnas de las tablas de Supabase con atributos de la plataforma de engagement:

Asignación personalizada de tablas

table_mapping:
  customers:
    # Column → Attribute mapping
    email: email
    full_name: FIRSTNAME
    company: COMPANY
    plan: SUBSCRIPTION_PLAN
    mrr: MONTHLY_REVENUE
    created_at: SIGNUP_DATE

  orders:
    # Track as events
    sync_as: events
    event_name: "order_placed"
    properties:
      total: amount
      status: order_status
      items: line_items

Endpoints de la API

La REST API de Supabase se autogenera a partir del esquema de tu base de datos en https://<ref>.supabase.co/rest/v1/.

Operadores de filtrado

Eventos

Eventos de Auth

Eventos de base de datos (Realtime)

Eventos de webhook

Ejemplos de código

Inicializar el conector

import { TajoClient } from '@tajo/sdk';
import { createClient } from '@supabase/supabase-js';

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

// Connect Supabase project
await tajo.connectors.connect('supabase', {
  projectUrl: process.env.SUPABASE_URL,
  serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

Sincronizar usuarios como contactos

// Sync all Supabase Auth users as contacts
await tajo.connectors.sync('supabase', {
  type: 'full',
  resources: ['users'],
});

// Incremental sync (new/changed users only)
await tajo.connectors.sync('supabase', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01T00:00:00Z',
});

Escuchar cambios en tiempo real

// Subscribe to new orders for engagement triggers
const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY
);

supabase
  .channel('orders')
  .on('postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'orders' },
    async (payload) => {
      // Forward to Tajo as an event
      await tajo.events.track({
        email: payload.new.customer_email,
        event: 'order_placed',
        properties: {
          order_id: payload.new.id,
          total: payload.new.total,
          items: payload.new.line_items,
        },
      });
    }
  )
  .subscribe();

Consultar y segmentar

// Query customers by plan for targeted campaigns
const { data: proUsers } = await supabase
  .from('customers')
  .select('email, full_name, plan, mrr')
  .eq('plan', 'pro')
  .gt('mrr', 100)
  .order('mrr', { ascending: false });

// Sync to a Brevo list for campaign targeting
await tajo.lists.addContacts(PRO_LIST_ID, proUsers);

Límites de velocidad

Resolución de problemas

Problemas habituales

Modo depuración

connectors:
  supabase:
    debug: true
    log_level: verbose
    log_queries: true
    log_realtime: true

Probar la conexión

tajo connectors test supabase
# ✓ API connection successful
# ✓ Auth endpoint accessible
# ✓ Tables readable (12 tables found)
# ✓ Storage accessible (3 buckets)
# ✓ Realtime connection established
# ✓ Edge Functions available (4 functions)

Buenas prácticas

1. Usa la clave service_role solo en el servidor, Nunca la expongas en código del cliente
2. Habilita RLS en todas las tablas, Incluso con service_role, diseña con RLS como defensa en profundidad
3. Usa Realtime para sincronización dirigida por eventos, Más eficiente que hacer polling de los cambios
4. Agrupa operaciones, Usa inserciones en bulk y el filtro in para operaciones de alto volumen
5. Asigna user metadata, Almacena campos relevantes para el engagement en user_metadata durante el alta
6. Usa Edge Functions para los webhooks, Procesa los webhooks entrantes con Edge Functions de Supabase para una gestión de baja latencia

Seguridad

• Autenticación por API Key, Todas las peticiones requieren API keys válidas
• Row Level Security (RLS), Control de acceso por fila nativo de Postgres
• Verificación JWT, Los tokens de Auth son JWT firmados que se verifican en cada petición
• SSL/TLS, Todas las conexiones se cifran en tránsito
• SOC 2 Type II, Supabase cumple SOC 2
• Restricciones de red, IP allowlisting opcional en planes de pago

Recursos relacionados

• Conector de Shopify
• Conector de Stripe
• Conector de Auth0
• Documentación oficial de Supabase
• Guía de la REST API de Supabase
• Guía de Auth de Supabase