PIPEDRIVE_PERSON_SEARCH - Buscar Pessoa no Pipedrive

O que é este Node?

O PIPEDRIVE_PERSON_SEARCH é o node responsável por buscar pessoas por nome, email ou termo no Pipedrive CRM.

Por que este Node existe?

Encontrar contatos sem saber o ID é essencial. O PIPEDRIVE_PERSON_SEARCH existe para:

1. Busca Flexível: Encontrar pessoa por nome ou email
2. Evitar Duplicados: Verificar se pessoa já existe antes de criar
3. Descoberta de ID: Obter ID da pessoa para operações posteriores
4. Validação: Confirmar se cliente está cadastrado

Como funciona internamente?

Quando o PIPEDRIVE_PERSON_SEARCH é executado, o sistema:

1. Recebe termo: Coleta texto de busca
2. Processa variáveis: Substitui variáveis
3. Faz requisição GET: Busca em /api/v1/persons/search
4. Retorna resultados: Lista de pessoas que correspondem
5. Salva na variável: Armazena array de resultados

Código interno (pipedrive.executor.ts:57-60):

else if (operation === 'search') {
  const term = this.replaceVariables(node.data.searchTerm, context.variables);
  const response = await axios.get(`${endpoint}/search?${authParam}&term=${encodeURIComponent(term)}`, { headers });
  result = response.data;
}

Quando você DEVE usar este Node?

Use PIPEDRIVE_PERSON_SEARCH quando precisar encontrar pessoa:

Casos de uso

1. Verificar existência: Antes de criar, buscar se já existe
2. Busca por email: Cliente fornece email e você busca cadastro
3. Busca por nome: Encontrar pessoa pelo nome
4. Obter ID: Descobrir ID para usar em outras operações

Quando NÃO usar PIPEDRIVE_PERSON_SEARCH

• Já tem o ID: Use PIPEDRIVE_PERSON_GET diretamente
• Listar todos: Não há operation "list" para persons (use search com termo vazio)

Parâmetros Detalhados

searchTerm (string, obrigatório)

O que é: Termo de busca (nome, email, telefone, etc.)

Exemplo: "João Silva", "joao@email.com", "{{customer_email}}"

Flow completo para testar:

{
  "name": "Teste Pipedrive - Buscar Pessoa",
  "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": "Email",
        "parameters": {
          "message": "Digite seu email:",
          "variableName": "email"
        }
      }
    },
    {
      "id": "pipedrive_1",
      "type": "pipedrive",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar",
        "resource": "persons",
        "operation": "search",
        "config": {
          "apiToken": "{{pipedrive_token}}",
          "companyDomain": "sua-empresa"
        },
        "searchTerm": "{{email}}",
        "responseVariable": "resultado"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Encontrou?",
        "parameters": {
          "variable": "resultado.data.items.length",
          "operator": "greater_than",
          "value": 0
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 0 },
      "data": {
        "label": "Encontrado",
        "parameters": {
          "message": "✅ Cliente encontrado! ID: {{resultado.data.items[0].item.id}}"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 200 },
      "data": {
        "label": "Não Encontrado",
        "parameters": {
          "message": "❌ Cliente não cadastrado. Vamos criar seu cadastro!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "pipedrive_1" },
    { "source": "pipedrive_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_1", "label": "true" },
    { "source": "condition_1", "target": "message_2", "label": "false" },
    { "source": "message_1", "target": "end_1" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Teste: Digite email existente - encontra. Digite email novo - não encontra.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
resource	string	Sim	Deve ser "persons"
operation	string	Sim	Deve ser "search"
searchTerm	string	Sim	Termo de busca
config.apiToken	string	Sim	Token API
config.companyDomain	string	Sim	Subdomínio
responseVariable	string	Não	Variável resposta

Exemplo: Evitar Duplicados

Objetivo: Buscar pessoa antes de criar para evitar duplicação

JSON para Importar

{
  "name": "Pipedrive - Evitar Duplicados",
  "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": "Seu nome:",
          "variableName": "name"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Seu email:",
          "variableName": "email"
        }
      }
    },
    {
      "id": "pipedrive_1",
      "type": "pipedrive",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Buscar Existente",
        "resource": "persons",
        "operation": "search",
        "config": {
          "apiToken": "{{pipedrive_token}}",
          "companyDomain": "sua-empresa"
        },
        "searchTerm": "{{email}}",
        "responseVariable": "busca"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Já Existe?",
        "parameters": {
          "variable": "busca.data.items.length",
          "operator": "equals",
          "value": 0
        }
      }
    },
    {
      "id": "pipedrive_2",
      "type": "pipedrive",
      "position": { "x": 1100, "y": 0 },
      "data": {
        "label": "Criar Novo",
        "resource": "persons",
        "operation": "create",
        "config": {
          "apiToken": "{{pipedrive_token}}",
          "companyDomain": "sua-empresa"
        },
        "person": {
          "name": "{{name}}",
          "email": [{"value": "{{email}}", "primary": true}]
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1300, "y": 0 },
      "data": {
        "label": "Criado",
        "parameters": {
          "message": "✅ Novo cadastro criado!"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1100, "y": 200 },
      "data": {
        "label": "Já Existe",
        "parameters": {
          "message": "Bem-vindo de volta! Já temos seu cadastro."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "email_1" },
    { "source": "email_1", "target": "pipedrive_1" },
    { "source": "pipedrive_1", "target": "condition_1" },
    { "source": "condition_1", "target": "pipedrive_2", "label": "true" },
    { "source": "condition_1", "target": "message_2", "label": "false" },
    { "source": "pipedrive_2", "target": "message_1" },
    { "source": "message_1", "target": "end_1" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Seu nome:
Usuário: Maria Santos
Sistema: Seu email:
Usuário: maria@email.com
Sistema: ✅ Novo cadastro criado!

Resposta do Node

{
  "success": true,
  "data": {
    "items": [
      {
        "result_score": 0.98,
        "item": {
          "id": 123,
          "type": "person",
          "name": "João Silva",
          "email": "joao@email.com",
          "phone": "11999998888",
          "organization": {
            "id": 456,
            "name": "Empresa ABC"
          }
        }
      }
    ]
  }
}

Campos importantes: - data.items: Array de resultados - data.items[0].item.id: ID da primeira pessoa encontrada - data.items[0].result_score: Score de relevância (0-1)

Boas Práticas

✅ SIM:

• Sempre verifique items.length antes de acessar resultados
• Use CONDITION para tratar caso não encontre ninguém
• Busque por email para maior precisão (mais único que nome)
• Verifique result_score para garantir relevância
• Use resultados para evitar criar duplicados
• Salve ID encontrado para usar em operações posteriores

❌ NÃO:

• Assumir que sempre retornará resultados
• Ignorar múltiplos resultados (pessoa pode ter registros duplicados)
• Buscar sem validar termo de busca vazio
• Criar pessoa sem buscar primeiro (risco de duplicação)

Dicas

💡 Dica 1: Email é melhor critério de busca que nome pois é único. Sempre que possível, busque por email.

💡 Dica 2: Use result_score para filtrar resultados: scores acima de 0.8 geralmente são matches relevantes.

💡 Dica 3: Se encontrar múltiplos resultados, considere pedir confirmação ao usuário sobre qual é o correto.

💡 Dica 4: Combine com PERSON_CREATE: busque primeiro, se não encontrar, crie novo. Evita duplicados.

Próximos Nodes

→ PIPEDRIVE_PERSON_GET - Buscar com ID específico → PIPEDRIVE_PERSON_CREATE - Criar nova pessoa → PIPEDRIVE_PERSON_UPDATE - Atualizar pessoa encontrada → PIPEDRIVE_DEAL_CREATE - Criar deal vinculado à pessoa