> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maketalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bloco Buscar Dados

> Consulte informações de APIs, atributos de contato ou conversa para usar em decisões automáticas

## O que é o Bloco Buscar Dados?

O bloco **Buscar Dados** permite que o agente consulte informações de forma automática e silenciosa — sem envolver a IA. Ele busca um dado específico (de uma API externa, de um atributo do contato ou da conversa) e armazena o resultado em uma variável, que pode ser usada em seguida por um bloco **Condição** para tomar decisões.

<Frame caption="Painel de configuração do Bloco Buscar Dados">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/maketalk-7da59a87/images/administradores/flow-builder/bloco-buscar-dados.png" alt="Configuração do bloco Buscar Dados" />
</Frame>

### Por que usar?

| Benefício                   | Descrição                                          |
| --------------------------- | -------------------------------------------------- |
| **Decisões instantâneas**   | Sem esperar a IA processar — execução imediata     |
| **Sem custo de LLM**        | Não consome tokens de IA para buscar o dado        |
| **Resultados previsíveis**  | Sempre busca a mesma informação da mesma forma     |
| **Integração com Chatwoot** | Acessa atributos de contato e conversa diretamente |

***

## Como funciona?

```
Conversa chega → Buscar Dados executa automaticamente
                        ↓
              Consulta a fonte configurada
              (API, atributo de contato ou conversa)
                        ↓
              Armazena o resultado na variável
              (ex: fetched.plano)
                        ↓
              Bloco Condição avalia o valor
              (ex: se fetched.plano = "premium")
                        ↓
              Direciona para o caminho correto
              (verdadeiro ou falso)
```

<Tip>
  O bloco Buscar Dados foi projetado para funcionar em conjunto com o bloco **Condição (modo Determinístico)**. Juntos, eles formam uma cadeia de decisão automática que não depende da IA.
</Tip>

***

## Fontes de Dados

O bloco oferece três fontes de dados diferentes, dependendo de onde a informação está:

### 1. Atributo do Contato

Busca um campo dos **atributos personalizados do contato** no Chatwoot. Ideal para identificar características do cliente que já estão cadastradas.

| Campo                 | Descrição                  | Exemplo                                |
| --------------------- | -------------------------- | -------------------------------------- |
| **Chave do Atributo** | Nome do campo no Chatwoot  | `plano`, `segmento`, `cliente_habitue` |
| **Variável de Saída** | Onde armazenar o resultado | `fetched.plano`                        |

<Tabs>
  <Tab title="Exemplo: Plano do cliente">
    **Configuração:**

    * Fonte: Atributo do Contato
    * Chave do Atributo: `plano`
    * Variável de Saída: `fetched.plano`

    **Resultado:** Se o contato tem `plano = "premium"`, a variável `fetched.plano` recebe `"premium"`.

    **Condição seguinte:** Se `fetched.plano` igual a `"premium"` → caminho VIP.
  </Tab>

  <Tab title="Exemplo: Tipo de parceiro">
    **Configuração:**

    * Fonte: Atributo do Contato
    * Chave do Atributo: `tipo_parceiro`
    * Variável de Saída: `fetched.tipo_parceiro`

    **Resultado:** Se o contato tem `tipo_parceiro = "agencia"`, o agente pode redirecionar automaticamente.
  </Tab>
</Tabs>

<Note>
  Os atributos disponíveis são os mesmos que você configura em **Chatwoot > Configurações > Atributos Personalizados**. Se o atributo não existir no contato, o valor retornado será vazio.
</Note>

***

### 2. Atributo da Conversa

Busca um campo dos **atributos personalizados da conversa** no Chatwoot. Útil para informações que mudam de conversa para conversa.

| Campo                 | Descrição                  | Exemplo                               |
| --------------------- | -------------------------- | ------------------------------------- |
| **Chave do Atributo** | Nome do campo na conversa  | `status_pagamento`, `origem_campanha` |
| **Variável de Saída** | Onde armazenar o resultado | `fetched.status_pagamento`            |

**Exemplo prático:**

```
Fonte: Atributo da Conversa
Chave: status_pagamento
Variável: fetched.status_pagamento

→ Se o valor for "pendente", transfere para equipe financeira
→ Se o valor for "pago", continua atendimento normal
```

***

### 3. API Externa (HTTP)

Consulta uma API externa via HTTP para obter informações em tempo real. Útil para consultar sistemas internos (ERP, CRM, sistema de reservas, etc.).

| Campo                 | Descrição                    | Exemplo                   |
| --------------------- | ---------------------------- | ------------------------- |
| **Método HTTP**       | GET, POST, PUT, etc.         | `GET`                     |
| **URL Base**          | Endereço da API              | `https://api.exemplo.com` |
| **Endpoint**          | Caminho do recurso           | `/api/v1/clientes/status` |
| **JSONPath**          | Caminho para extrair o valor | `$.data.status`           |
| **Variável de Saída** | Onde armazenar o resultado   | `fetched.status`          |

<AccordionGroup>
  <Accordion title="O que é JSONPath?">
    JSONPath é uma forma de navegar dentro de uma resposta JSON para extrair um valor específico.

    **Exemplo de resposta da API:**

    ```json theme={null}
    {
      "data": {
        "cliente": "João",
        "status": "ativo",
        "plano": "premium"
      }
    }
    ```

    | JSONPath         | Resultado   |
    | ---------------- | ----------- |
    | `$.data.status`  | `"ativo"`   |
    | `$.data.plano`   | `"premium"` |
    | `$.data.cliente` | `"João"`    |
  </Accordion>

  <Accordion title="Autenticação da API">
    Se sua API exige autenticação, configure na seção **Autenticação**:

    | Tipo             | Quando usar             |
    | ---------------- | ----------------------- |
    | **Nenhuma**      | API pública             |
    | **API Key**      | Enviar chave via header |
    | **Bearer Token** | Token de acesso         |
    | **Basic Auth**   | Usuário e senha         |
  </Accordion>
</AccordionGroup>

<Warning>
  A API externa é chamada a cada mensagem que passa pelo bloco. Configure com moderação para não sobrecarregar seus sistemas. Para informações que mudam raramente, prefira atributos de contato.
</Warning>

***

## Variável de Saída

Toda informação buscada é armazenada em uma **variável de saída** que começa obrigatoriamente com `fetched.`.

| Regra                   | Descrição                                  |
| ----------------------- | ------------------------------------------ |
| **Prefixo obrigatório** | Toda variável começa com `fetched.`        |
| **Nome livre**          | Após o prefixo, escolha um nome descritivo |
| **Usado na Condição**   | O bloco Condição referencia esta variável  |

**Exemplos de nomes:**

| Fonte                        | Variável                   | Uso                        |
| ---------------------------- | -------------------------- | -------------------------- |
| Contato: `plano`             | `fetched.plano`            | Verificar plano do cliente |
| Contato: `cliente_habitue`   | `fetched.cliente_habitue`  | Identificar cliente VIP    |
| Conversa: `status_pagamento` | `fetched.status_pagamento` | Checar pagamento           |
| API: retorno JSON            | `fetched.tem_reserva`      | Verificar reserva ativa    |

***

## Conectando ao Fluxo

O bloco Buscar Dados funciona como parte de uma **cadeia de decisão automática**:

```
[Início] → [Buscar Dados] → [Condição Determinística] → [Próximo bloco]
                                       │
                                       ├─ Verdadeiro → [Transferência / Cotação / etc.]
                                       │
                                       └─ Falso → [Roteador / IA responde]
```

<Steps>
  <Step title="Adicione o bloco Buscar Dados">
    Arraste o bloco para o canvas e conecte-o ao bloco **Início** (ou a uma rota do **Roteador**).
  </Step>

  <Step title="Configure a fonte de dados">
    Escolha entre API Externa, Atributo do Contato ou Atributo da Conversa. Preencha os campos necessários.
  </Step>

  <Step title="Defina a variável de saída">
    Escolha um nome descritivo com o prefixo `fetched.` (ex: `fetched.plano`).
  </Step>

  <Step title="Conecte ao bloco Condição">
    Arraste uma conexão da saída do Buscar Dados para um bloco **Condição** configurado no modo **Determinístico**.
  </Step>

  <Step title="Configure a condição">
    No bloco Condição, use a mesma variável (ex: `fetched.plano`) e defina a regra (ex: igual a "premium").
  </Step>
</Steps>

<Warning>
  O bloco Buscar Dados deve ter **apenas uma conexão de entrada** e estar conectado diretamente a um bloco Condição (modo Determinístico). Não conecte outros blocos entre eles.
</Warning>

***

## Exemplos por Segmento

<Tabs>
  <Tab title="Hotel - Cliente VIP">
    **Objetivo:** Identificar clientes habitués e transferir automaticamente.

    **Fluxo:**

    ```
    [Início] → [Buscar Dados: cliente_habitue] → [Condição: = true?]
                                                       │
                                                       ├─ Sim → [Transferência: equipe VIP]
                                                       │
                                                       └─ Não → [Roteador: fluxo normal]
    ```

    **Configuração do Buscar Dados:**

    * Fonte: Atributo do Contato
    * Chave: `cliente_habitue`
    * Variável: `fetched.cliente_habitue`

    **Configuração da Condição:**

    * Variável: `fetched.cliente_habitue`
    * Operador: Igual a
    * Valor: `true`
  </Tab>

  <Tab title="E-commerce - Plano Premium">
    **Objetivo:** Oferecer atendimento diferenciado para clientes premium.

    **Fluxo:**

    ```
    [Início] → [Buscar Dados: plano] → [Condição: = premium?]
                                              │
                                              ├─ Sim → [Roteador com rotas VIP]
                                              │
                                              └─ Não → [Roteador padrão]
    ```

    **Configuração do Buscar Dados:**

    * Fonte: Atributo do Contato
    * Chave: `plano`
    * Variável: `fetched.plano`

    **Configuração da Condição:**

    * Variável: `fetched.plano`
    * Operador: Igual a
    * Valor: `premium`
  </Tab>

  <Tab title="SaaS - Verificar API">
    **Objetivo:** Consultar API interna para verificar se o cliente tem assinatura ativa.

    **Fluxo:**

    ```
    [Início] → [Buscar Dados: API status] → [Condição: ativo?]
                                                   │
                                                   ├─ Sim → [IA responde]
                                                   │
                                                   └─ Não → [Transferência: vendas]
    ```

    **Configuração do Buscar Dados:**

    * Fonte: API Externa
    * URL: `https://api.meuapp.com/v1/subscription/check`
    * JSONPath: `$.data.status`
    * Variável: `fetched.status_assinatura`
  </Tab>
</Tabs>

***

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="O cliente vê alguma mensagem enquanto o dado é buscado?">
    Não. O bloco Buscar Dados executa de forma totalmente silenciosa. O cliente não percebe que uma consulta foi feita — tudo acontece em milissegundos antes da IA responder.
  </Accordion>

  <Accordion title="Posso usar Buscar Dados sem o bloco Condição?">
    Tecnicamente sim, mas o valor buscado não terá utilidade sem uma condição para avaliá-lo. O bloco foi projetado para funcionar em conjunto com o bloco Condição no modo Determinístico.
  </Accordion>

  <Accordion title="O que acontece se o atributo não existir no contato?">
    A variável de saída recebe um valor vazio. No bloco Condição, você pode usar o operador **Está vazio** para tratar esse caso.
  </Accordion>

  <Accordion title="Qual a diferença entre Buscar Dados e Integração API?">
    São dois modos do mesmo bloco:

    * **Buscar Dados**: Execução automática e silenciosa, sem IA. Armazena resultado em variável para uso em condições.
    * **Integração API (Tool)**: A IA decide quando chamar a API durante a conversa e usa o resultado para responder ao cliente.
  </Accordion>

  <Accordion title="Posso ter vários blocos Buscar Dados no fluxo?">
    Sim, mas cada cadeia (Buscar Dados → Condição) deve ser independente. Evite encadear múltiplos blocos Buscar Dados em sequência.
  </Accordion>
</AccordionGroup>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Bloco Condição" icon="code-branch" href="/administradores/flow-builder/bloco-condicao">
    Configure regras para avaliar os dados buscados.
  </Card>

  <Card title="Bloco Integração API" icon="plug" href="/administradores/flow-builder/bloco-integracao-api">
    Conecte APIs externas para o agente usar durante a conversa.
  </Card>
</CardGroup>