Pular para conteúdo

Supabase Integration - Lumina Flow Builder

Visão Geral

O Supabase é uma plataforma open-source que fornece backend completo como serviço (BaaS), incluindo banco de dados PostgreSQL, autenticação, storage e muito mais. A integração Supabase no Lumina Flow Builder permite que você conecte seus fluxos de conversação diretamente com bancos de dados Supabase para criar, ler, atualizar e deletar dados em tempo real.

Por que usar Supabase no Flow Builder?

  1. Persistência de Dados: Salve informações coletadas em conversas diretamente no banco
  2. Consultas em Tempo Real: Busque dados atualizados para personalizar fluxos
  3. CRUD Completo: Operações completas de Create, Read, Update, Delete
  4. PostgreSQL Completo: Aproveite todo poder de um banco relacional robusto
  5. Escalabilidade: Supabase escala automaticamente conforme demanda
  6. Sem Servidor: Não precisa gerenciar infraestrutura de banco

Operações Disponíveis

A integração Supabase oferece 5 operações fundamentais:

1. GETROW - Buscar Registro Específico

Busca um único registro pelo ID.

Quando usar: - Carregar perfil de usuário específico - Buscar detalhes de um pedido conhecido - Validar se registro existe antes de operação

Exemplo: 

{
  "operation": "getRow",
  "table": "users",
  "rowId": "{{userId}}",
  "responseVariable": "usuario"
}

2. GETALL - Buscar Múltiplos Registros

Busca lista de registros com filtros, ordenação e paginação.

Quando usar: - Listar produtos de uma categoria - Buscar pedidos pendentes - Encontrar usuário por email - Criar dashboards e relatórios

Exemplo: 

{
  "operation": "getAll",
  "table": "products",
  "filters": {
    "category": "electronics",
    "available": true
  },
  "sort": {
    "field": "price",
    "ascending": true
  },
  "limit": 10,
  "responseVariable": "produtos"
}

3. INSERT - Inserir Novo Registro

Cria um novo registro na tabela.

Quando usar: - Cadastrar novo usuário - Criar pedido - Salvar feedback do cliente - Registrar log de interação

Exemplo: 

{
  "operation": "insert",
  "table": "customers",
  "row": {
    "name": "{{nome}}",
    "email": "{{email}}",
    "phone": "{{telefone}}"
  },
  "responseVariable": "clienteCriado"
}

4. UPDATE - Atualizar Registro Existente

Modifica campos de um registro específico.

Quando usar: - Atualizar status de pedido - Editar perfil de usuário - Incrementar contadores - Registrar última atividade

Exemplo: 

{
  "operation": "update",
  "table": "orders",
  "rowId": "{{orderId}}",
  "updates": {
    "status": "shipped",
    "shipped_at": "{{_timestamp}}"
  },
  "responseVariable": "pedidoAtualizado"
}

5. DELETE - Deletar Registro

Remove permanentemente um registro da tabela.

Quando usar: - Cancelar agendamento - Excluir conta (LGPD/GDPR) - Limpar logs antigos - Remover dados temporários

Exemplo: 

{
  "operation": "delete",
  "table": "appointments",
  "rowId": "{{appointmentId}}",
  "responseVariable": "resultado"
}

Configuração Inicial

1. Obter Credenciais do Supabase

  1. Acesse https://supabase.com
  2. Crie um projeto ou selecione existente
  3. Vá em Settings → API
  4. Copie:
  5. URL (Project URL)
  6. Service Role Key (service_role secret)

⚠️ IMPORTANTE: Nunca exponha Service Role Key em código front-end!

2. Configurar Node no Flow

Todo node Supabase requer configuração básica:

{
  "type": "supabase",
  "data": {
    "operation": "getRow|getAll|insert|update|delete",
    "config": {
      "host": "https://seu-projeto.supabase.co",
      "serviceRole": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "table": "nome_da_tabela",
    "responseVariable": "nomeVariavel"
  }
}

3. Estrutura do Banco

Certifique-se que suas tabelas no Supabase:

  • Têm campo id como chave primária (UUID recomendado)
  • Têm campos created_at e updated_at (timestamp)
  • Têm Row Level Security (RLS) configurado conforme necessidade
  • Têm índices em campos frequentemente filtrados/ordenados

Fluxos de Exemplo Completos

Exemplo 1: Cadastro de Lead Completo

Flow que coleta dados e salva lead no Supabase:

{
  "name": "Cadastro de Lead",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual seu nome?",
          "variableName": "nome"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Qual seu email?",
          "variableName": "email"
        }
      }
    },
    {
      "id": "supabase_1",
      "type": "supabase",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Salvar Lead",
        "operation": "insert",
        "config": {
          "host": "https://projeto.supabase.co",
          "serviceRole": "sua-key"
        },
        "table": "leads",
        "row": {
          "name": "{{nome}}",
          "email": "{{email}}",
          "source": "whatsapp",
          "created_at": "{{_timestamp}}"
        },
        "responseVariable": "lead"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "Cadastro realizado! ID: {{lead.id}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "email_1" },
    { "source": "email_1", "target": "supabase_1" },
    { "source": "supabase_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Exemplo 2: Consulta de Pedido

Flow que busca e exibe status de pedido:

{
  "name": "Consultar Pedido",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Número Pedido",
        "parameters": {
          "message": "Digite o número do pedido:",
          "variableName": "orderNumber"
        }
      }
    },
    {
      "id": "supabase_1",
      "type": "supabase",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Pedido",
        "operation": "getRow",
        "config": {
          "host": "https://projeto.supabase.co",
          "serviceRole": "sua-key"
        },
        "table": "orders",
        "rowId": "{{orderNumber}}",
        "responseVariable": "pedido"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Status",
        "parameters": {
          "message": "Pedido #{{pedido.order_number}}\n\nStatus: {{pedido.status}}\nValor: R$ {{pedido.total}}\nPrevisão: {{pedido.delivery_date}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "supabase_1" },
    { "source": "supabase_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Exemplo 3: Atualizar Status com Switch

Flow que permite escolher novo status de pedido:

{
  "name": "Atualizar Status",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "ID Pedido",
        "parameters": {
          "message": "ID do pedido:",
          "variableName": "orderId"
        }
      }
    },
    {
      "id": "switch_1",
      "type": "switch",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Escolher Status",
        "parameters": {
          "message": "Novo status:\n1-Confirmado\n2-Enviado\n3-Entregue",
          "variableName": "opcao",
          "cases": {
            "1": "confirmed",
            "2": "shipped",
            "3": "delivered"
          }
        }
      }
    },
    {
      "id": "supabase_1",
      "type": "supabase",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Atualizar",
        "operation": "update",
        "config": {
          "host": "https://projeto.supabase.co",
          "serviceRole": "sua-key"
        },
        "table": "orders",
        "rowId": "{{orderId}}",
        "updates": {
          "status": "{{opcao}}",
          "updated_at": "{{_timestamp}}"
        },
        "responseVariable": "pedido"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "Pedido atualizado para: {{pedido.status}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "switch_1" },
    { "source": "switch_1", "target": "supabase_1" },
    { "source": "supabase_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Variáveis Especiais do Sistema

O Flow Builder oferece variáveis especiais que podem ser usadas em operações Supabase:

Variável Descrição Exemplo
{{_from}} Telefone do usuário +5511999999999
{{_timestamp}} Timestamp atual 2025-01-15T10:30:00.000Z
{{_flowId}} ID do fluxo sendo executado flow-12345
{{_userId}} ID do usuário (se autenticado) user-67890

Exemplo de uso: 

{
  "row": {
    "customer_phone": "{{_from}}",
    "created_at": "{{_timestamp}}",
    "flow_source": "{{_flowId}}"
  }
}

Tratamento de Erros

Erros Comuns

  1. "Supabase configuration (host and serviceRole) is required"

  2. Solução: Verifique se config.host e config.serviceRole estão preenchidos

  3. "Supabase getRow error: Row not found"

  4. Solução: ID fornecido não existe na tabela. Verifique o rowId

  5. "Supabase insert error: Duplicate key value violates unique constraint"

  6. Solução: Registro com campo único (ex: email) já existe. Verifique antes de inserir

  7. "Supabase update error: Row not found"

  8. Solução: Tente buscar registro antes de atualizar para confirmar existência

  9. "Supabase delete error: violates foreign key constraint"

  10. Solução: Registro tem dependências. Delete registros dependentes primeiro

Boas Práticas de Tratamento

{
  "nodes": [
    {
      "id": "supabase_1",
      "type": "supabase",
      "data": {
        "operation": "getRow",
        "table": "users",
        "rowId": "{{userId}}",
        "responseVariable": "user"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "data": {
        "parameters": {
          "variable": "{{user}}",
          "operator": "is_defined"
        }
      }
    },
    {
      "id": "message_success",
      "type": "message",
      "data": {
        "parameters": {
          "message": "Usuário encontrado: {{user.name}}"
        }
      }
    },
    {
      "id": "message_error",
      "type": "message",
      "data": {
        "parameters": {
          "message": "Usuário não encontrado. Verifique o ID."
        }
      }
    }
  ]
}

Segurança e Boas Práticas

✅ SEMPRE FAÇA

  1. Use Service Role Key apenas no backend: Nunca exponha em código front-end
  2. Configure Row Level Security (RLS): Proteja dados mesmo com Service Role
  3. Valide dados antes de inserir: Use nodes de validação (EMAIL, PHONE, NUMBER)
  4. Use variáveis para dados dinâmicos: Evite valores hardcoded
  5. Implemente confirmação para delete: Sempre peça confirmação antes de deletar
  6. Registre operações críticas: Salve logs de alterações importantes
  7. Use soft delete quando possível: Marque como deletado ao invés de remover

❌ NUNCA FAÇA

  1. Expor credenciais: Nunca commite Service Role Key no código
  2. Delete sem confirmação: Sempre valide antes de operações destrutivas
  3. Assume sucesso: Sempre trate possíveis erros
  4. Ignore relações: Verifique dependências antes de deletar
  5. Use em loop sem delay: Adicione DELAY para evitar rate limiting
  6. Hardcode IDs: Use variáveis para valores dinâmicos

Performance e Otimização

Índices no Banco

Crie índices em campos frequentemente usados:

-- Índice para busca por email
CREATE INDEX idx_users_email ON users(email);

-- Índice para busca por status
CREATE INDEX idx_orders_status ON orders(status);

-- Índice composto para filtros múltiplos
CREATE INDEX idx_products_category_price ON products(category, price);

Paginação

Para tabelas grandes, use limit:

{
  "operation": "getAll",
  "table": "logs",
  "limit": 50,
  "sort": {
    "field": "created_at",
    "ascending": false
  }
}

Cache

Para dados que mudam pouco, considere cachear resultados:

{
  "nodes": [
    {
      "id": "variable_check",
      "type": "condition",
      "data": {
        "parameters": {
          "variable": "{{cachedProducts}}",
          "operator": "is_defined"
        }
      }
    },
    {
      "id": "supabase_fetch",
      "type": "supabase",
      "data": {
        "operation": "getAll",
        "table": "products",
        "responseVariable": "cachedProducts"
      }
    }
  ]
}

Recursos Adicionais

Documentação

Suporte

Caso tenha dúvidas sobre a integração Supabase:

  1. Consulte a documentação específica de cada operação
  2. Verifique os exemplos completos em cada arquivo
  3. Teste flows no ambiente de desenvolvimento primeiro
  4. Use logs para debugar operações

Última atualização: 2025-01-15 Versão da integração: 1.0.0 Status: ✅ Produção