Salesforce Integration - Lumina Flow Builder

Visão Geral

A integração Salesforce do Lumina Flow Builder permite criar, atualizar, buscar e gerenciar dados no Salesforce CRM diretamente de conversas no WhatsApp, automatizando processos de vendas, marketing e atendimento ao cliente.

Recursos Disponíveis

O executor Salesforce suporta 11 recursos principais com 44 operações no total:

1. Lead (6 operações)

Gerenciamento de leads - potenciais clientes em prospecção.

create - Criar novo lead
update - Atualizar lead existente
upsert - Criar ou atualizar baseado em ID externo
get - Buscar lead específico por ID
getAll - Listar múltiplos leads com filtros
delete - Excluir lead

Documentação: lead-create.md

2. Contact (7 operações)

Gerenciamento de contatos - pessoas em empresas cliente.

create - Criar novo contato
update - Atualizar contato existente
upsert - Criar ou atualizar baseado em ID externo
get - Buscar contato específico por ID
getAll - Listar múltiplos contatos com filtros
delete - Excluir contato
addToCampaign - Adicionar contato a campanha de marketing

Documentação: contact-create.md

3. Account (6 operações)

Gerenciamento de contas/empresas - organizações cliente.

create - Criar nova empresa
update - Atualizar empresa existente
upsert - Criar ou atualizar baseado em ID externo
get - Buscar empresa específica por ID
getAll - Listar múltiplas empresas com filtros
delete - Excluir empresa

Documentação: account-create.md

4. Opportunity (6 operações)

Gerenciamento de oportunidades - negócios em pipeline.

create - Criar nova oportunidade de venda
update - Atualizar oportunidade existente
upsert - Criar ou atualizar baseado em ID externo
get - Buscar oportunidade específica por ID
getAll - Listar múltiplas oportunidades com filtros
delete - Excluir oportunidade

Documentação: opportunity-create.md

5. Case (6 operações)

Gerenciamento de casos - tickets de suporte e atendimento.

create - Criar novo caso de suporte
update - Atualizar caso existente
get - Buscar caso específico por ID
getAll - Listar múltiplos casos com filtros
delete - Excluir caso
addComment - Adicionar comentário ao caso

Documentação: case-create.md

6. Task (5 operações)

Gerenciamento de tarefas - atividades e follow-ups.

create - Criar nova tarefa
update - Atualizar tarefa existente
get - Buscar tarefa específica por ID
getAll - Listar múltiplas tarefas com filtros
delete - Excluir tarefa

7. Custom Object (6 operações)

Operações em objetos customizados da sua instância.

create - Criar registro em objeto customizado
update - Atualizar registro de objeto customizado
upsert - Criar ou atualizar baseado em ID externo
get - Buscar registro específico por ID
getAll - Listar múltiplos registros com filtros
delete - Excluir registro

8. Document (4 operações)

Gerenciamento de documentos e arquivos.

upload - Fazer upload de documento
get - Buscar documento específico por ID
getAll - Listar múltiplos documentos
delete - Excluir documento

9. Attachment (4 operações)

Gerenciamento de anexos associados a registros.

create - Criar novo anexo
get - Buscar anexo específico por ID
getAll - Listar múltiplos anexos
delete - Excluir anexo

10. User (2 operações)

Consulta de usuários do Salesforce.

get - Buscar usuário específico por ID
getAll - Listar múltiplos usuários com filtros

11. Search (1 operação)

Buscas avançadas com SOQL.

query - Executar query SOQL personalizada

Autenticação

Todas as operações requerem autenticação OAuth2 com Salesforce:

{
  "accessToken": "00D5g000000xxxx!AQcAQH...",
  "instanceUrl": "https://sua-instancia.salesforce.com",
  "refreshToken": "5Aep861...",
  "environment": "production"
}

Parâmetros de Autenticação

Parâmetro	Tipo	Obrigatório	Descrição
accessToken	string	Sim	Token de acesso OAuth2
instanceUrl	string	Sim	URL da instância Salesforce
refreshToken	string	Não	Token para renovação automática
environment	string	Não	"production" ou "sandbox" (padrão: production)

Estrutura Básica de Requisição

{
  "type": "salesforce",
  "parameters": {
    "resource": "lead|contact|account|opportunity|case|task|customObject|document|attachment|user|search",
    "operation": "create|update|upsert|get|getAll|delete|addToCampaign|addComment|query|upload",
    "accessToken": "{{salesforce_token}}",
    "instanceUrl": "{{salesforce_instance}}",
    // ... parâmetros específicos da operação
  }
}

Casos de Uso Principais

1. Captura de Leads

Criar leads automaticamente a partir de conversas qualificadas no WhatsApp.

Recursos: Lead → Contact → Account → Opportunity

2. Suporte ao Cliente

Registrar casos de suporte e acompanhar resolução.

Recursos: Case → Contact → Account → Task

3. Pipeline de Vendas

Gerenciar oportunidades desde prospecção até fechamento.

Recursos: Opportunity → Account → Contact → Task

4. Gestão de Relacionamento

Manter registro atualizado de todos os contatos e interações.

Recursos: Contact → Account → Task → Search

Recursos Avançados

Campos Adicionais (additionalFields)

Todas as operações de criação e atualização suportam additionalFields para campos customizados:

{
  "additionalFields": {
    "Custom_Field__c": "valor",
    "Another_Field__c": 123,
    "Picklist_Field__c": "Option A"
  }
}

Variáveis de Contexto

Todos os campos suportam variáveis do contexto da conversa:

{
  "company": "{{user_company}}",
  "email": "{{user_email}}",
  "phone": "{{user_phone}}"
}

Operações Upsert

Upsert permite criar ou atualizar baseado em campo externo (ex: CNPJ, Email):

{
  "operation": "upsert",
  "externalIdField": "Email",
  "externalIdValue": "{{user_email}}",
  // ... outros campos
}

Queries SOQL

Operação search permite queries customizadas:

{
  "resource": "search",
  "operation": "query",
  "query": "SELECT Id, Name FROM Account WHERE Industry = 'Technology' LIMIT 10"
}

Boas Práticas

✅ Recomendado:

Hierarquia correta: Account → Contact → Opportunity → Task
Validação de dados: Use nodes EMAIL, PHONE antes de criar registros
Evitar duplicatas: Use UPSERT com campos únicos (Email, CNPJ)
Rastreamento: Sempre defina origem/source (ex: "WhatsApp")
Campos obrigatórios: Verifique campos required do Salesforce
Error handling: Use CONDITION para verificar success e tratar erros
Salvar IDs: Armazene IDs retornados para operações futuras

❌ Evitar:

Criar registros sem validação de dados
Duplicar leads/contacts/accounts
Ignorar relacionamentos (accountId, contactId)
Usar credenciais hardcoded (use variáveis)
Criar registros sem contexto mínimo
Não tratar erros de autenticação ou validação

Exemplo Completo: Fluxo de Vendas

{
  "name": "Fluxo Completo Vendas Salesforce",
  "nodes": [
    {
      "id": "start_1",
      "type": "start"
    },
    {
      "id": "qualify_1",
      "type": "input",
      "data": {
        "parameters": {
          "message": "Qual é o nome da sua empresa?",
          "variableName": "company"
        }
      }
    },
    {
      "id": "sf_account_1",
      "type": "salesforce",
      "data": {
        "parameters": {
          "resource": "account",
          "operation": "create",
          "name": "{{company}}"
        }
      }
    },
    {
      "id": "sf_contact_1",
      "type": "salesforce",
      "data": {
        "parameters": {
          "resource": "contact",
          "operation": "create",
          "lastName": "{{user_name}}",
          "accountId": "{{sf_account_1.id}}"
        }
      }
    },
    {
      "id": "sf_opportunity_1",
      "type": "salesforce",
      "data": {
        "parameters": {
          "resource": "opportunity",
          "operation": "create",
          "name": "{{company}} - Novo Negócio",
          "accountId": "{{sf_account_1.id}}",
          "stageName": "Prospecting",
          "closeDate": "2025-12-31"
        }
      }
    },
    {
      "id": "sf_task_1",
      "type": "salesforce",
      "data": {
        "parameters": {
          "resource": "task",
          "operation": "create",
          "subject": "Follow-up {{company}}",
          "whatId": "{{sf_opportunity_1.id}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end"
    }
  ]
}

Limites e Considerações

API Limits

Respeite os limites de API do Salesforce (24h rolling window)
Use operações bulk quando possível para múltiplos registros
Implemente retry logic para erros temporários

Performance

Minimize chamadas de API desnecessárias
Use getAll com filtros ao invés de múltiplos get
Cache dados que mudam raramente (picklists, metadata)

Segurança

Nunca exponha accessToken em logs ou mensagens
Use refreshToken para renovação automática
Implemente timeout adequado nas requisições
Valide dados antes de enviar ao Salesforce

Suporte e Documentação

Arquivo executor: /src/whatsapp-flows/executors/salesforce-executor.service.ts
API Version: v60.0
Documentação Salesforce: https://developer.salesforce.com/docs

Ferramentas Documentadas

Criação (CREATE)

✅ Lead Create - Criar novos leads
✅ Contact Create - Criar contatos
✅ Account Create - Criar empresas
✅ Opportunity Create - Criar oportunidades
✅ Case Create - Criar casos de suporte

Atualização (UPDATE)

Task Create - Criar tarefas e follow-ups
Custom Object - Trabalhar com objetos customizados
Document & Attachment - Gerenciar arquivos

Busca e Consulta (GET/GETALL)

Search Query - Executar queries SOQL customizadas
Get operations - Buscar registros específicos
GetAll operations - Listar múltiplos registros

Operações Especiais

Contact Add to Campaign - Marketing
Case Add Comment - Suporte
Upsert operations - Criar ou atualizar

Próximos Passos

Revise a documentação de cada operação específica
Configure credenciais OAuth2 no seu ambiente
Teste com dados de sandbox antes de produção
Implemente error handling robusto
Monitore uso de API limits

Última atualização: 2025-10-13 Total de operações: 44 Total documentadas: 5 (create operations principais)