ZENDESK USER SEARCH - Buscar Usuário por Query

O que é este Node?

O ZENDESK USER SEARCH é o node responsável por buscar usuários usando queries de busca (email, nome, etc).

Por que este Node existe?

O ZENDESK USER SEARCH existe para:

Busca por Email: Encontrar usuário pelo email
Verificação de Existência: Checar se usuário já existe antes de criar
Busca Flexível: Procurar por diferentes critérios
Integração: Associar contatos WhatsApp com usuários Zendesk

Como funciona internamente?

Código interno (zendesk.executor.ts:164-170):

case 'search':
  const searchQuery = this.replaceVariables(data.query, context.variables);
  const { data: searchResponse } = await client.get(`/users/search.json?query=${encodeURIComponent(searchQuery)}`);
  return {
    users: searchResponse.users,
    count: searchResponse.users.length,
  };

Quando você DEVE usar este Node?

Use quando precisar buscar usuário por email ou nome:

Verificar se usuário existe (evitar duplicatas)
Encontrar user_id a partir do email
Buscar usuários por critérios flexíveis

Parâmetros

Campo	Tipo	Obrigatório	Descrição
config	object	Sim	Credenciais Zendesk
query	string	Sim	Termo de busca: email, nome, etc (suporta {{variáveis}})
responseVariable	string	Não	Variável para armazenar resposta

Exemplo 1: Buscar por Email e Criar se Não Existir

{
  "name": "Buscar ou Criar Usuário",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Digite seu email:",
          "variable": "email"
        }
      }
    },
    {
      "id": "zendesk_search",
      "type": "zendesk",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Buscar Usuário",
        "resource": "user",
        "operation": "search",
        "config": {
          "subdomain": "sua-empresa",
          "email": "admin@empresa.com",
          "apiToken": "seu_token_api"
        },
        "query": "{{email}}",
        "responseVariable": "busca"
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 550, "y": 50 },
      "data": {
        "label": "Encontrado?",
        "parameters": {
          "conditions": [
            {
              "variable": "busca.count",
              "operator": "greater_than",
              "value": "0"
            }
          ]
        }
      }
    },
    {
      "id": "message_found",
      "type": "message",
      "position": { "x": 700, "y": 50 },
      "data": {
        "label": "Usuário Existe",
        "parameters": {
          "message": "Bem-vindo de volta, {{busca.users[0].name}}!"
        }
      }
    },
    {
      "id": "input_name",
      "type": "input",
      "position": { "x": 700, "y": 150 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual seu nome?",
          "variable": "nome"
        }
      }
    },
    {
      "id": "zendesk_create",
      "type": "zendesk",
      "position": { "x": 850, "y": 150 },
      "data": {
        "label": "Criar Usuário",
        "resource": "user",
        "operation": "create",
        "config": {
          "subdomain": "sua-empresa",
          "email": "admin@empresa.com",
          "apiToken": "seu_token_api"
        },
        "name": "{{nome}}",
        "email": "{{email}}",
        "role": "end-user",
        "responseVariable": "novo_usuario"
      }
    },
    {
      "id": "message_created",
      "type": "message",
      "position": { "x": 1000, "y": 150 },
      "data": {
        "label": "Criado",
        "parameters": {
          "message": "✅ Cadastro realizado, {{nome}}!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1150, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_1", "target": "zendesk_search" },
    { "source": "zendesk_search", "target": "condition_1" },
    { "source": "condition_1", "target": "message_found", "label": "true" },
    { "source": "condition_1", "target": "input_name", "label": "false" },
    { "source": "message_found", "target": "end_1" },
    { "source": "input_name", "target": "zendesk_create" },
    { "source": "zendesk_create", "target": "message_created" },
    { "source": "message_created", "target": "end_1" }
  ]
}

Saída esperada (usuário existe):

Sistema: Digite seu email:
Usuário: joao@email.com
Sistema: Bem-vindo de volta, João Silva!

Saída esperada (novo usuário):

Sistema: Digite seu email:
Usuário: maria@email.com
Sistema: Qual seu nome?
Usuário: Maria Santos
Sistema: ✅ Cadastro realizado, Maria Santos!

Exemplo 2: Buscar Múltiplos Usuários por Domínio

{
  "name": "Buscar Usuários por Domínio",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 250, "y": 100 },
      "data": {
        "label": "Domínio",
        "parameters": {
          "message": "Digite o domínio (ex: empresa.com):",
          "variable": "dominio"
        }
      }
    },
    {
      "id": "zendesk_1",
      "type": "zendesk",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "Buscar por Domínio",
        "resource": "user",
        "operation": "search",
        "config": {
          "subdomain": "sua-empresa",
          "email": "admin@empresa.com",
          "apiToken": "seu_token_api"
        },
        "query": "@{{dominio}}",
        "responseVariable": "resultado"
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 550, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "Encontrados {{resultado.count}} usuários do domínio @{{dominio}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "zendesk_1" },
    { "source": "zendesk_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Resposta do Node

{
  "users": [
    {
      "id": 12345,
      "name": "João Silva",
      "email": "joao@email.com",
      "role": "end-user"
    }
  ],
  "count": 1
}

Boas Práticas

✅ SIM:

Use SEARCH antes de CREATE para evitar duplicatas
Busque por email para encontrar usuário específico
Verifique count > 0 antes de acessar users[0]
Armazene user.id para uso posterior

❌ NÃO:

Não assuma que encontrará resultado - sempre verifique count
Não faça múltiplas buscas seguidas se pode filtrar localmente
Não exponha dados de múltiplos usuários ao cliente final

Dicas

💡 Dica 1: Use query: "{{email}}" para busca exata por email

💡 Dica 2: Combine SEARCH + CONDITION para fluxo "buscar ou criar"

💡 Dica 3: Busca retorna array - sempre verifique count > 0 antes de usar users[0]

💡 Dica 4: Para WhatsApp, busque por {{user_phone}}@whatsapp.temp se usar email temporário

Próximo Node

→ ZENDESK USER CREATE - Criar usuário se não encontrado → ZENDESK USER GET - Buscar por ID encontrado → ZENDESK USER UPDATE - Atualizar usuário encontrado