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

# Criando Tools com SQL

> Configure as consultas SQL que o Plug4ia usa para responder perguntas dos usuários pelo WhatsApp.

As **Tools** são as consultas que a Software House configura para que o Plug4ia responda perguntas pelo WhatsApp.

Cada Tool pertence a um ERP, possui um agente responsável, uma descrição e uma **consulta SQL**. Quando o usuário faz uma pergunta, o Plug4ia usa a descrição das Tools para escolher a consulta mais adequada e buscar os dados no ambiente integrado da empresa.

<Info>
  A qualidade da resposta depende diretamente da Tool cadastrada. Nome, descrição e SQL precisam deixar claro qual pergunta a consulta responde.
</Info>

## Campos da Tool

| Campo        | Descrição                                 |
| ------------ | ----------------------------------------- |
| ERP          | ERP ao qual a Tool pertence               |
| Nome da Tool | Nome curto para identificação no portal   |
| Agente       | Área responsável pela consulta            |
| Descrição    | Explicação do que a Tool responde         |
| Consulta SQL | SQL executada para buscar os dados        |
| Tool ativa   | Define se a Tool está disponível para uso |

## Agentes disponíveis

Selecione o agente que melhor representa o assunto da consulta.

| Agente                     | Use para                                             |
| -------------------------- | ---------------------------------------------------- |
| Agente de Vendas           | Faturamento, vendas, ticket médio, produtos vendidos |
| Agente de Compras          | Compras, fornecedores, itens comprados               |
| Agente de Produtos         | Estoque, preços, margem, cadastro de produtos        |
| Agente de Contas a Receber | Clientes devedores, títulos em aberto, recebimentos  |
| Agente de Contas a Pagar   | Contas a vencer, pagamentos, fornecedores em atraso  |

## Criando uma Tool

<Steps>
  <Step title="Acesse Tools">
    No menu lateral, clique em **Tools**.
  </Step>

  <Step title="Clique em Nova Tool">
    O formulário de cadastro será aberto.
  </Step>

  <Step title="Selecione o ERP e o agente">
    Escolha o ERP da consulta e o agente responsável pelo assunto.
  </Step>

  <Step title="Informe nome e descrição">
    Use uma descrição objetiva, escrita como uma explicação do que a consulta responde.

    Exemplo: "Retorna o total de vendas por dia em um período informado pelo usuário."
  </Step>

  <Step title="Configure a consulta SQL">
    Escreva a SQL no campo **Consulta SQL**.
  </Step>

  <Step title="Ative e salve">
    Marque **Tool ativa** quando a consulta já estiver validada e clique em **Salvar tool**.
  </Step>
</Steps>

## Regras para consulta SQL

As consultas devem ser de leitura e retornar apenas os dados necessários para a resposta.

| Regra                        | Orientação                                                          |
| ---------------------------- | ------------------------------------------------------------------- |
| Use SELECT                   | A consulta deve iniciar com SELECT e conter FROM                    |
| Liste colunas explicitamente | Evite `SELECT *`; informe cada coluna necessária                    |
| Evite múltiplas instruções   | Não use várias consultas separadas por ponto e vírgula              |
| Não altere dados             | Não use INSERT, UPDATE, DELETE, DROP, ALTER ou comandos semelhantes |
| Evite bloqueios              | Não use comandos que bloqueiem tabelas ou registros                 |
| Retorne dados objetivos      | Prefira colunas com nomes claros para facilitar a resposta          |

<Warning>
  Valide cada SQL antes de ativar a Tool. A consulta será usada para responder usuários reais pelo WhatsApp.
</Warning>

## Parâmetros na SQL

Use parâmetros para permitir que o Plug4ia preencha valores conforme a pergunta do usuário.

Parâmetros encontrados no catálogo atual:

| Parâmetro         | Uso                                                                   |
| ----------------- | --------------------------------------------------------------------- |
| `@erp_empresa_id` | Identificador da empresa dentro do ERP                                |
| `@data_ini`       | Data inicial de um período                                            |
| `@data_fim`       | Data final de um período                                              |
| `@data_inicio`    | Data inicial usada em algumas consultas financeiras                   |
| `@top_n`          | Quantidade máxima de itens em rankings                                |
| `@order_by`       | Critério de ordenação, como receita, margem ou quantidade             |
| `@nome`           | Nome parcial de cliente, fornecedor, produto ou lote, conforme a Tool |
| `@nome_produto`   | Nome ou trecho do nome do produto                                     |
| `@produto_id`     | Código interno do produto                                             |
| `@produto_nome`   | Nome ou trecho do nome do produto                                     |
| `@codigo_barras`  | Código de barras do produto                                           |
| `@codigo_ean`     | Código EAN do produto                                                 |
| `@grupos`         | Lista de grupos de produto                                            |
| `@lote`           | Lote de produto                                                       |
| `@numero_nota`    | Número da nota de compra                                              |
| `@fornecedor_id`  | Código interno do fornecedor                                          |
| `@pagar_id`       | Código interno do documento a pagar                                   |
| `@receber_id`     | Código interno do documento a receber                                 |
| `@documento`      | Número do documento                                                   |

<Tip>
  Use nomes claros nos parâmetros. Isso ajuda a relacionar a pergunta do usuário com os filtros da consulta.
</Tip>

<Note>
  O catálogo atual usa principalmente `@data_ini`, `@data_fim` e `@erp_empresa_id`. Ao criar novas Tools, mantenha esse padrão sempre que possível para facilitar manutenção e reaproveitamento.
</Note>

## Exemplo: resumo de vendas

**Nome da Tool:** `vendas_completo`

**Agente:** Agente de Vendas

**Descrição:** Retorna quantidade de vendas, total faturado e ticket médio entre duas datas.

```sql theme={null}
SELECT
  @data_ini AS data_ini,
  COALESCE(@data_fim, @data_ini) AS data_fim,
  DATEDIFF(COALESCE(@data_fim, @data_ini), @data_ini) + 1 AS dias,
  COUNT(DISTINCT v.venda_id) AS qtd_vendas,
  ROUND(SUM(v.valor_total_liquido), 2) AS total,
  ROUND(SUM(v.valor_total_liquido) / NULLIF(COUNT(DISTINCT v.venda_id), 0), 2) AS ticket_medio
FROM venda v
WHERE v.cancelada = 0
  AND v.devolvida = 0
  AND v.data_hora >= @data_ini
  AND v.data_hora < DATE_ADD(COALESCE(@data_fim, @data_ini), INTERVAL 1 DAY)
  AND v.empresa_id = @erp_empresa_id
```

Perguntas que essa Tool pode responder:

```text theme={null}
Quanto vendemos ontem?
```

```text theme={null}
Qual foi o faturamento desta semana?
```

## Exemplo: produtos mais vendidos

**Nome da Tool:** `top_produtos_mais_vendidos`

**Agente:** Agente de Vendas

**Descrição:** Ranking de produtos mais vendidos por receita, margem ou quantidade.

```sql theme={null}
SELECT
  pr.nome AS produto,
  ROUND(COALESCE(SUM(vi.valor_total_liquido), 0), 2) AS receita,
  ROUND(COALESCE(SUM(vi.quantidade * vi.preco_custo_bruto), 0), 2) AS custo,
  ROUND(COALESCE(SUM(vi.valor_total_liquido), 0) - COALESCE(SUM(vi.quantidade * vi.preco_custo_bruto), 0), 2) AS margem,
  ROUND(COALESCE(SUM(vi.quantidade), 0), 3) AS quantidade
FROM venda_item vi
JOIN venda v ON v.venda_id = vi.venda_id
JOIN produto pr ON pr.produto_id = vi.produto_id
WHERE vi.cancelada = 0
  AND v.cancelada = 0
  AND v.devolvida = 0
  AND v.data_hora >= @data_ini
  AND v.data_hora < DATE_ADD(COALESCE(@data_fim, @data_ini), INTERVAL 1 DAY)
  AND pr.tipo = 0
  AND v.empresa_id = @erp_empresa_id
GROUP BY pr.nome
ORDER BY
  CASE WHEN @order_by = 'receita' THEN receita END DESC,
  CASE WHEN @order_by = 'margem' THEN margem END DESC,
  CASE WHEN @order_by = 'quantidade' THEN quantidade END DESC,
  receita DESC
LIMIT @top_n
```

Perguntas que essa Tool pode responder:

```text theme={null}
Quais produtos mais venderam este mês?
```

```text theme={null}
Me mostre os 10 produtos com maior venda na semana.
```

## Exemplo: contas a receber por período

**Nome da Tool:** `contas_receber_clientes_periodo`

**Agente:** Agente de Contas a Receber

**Descrição:** Retorna documentos de contas a receber com saldo em aberto que vencem dentro de um período.

```sql theme={null}
SELECT
  r.cliente_id,
  p.nome_razao_social AS cliente,
  r.documento,
  r.vencimento,
  (r.valor - r.desconto + r.acrescimo) AS valor_original,
  r.valor_pago,
  ((r.valor - r.desconto + r.acrescimo) - r.valor_pago) AS saldo_em_aberto
FROM receber r
JOIN pessoa p ON p.pessoa_id = r.cliente_id
WHERE r.empresa_id = @erp_empresa_id
  AND r.excluido = 0
  AND r.substituido = 0
  AND r.realizado = 1
  AND r.vencimento >= @data_ini
  AND r.vencimento < DATE_ADD(@data_fim, INTERVAL 1 DAY)
  AND ((r.valor - r.desconto + r.acrescimo) - r.valor_pago) > 0
ORDER BY r.vencimento, p.nome_razao_social
```

Perguntas que essa Tool pode responder:

```text theme={null}
Quais clientes estão com títulos vencidos?
```

```text theme={null}
Mostre as contas a receber vencidas até hoje.
```

## Exemplo: consulta de produto por código

**Nome da Tool:** `consulta_produto_codigo`

**Agente:** Agente de Produtos

**Descrição:** Detalhes de produto com preços, margem, grupo e estoque filtrando por ID ou código EAN.

```sql theme={null}
SELECT
  p.produto_id,
  COALESCE(ean.codigo_ean, '') AS codigo_ean,
  p.nome AS produto,
  COALESCE(pg.nome, '') AS grupo_produto,
  COALESCE(MAX(pp.preco_custo), 0) AS preco_custo,
  COALESCE(MAX(pp.preco_venda), 0) AS preco_venda,
  COALESCE(MAX(pp.margem_lucro), 0) AS margem_lucro,
  COALESCE(SUM(pe.quantidade), 0) AS estoque
FROM produto p
LEFT JOIN produto_codigo_ean ean ON ean.produto_id = p.produto_id
LEFT JOIN produto_grupo pg ON pg.produto_grupo_id = p.produto_grupo_id
LEFT JOIN produto_preco pp
  ON pp.produto_id = p.produto_id
  AND pp.empresa_id = @erp_empresa_id
  AND pp.produto_grade_id IS NULL
LEFT JOIN produto_estoque pe
  ON pe.produto_id = p.produto_id
  AND pe.empresa_id = @erp_empresa_id
LEFT JOIN produto_empresa pem
  ON pem.produto_id = p.produto_id
  AND pem.empresa_id = @erp_empresa_id
  AND pem.excluido = 0
  AND pem.ativo = 1
WHERE pem.produto_id IS NOT NULL
  AND (
    (@produto_id IS NOT NULL AND p.produto_id = @produto_id)
    OR (@codigo_ean IS NOT NULL AND ean.codigo_ean = @codigo_ean)
  )
GROUP BY p.produto_id
```

Perguntas que essa Tool pode responder:

```text theme={null}
Qual o estoque do produto 123?
```

```text theme={null}
Me mostre o preço e a margem do produto parafuso.
```

## Exemplo: compras por período

**Nome da Tool:** `compras_resumo_periodo`

**Agente:** Agente de Compras

**Descrição:** Total de compras, quantidade de notas e ticket médio de compra no período.

```sql theme={null}
SELECT
  @data_ini AS data_ini,
  COALESCE(@data_fim, @data_ini) AS data_fim,
  COUNT(DISTINCT c.compra_id) AS qtd_compras,
  ROUND(COALESCE(SUM(c.valor_total_liquido), 0), 2) AS total_compras,
  ROUND(COALESCE(SUM(c.valor_total_liquido), 0) / NULLIF(COUNT(DISTINCT c.compra_id), 0), 2) AS ticket_medio_compra
FROM compra c
WHERE c.empresa_id = @erp_empresa_id
  AND c.cancelada = 0
  AND c.devolvida = 0
  AND c.data_entrada >= @data_ini
  AND c.data_entrada < DATE_ADD(COALESCE(@data_fim, @data_ini), INTERVAL 1 DAY)
```

Perguntas que essa Tool pode responder:

```text theme={null}
Quanto compramos este mês?
```

```text theme={null}
Qual foi o ticket médio das compras da semana?
```

## Exemplo: contas a pagar a vencer

**Nome da Tool:** `contas_pagar_documentos_a_vencer`

**Agente:** Agente de Contas a Pagar

**Descrição:** Documentos com saldo que vencem no período informado.

```sql theme={null}
SELECT
  p.pagar_id,
  p.documento,
  p.emissao,
  p.vencimento,
  f.pessoa_id AS fornecedor_id,
  f.nome_razao_social AS fornecedor_razao_social,
  (p.valor - p.desconto + p.acrescimo) AS valor_total,
  p.valor_pago,
  (p.valor - p.desconto + p.acrescimo) - p.valor_pago AS saldo,
  DATEDIFF(p.vencimento, CURDATE()) AS dias_para_vencer
FROM pagar p
JOIN pessoa f ON f.pessoa_id = p.fornecedor_id
WHERE p.empresa_id = @erp_empresa_id
  AND p.excluido = 0
  AND p.realizado = 1
  AND p.valor_pago < (p.valor - p.desconto + p.acrescimo)
  AND p.vencimento BETWEEN @data_ini AND @data_fim
ORDER BY p.vencimento ASC, f.nome_razao_social ASC
```

Perguntas que essa Tool pode responder:

```text theme={null}
O que vence nos próximos 7 dias?
```

```text theme={null}
Quais contas a pagar vencem hoje?
```

## Boas práticas para descrições

Uma boa descrição ajuda o Plug4ia a escolher a Tool correta.

| Evite             | Prefira                                                              |
| ----------------- | -------------------------------------------------------------------- |
| "Consulta vendas" | "Retorna o total de vendas por período informado pelo usuário"       |
| "Produtos"        | "Consulta estoque, preço e margem de um produto pelo nome ou código" |
| "Financeiro"      | "Lista títulos vencidos a receber até uma data informada"            |

## Ativando e desativando Tools

Use o status para controlar se a consulta está disponível.

* **Ativa**: pode ser usada para responder perguntas.
* **Inativa**: permanece cadastrada, mas não deve ser usada nas respostas.

<Warning>
  Ao desativar uma Tool, perguntas que dependem dela podem deixar de ser respondidas.
</Warning>

## Filtros e manutenção

Na tela de Tools, você pode filtrar por:

* Nome.
* Descrição.
* ERP.
* Agente.
* Status.

Também é possível visualizar detalhes, copiar a SQL, editar ou excluir uma Tool.

<Note>
  Excluir uma Tool remove a consulta do portal. Se você só precisa suspender o uso temporariamente, inative a Tool.
</Note>