> ## 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.

# Diagnóstico de Problemas Comuns

> Roteiros práticos para a Software House diagnosticar problemas de WhatsApp, usuários, integrador, Tools, consultas e agendamentos no Plug4ia.

Esta página reúne os problemas mais comuns na operação do **Plug4ia** e os primeiros passos que a Software House deve verificar no Portal Administrativo.

Use esta ordem de diagnóstico sempre que possível: **WhatsApp conectado → usuário ativo → empresa liberada → integrador conectado → Tool ativa → agendamento configurado**.

<AccordionGroup>
  <Accordion title="Usuário envia mensagem e não recebe resposta" icon="message-circle">
    Quando um usuário envia mensagem pelo WhatsApp e não recebe resposta, normalmente existe alguma pendência de cadastro ou permissão.

    **Verifique no portal:**

    1. Acesse **Usuários** e confirme se o usuário está cadastrado.
    2. Confira se o campo **WhatsApp** está preenchido corretamente.
    3. Confirme se o usuário está **ativo**.
    4. Abra **Definir empresas** e verifique se o usuário tem acesso à empresa correta.
    5. Acesse **Configurações → WhatsApp** e confirme se existe um canal conectado.
    6. Acesse **Empresas** e confirme se a empresa está ativa e com integrador conectado.

    <Warning>
      O WhatsApp do usuário é usado para identificar quem está enviando a mensagem. Se o número estiver incorreto, o Plug4ia pode não processar a solicitação.
    </Warning>
  </Accordion>

  <Accordion title="WhatsApp da Software House está desconectado" icon="qr-code">
    Se nenhum usuário consegue conversar com o Plug4ia, verifique primeiro a conexão do canal de WhatsApp.

    **Verifique no portal:**

    1. Acesse **Configurações → WhatsApp**.
    2. Confira a coluna **Status** do canal.
    3. Se estiver desconectado, use a ação de reconectar.
    4. Gere um novo QR Code.
    5. No celular do canal, abra **Aparelhos conectados** e escaneie o QR Code.
    6. Aguarde o portal indicar que o WhatsApp está conectado.

    <Tip>
      Se o QR Code expirar, gere outro código pelo próprio modal de conexão.
    </Tip>
  </Accordion>

  <Accordion title="Integrador aparece desconectado" icon="plug">
    Quando o integrador local aparece desconectado, as consultas daquela empresa podem não retornar dados.

    **Verifique no portal e no cliente:**

    1. Acesse **Empresas** e localize a empresa.
    2. Confira a coluna **Integrador**.
    3. Confirme se a empresa está **ativa**.
    4. Edite a empresa e confira se ela está vinculada ao ERP correto.
    5. No servidor do cliente, confirme se o serviço do integrador está em execução.
    6. No Windows, procure o serviço **Ask2DataIntegrador**.
    7. No Linux, verifique o container do integrador com Docker Compose.
    8. Se um novo token foi gerado recentemente, confirme se o integrador foi reconfigurado com o token atual.

    <Info>
      O integrador precisa estar instalado em uma máquina com acesso ao banco do ERP e com comunicação liberada para o Plug4ia.
    </Info>
  </Accordion>

  <Accordion title="Consulta retorna erro ou resultado vazio" icon="database">
    Quando o Plug4ia responde com erro, dados vazios ou uma resposta diferente do esperado, o problema costuma estar na Tool, na SQL ou no acesso ao banco.

    **Verifique:**

    1. Acesse **Tools** e localize a consulta relacionada.
    2. Confirme se a Tool está **ativa**.
    3. Confira se a Tool está no ERP correto.
    4. Verifique se o **Agente** selecionado corresponde ao assunto da pergunta.
    5. Revise a **Descrição** para garantir que ela explica claramente o que a Tool responde.
    6. Valide a **Consulta SQL** com os mesmos filtros esperados.
    7. Confirme se a empresa está conectada pelo integrador.
    8. Confirme se o usuário tem acesso à empresa consultada.

    <Warning>
      A resposta do Plug4ia depende dos dados retornados pela SQL da Tool. Se a SQL não retorna dados, o WhatsApp também não terá dados para exibir.
    </Warning>
  </Accordion>

  <Accordion title="Pergunta esperada não encontra a Tool correta" icon="wrench">
    Se o usuário pergunta algo que deveria funcionar, mas o Plug4ia não usa a consulta esperada, revise o cadastro da Tool.

    **Verifique:**

    1. O nome da Tool está claro para a equipe?
    2. A descrição explica o tipo de pergunta que ela responde?
    3. A Tool está vinculada ao agente correto?
    4. A Tool está ativa?
    5. Existe outra Tool com descrição muito parecida?
    6. Os parâmetros da SQL seguem nomes claros, como `@data_ini`, `@data_fim`, `@top_n` ou `@nome`?

    <Tip>
      Descrições específicas ajudam mais que descrições genéricas. Prefira "Retorna total de vendas por período" em vez de "Consulta vendas".
    </Tip>
  </Accordion>

  <Accordion title="Agendamento não envia relatório" icon="calendar-clock">
    Se o agendamento está cadastrado, mas o usuário não recebe o relatório no horário esperado, verifique a configuração do usuário e do agendamento.

    **Verifique:**

    1. Acesse **Usuários**.
    2. Abra **Gerenciar agendamentos** no usuário afetado.
    3. Confirme se o agendamento está **ativo**.
    4. Confira empresa, ERP, horário, frequência, agente e ação agendada.
    5. Verifique se o usuário tem acesso à empresa do agendamento.
    6. Confirme se a empresa está ativa e com integrador conectado.
    7. Verifique se existe uma Tool ativa para responder a ação agendada.
    8. Se o envio for em áudio, confirme se a opção **Enviar em áudio** está marcada.

    <Note>
      Resposta em áudio funciona para agendamentos. Consultas pontuais por WhatsApp podem ser enviadas por voz, mas a resposta imediata é em texto.
    </Note>
  </Accordion>

  <Accordion title="Agendamento envia para a empresa errada ou com dados inesperados" icon="building">
    Quando o relatório chega com dados inesperados, revise a empresa escolhida e a ação agendada.

    **Verifique:**

    1. No agendamento, confira o campo **Empresa / ERP**.
    2. Confirme se a ação agendada descreve exatamente o relatório desejado.
    3. Verifique se a Tool usada filtra a empresa corretamente.
    4. Confirme se o usuário não possui acesso a empresas que não deveria consultar.
    5. Teste a consulta manualmente pelo WhatsApp antes de manter o agendamento recorrente.

    <Tip>
      Para clientes com várias empresas, use ações agendadas objetivas e valide o acesso do usuário com atenção.
    </Tip>
  </Accordion>

  <Accordion title="QR Code do WhatsApp não conecta" icon="mobile-screen">
    Se o QR Code aparece, mas o WhatsApp não conecta, o problema costuma estar no celular usado como canal ou no tempo de expiração do QR Code.

    **Verifique:**

    1. O celular tem internet estável.
    2. O WhatsApp está aberto e atualizado.
    3. O usuário acessou **Aparelhos conectados** no WhatsApp.
    4. O QR Code ainda está válido.
    5. O canal não está conectado em outro ambiente de forma conflitante.
    6. Após escanear, aguarde o portal atualizar o status.

    <Info>
      O canal conectado é da Software House. Os usuários finais não precisam escanear QR Code; eles só precisam ter o número cadastrado no usuário.
    </Info>
  </Accordion>
</AccordionGroup>

## Checklist rápido

| Área        | O que verificar                                       |
| ----------- | ----------------------------------------------------- |
| WhatsApp    | Canal conectado em **Configurações → WhatsApp**       |
| Usuário     | Ativo, WhatsApp correto e empresas liberadas          |
| Empresa     | Ativa, ERP correto e integrador conectado             |
| Integrador  | Serviço rodando no cliente e token atual              |
| Tool        | Ativa, SQL validada, agente correto e descrição clara |
| Agendamento | Ativo, horário/frequência corretos e empresa liberada |