n8n-nodes-digisac 1.0.2 → 1.1.0

package/README.md

@@ -1,24 +1,31 @@
 # n8n-nodes-digisac
 
-[![CI](https://github.com/PedroHSGuimaraes/n8n-nodes-digisac/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/PedroHSGuimaraes/n8n-nodes-digisac/actions/workflows/ci.yml)
+Node community do [n8n](https://n8n.io/) para integrar seus fluxos com a **API do [Digisac](https://digisac.com.br)**, plataforma de atendimento multicanal (WhatsApp e outros canais).
 
-Node community do [n8n](https://n8n.io/) para integrar workflows com a **API da Digisac**. O pacote expõe em um único node todas as chamadas publicadas na documentação Postman da Digisac: contatos, chamados, mensagens, campanhas, conexões, departamentos, usuários, tags, templates, webhooks, relatórios, estatísticas, agendamentos e demais recursos operacionais.
+[![CI](https://github.com/PedroHSGuimaraes/n8n-nodes-digisac/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/PedroHSGuimaraes/n8n-nodes-digisac/actions/workflows/ci.yml) [![Apoie no Buy Me a Coffee](https://img.shields.io/badge/Buy_Me_a_Coffee-Apoie_o_projeto-FFDD00?logo=buy-me-a-coffee&logoColor=000000)](https://buymeacoffee.com/qTny0AzFXS)
 
-O projeto segue o mesmo padrão usado no `n8n-nodes-clinicorp`: um node de ação, uma credencial, TypeScript, catálogo gerado a partir da documentação da API, build validado por CI, publicação no npm via GitHub Actions e suporte a uso como Tool de Agente de IA.
+Um único node cobre **todas as chamadas da coleção Postman pública do Digisac**: contatos, chamados, mensagens, campanhas, conexões, departamentos, usuários, tags, templates, webhooks, relatórios, estatísticas, agendamentos e demais recursos.
 
-## Funcionalidades
+[n8n](https://n8n.io/) é uma plataforma de automação de fluxos com [licença fair-code](https://docs.n8n.io/reference/license/).
 
-- **Cobertura completa da documentação**: 298 chamadas da coleção pública Postman da Digisac, organizadas em 51 recursos no n8n.
-- **Node único e intuitivo**: selecione **Resource -> Operation**, preencha campos simples de path, query e body, e execute.
-- **Credencial centralizada**: Base URL e Bearer Token ficam salvos uma única vez na credencial `Digisac API`.
-- **Pronto para AI Agent**: o node tem `usableAsTool: true` e descrições pensadas para LLMs entenderem método, caminho, parâmetros, IDs, filtros, campos de body e quando usar JSON avançado.
-- **Sem dependências runtime**: usa `httpRequestWithAuthentication` do próprio n8n.
-- **Catálogo rastreável**: `nodes/Digisac/generated/endpoints.ts` é gerado da documentação Postman; `docs/api-calls.md` lista todas as chamadas em português.
-- **Publicação segura**: GitHub Actions publica no npm com provenance.
+[Instalação](#-instalação) · [Credenciais](#-credenciais) · [Nós e Operações](#-nós-e-operações) · [Exemplos](#-exemplos-práticos) · [Tool de IA](#-usar-como-tool-de-agente-de-ia) · [Versão 1 ou 2](#-versão-1-ou-2-do-node) · [Desenvolvimento](#️-desenvolvimento) · [Versões](#-versões) · [Apoie](#-apoie-o-projeto)
 
-## Instalação
+---
 
-No n8n, acesse **Settings -> Community Nodes -> Install** e instale:
+## 🚀 Funcionalidades
+
+- **1 node unificado** — `Digisac` com seletor **Resource → Operation**. Cada operation é uma chamada real da API, com método, caminho e origem na documentação.
+- **Cobertura completa** — 298 chamadas em 51 recursos, geradas da coleção pública Postman.
+- **IDs em lista pesquisável (versão 2 do node)** — contato, conexão, departamento, usuário, tag, cargo, robô e assunto de chamado aparecem como lista da sua conta, com busca, e aceitam colar o ID. Os outros IDs aceitam colar o ID no mesmo formato.
+- **Datas e opções guiadas (versão 2 do node)** — período, `From` e `To` têm seletor de data; `Status`, `Period Type`, `Type`, participações e `Origin` são listas de opções.
+- **Workflows salvos não mudam** — quem já usa a versão 1 continua enviando a mesma requisição.
+- **Credencial centralizada** — Base URL e token ficam na credencial `Digisac API`.
+- **Usável como Tool de IA** — o node tem `usableAsTool`, com descrições pensadas para o agente entender método, caminho, parâmetros e cuidados. Veja [Usar como Tool de Agente de IA](#-usar-como-tool-de-agente-de-ia).
+- **Zero dependências de runtime** — usa o `httpRequestWithAuthentication` do próprio n8n, com timeout de 30 s em toda chamada. Passa no lint oficial `n8n-node lint` e é publicado no npm **com provenance**.
+
+## 📦 Instalação
+
+No n8n, acesse **Settings → Community Nodes → Install** e instale:
 
 ```text
 n8n-nodes-digisac
@@ -30,50 +37,112 @@ Para usar community nodes como Tools de Agente de IA em n8n self-hosted, habilit
 N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
 ```
 
-Sem essa variável, o node pode funcionar como node normal, mas não aparecer como tool no AI Agent em instalações self-hosted.
+Sem essa variável, o node funciona como node normal, mas não aparece como tool no AI Agent em instalações self-hosted.
 
-## Credenciais
+## 🔑 Credenciais
 
-Crie uma credencial chamada **Digisac API**.
+Crie uma credencial **Digisac API**.
 
 | Campo | O que preencher | Onde encontrar |
 | --- | --- | --- |
-| **Base URL** | URL base da sua conta Digisac, sem barra final. Exemplo: `https://suaempresa.digisac.app`. | Digisac -> Conta -> Informações |
-| **Access Token** | Token Bearer de acesso pessoal. | Digisac -> Conta -> API -> Tokens de acesso pessoal |
-| **PDF/Base URL** | Base opcional para endpoints documentados como `URLbase`, principalmente export de PDF. Se vazio, o node reutiliza a Base URL. | Use só se sua instância separar URL de API e URL de PDF |
+| **Base URL** | URL base da sua conta, sem barra final. Exemplo: `https://suaempresa.digisac.app`. | Digisac → Conta → Informações |
+| **Access Token** | Token Bearer de acesso pessoal. Tem as mesmas permissões do usuário que o criou. | Digisac → Conta → API → Tokens de acesso pessoal |
+| **PDF/Base URL** | Base opcional para endpoints documentados como `URLbase`, principalmente export de PDF. Se vazio, usa a Base URL. | Use só se sua instância separar a URL de API e a de PDF |
 
-A credencial testa o acesso com:
+A credencial testa o acesso com `GET /api/v1/me`.
 
-```http
-GET /api/v1/me
-```
+## 🧩 Nós e Operações
 
-## Como usar o node
+1. Adicione o node **Digisac** ao workflow.
+2. Escolha o **Resource**. Ele corresponde a uma pasta da documentação, como `Contatos`, `Mensagens`, `Chamados`, `Campanhas`, `Tags`, `Usuários` ou `Webhooks`.
+3. Escolha a **Operation**. Cada uma é uma chamada real da API.
+4. Preencha os IDs de path. Na versão 2, escolha na lista ou cole o ID no modo **By ID**.
+5. Preencha os campos de query que aparecerem, como `Per Page`, `Start Period`, `End Period`, `Status`.
+6. Em chamadas `POST`, `PUT` e `PATCH`, use **Body Fields**: o node gera os campos a partir do body documentado.
+7. Use **Use Body JSON Avancado** só quando a operação exigir array, objeto livre ou algo que não coube nos campos.
+8. Use **Options → Query Avancada JSON** só para filtros sem campo dedicado.
+9. Em exportações CSV, TXT ou PDF, use **Options → Response Format → Text**.
 
-1. Adicione o node **Digisac** no workflow.
-2. Escolha o **Resource**. O resource corresponde a uma pasta da documentação, como `Contatos`, `Mensagens`, `Chamados`, `Campanhas`, `Tags`, `Usuários`, `Webhooks`.
-3. Escolha a **Operation**. Cada operation corresponde a uma chamada real da API.
-4. Preencha os campos obrigatórios de path, como `contactId`, `ticketId`, `serviceId`, `messageId`, `userId`, `campaignId`.
-5. Preencha os campos de query que aparecerem, como `Per Page`, `Number`, `Service Id`, `Start Period`, `End Period`, `Status`.
-6. Em chamadas `POST`, `PUT` e `PATCH`, use **Campos do Body**. O node gera esses campos a partir do body documentado pela Digisac.
-7. Use **Body JSON Avançado** somente quando a operação exigir array, objeto livre ou uma estrutura que não coube nos campos gerados.
-8. Use **Options -> Query Avançada JSON** somente para filtros muito específicos não representados por campos.
-9. Em exports CSV/TXT/PDF, se a resposta não vier como JSON, use **Options -> Response Format -> Text**.
+Resources **Popular** são atalhos herdados da coleção Postman para operações frequentes. Resources **General** têm o catálogo mais completo.
 
-## Campos principais do node
+Regra para automações e Tools de IA: todo campo terminado em `Id` ou `Ids` deve vir de uma busca anterior, de uma entrada confirmada ou de um valor documentado, como `all`. Nunca copie placeholders como `{{contactId}}`.
 
 | Campo | Uso |
 | --- | --- |
-| **Resource** | Área funcional da API Digisac, gerada a partir das pastas Postman. |
-| **Operation** | Chamada exata da API. A descrição mostra método, endpoint, origem na documentação e placeholders. |
-| **Path Parameters** | Campos obrigatórios extraídos de placeholders como `{{contactId}}`. |
-| **Campos de query** | Campos simples gerados a partir da URL documentada. Exemplos: `Per Page`, `Number`, `Service Id`, `From`, `To`, `Type`. |
-| **Campos do Body** | Coleção de campos gerada a partir do body documentado para operações de escrita. Use antes de qualquer JSON manual. |
-| **Use Body JSON Avançado** | Toggle para liberar um editor JSON quando a chamada precisa de array, objeto livre ou payload muito específico. |
-| **Options -> Query Avançada JSON** | Objeto JSON livre mesclado na query string. Use apenas quando a chamada precisar de filtro não representado por campo. |
-| **Options -> Response Format** | Use `Text` para exportações CSV/TXT/PDF ou respostas que não retornam JSON. |
+| **Resource** | Área da API Digisac, gerada das pastas Postman. |
+| **Operation** | Chamada exata da API. A descrição mostra método, endpoint e origem. |
+| **IDs de path** | Obrigatórios, extraídos de placeholders como `{{contactId}}`. |
+| **Campos de query** | Campos simples gerados da URL documentada. |
+| **Body Fields** | Coleção gerada do body documentado para operações de escrita. |
+| **Options → Response Format** | `Text` para respostas que não são JSON. |
+
+### Todas as chamadas da API
 
-## Exemplos práticos
+O catálogo completo fica em [docs/api-calls.md](docs/api-calls.md). Resumo por método:
+
+```text
+GET: 144 | POST: 93 | PUT: 34 | PATCH: 1 | DELETE: 26
+```
+
+Resumo por recurso (gerado por `npm run generate:docs`):
+
+<!-- digisac:recursos:start -->
+| Recurso | Chamadas |
+| --- | ---: |
+| Acionamento flag no robo (General) | 1 |
+| Agendamentos (General) | 5 |
+| Agora (General) | 3 |
+| Agora (Popular) | 3 |
+| Assuntos de chamado (General) | 5 |
+| Auditoria de autenticacao (General) | 2 |
+| Autorizacao (General) | 1 |
+| Autorizacao (Popular) | 1 |
+| Avaliacoes (General) | 5 |
+| Campanhas (General) | 7 |
+| Campos personalizados (General) | 5 |
+| Cargos (General) | 7 |
+| Central de notificacoes (General) | 2 |
+| Chamados (General) | 7 |
+| Chamados (Popular) | 6 |
+| Conexoes (General) | 11 |
+| Contatos (General) | 22 |
+| Contatos (Popular) | 22 |
+| Controle de ausencia (General) | 1 |
+| Creditos SMS (General) | 3 |
+| Departamentos (General) | 6 |
+| Distribuicao de chamados (General) | 6 |
+| Estatisticas de atendimento (General) | 10 |
+| Estatisticas de atendimento (Popular) | 7 |
+| Estatisticas de avaliacoes (General) | 7 |
+| Feriados (General) | 5 |
+| Funil de vendas (General) | 10 |
+| Grupos WhatsApp (General) | 4 |
+| Historico de chamados (General) | 12 |
+| Historico de chamados (Popular) | 9 |
+| Idioma da plataforma (General) | 1 |
+| Integracoes (General) | 2 |
+| Mensagens (General) | 13 |
+| Mensagens (Popular) | 8 |
+| Mensagens interativas (General) | 7 |
+| Meus dados (General) | 1 |
+| Notificacao (General) | 3 |
+| Organizacoes (General) | 5 |
+| Pessoas (General) | 5 |
+| Planos (General) | 2 |
+| Redefinir senha (General) | 1 |
+| Respostas rapidas (General) | 7 |
+| Robos (General) | 6 |
+| Tags (General) | 8 |
+| Templates (General) | 11 |
+| Termos de aceite (General) | 5 |
+| Tokens (General) | 5 |
+| Usuarios (General) | 6 |
+| Versoes (General) | 1 |
+| Webhooks (General) | 5 |
+| WhatsApp (General) | 1 |
+<!-- digisac:recursos:end -->
+
+## 💡 Exemplos práticos
 
 ### Listar contatos
 
@@ -99,7 +168,7 @@ Preencha:
 Resource: **Mensagens (General)**  
 Operation: **Enviar mensagem**
 
-Em **Campos do Body**, preencha:
+Em **Body Fields**, preencha:
 
 - `Text`: `Olá, tudo bem?`
 - `Type`: `chat`
@@ -112,18 +181,13 @@ Em **Campos do Body**, preencha:
 Resource: **Mensagens (General)**  
 Operation: **Enviar imagem**, **Enviar PDF** ou **Enviar áudio**
 
-Use **Campos do Body** para `Text`, `Number` e `Service Id`. No campo `File`, informe um JSON com base64, mimetype e nome:
+Use **Body Fields** para `Text`, `Number` e `Service Id`. No campo `File`, informe somente o objeto do arquivo, não o body inteiro:
 
 ```json
 {
-  "type": "file",
-  "contactId": "CONTACT_ID",
-  "serviceId": "SERVICE_ID",
-  "file": {
-    "base64": "BASE64_DO_ARQUIVO",
-    "mimetype": "application/pdf",
-    "name": "documento.pdf"
-  }
+  "base64": "BASE64_DO_ARQUIVO",
+  "mimetype": "application/pdf",
+  "name": "documento.pdf"
 }
 ```
 
@@ -156,7 +220,7 @@ Body:
 Resource: **Chamados (General)**  
 Operation: **Fechar um chamado com assunto**
 
-Em **Campos do Body**, preencha `Ticket Topic Ids` com:
+Em **Body Fields**, preencha `Ticket Topic Ids` com:
 
 ```json
 ["TICKET_TOPIC_ID"]
@@ -181,116 +245,90 @@ Preencha os campos de query:
 Resource: **Webhooks (General)**  
 Operation: **Criar webhook**
 
-Em **Campos do Body**, preencha `Active`, `Name`, `Url`, `Events` e `Type`. Para `Events`, use array JSON:
+Em **Body Fields**, preencha `Active`, `Name`, `Url`, `Events` e `Type`. Para `Events`, use array JSON:
 
 ```json
 ["message.created", "ticket.closed"]
 ```
 
-## Todas as chamadas da API
+## 🤖 Usar como Tool de Agente de IA
 
-O catálogo completo fica em [docs/api-calls.md](docs/api-calls.md).
+O node `Digisac` é **usável como tool** por nós de **AI Agent** do n8n (Tools Agent). Isso deixa o modelo **executar ações no Digisac sozinho** — por exemplo: *"busque o contato do número 5511999998888 e envie a ele a mensagem de boas-vindas"*. A prática recomendada é criar uma tool por operação liberada para o agente. Isso limita o escopo do modelo e reduz risco de ações erradas.
 
-Resumo por método:
+### Como ligar (2 passos)
 
-```text
-GET: 144 | POST: 93 | PUT: 34 | PATCH: 1 | DELETE: 26
-```
+1. **No servidor n8n**, habilite o uso de community nodes como tools (por segurança, vem **desligado por padrão**). Defina a variável de ambiente:
 
-Resumo por recurso:
+   ```bash
+   N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
+   ```
 
-| Recurso | Chamadas |
-| --- | ---: |
-| Acionamento flag no robo (General) | 1 |
-| Agendamentos (General) | 5 |
-| Agora (General) | 3 |
-| Agora (Popular) | 3 |
-| Assuntos de chamado (General) | 5 |
-| Auditoria de autenticacao (General) | 2 |
-| Autorizacao (General) | 1 |
-| Autorizacao (Popular) | 1 |
-| Avaliacoes (General) | 5 |
-| Campanhas (General) | 7 |
-| Campos personalizados (General) | 5 |
-| Cargos (General) | 7 |
-| Central de notificacoes (General) | 2 |
-| Chamados (General) | 7 |
-| Chamados (Popular) | 6 |
-| Conexoes (General) | 11 |
-| Contatos (General) | 22 |
-| Contatos (Popular) | 22 |
-| Controle de ausencia (General) | 1 |
-| Creditos SMS (General) | 3 |
-| Departamentos (General) | 6 |
-| Distribuicao de chamados (General) | 6 |
-| Estatisticas de atendimento (General) | 10 |
-| Estatisticas de atendimento (Popular) | 7 |
-| Estatisticas de avaliacoes (General) | 7 |
-| Feriados (General) | 5 |
-| Funil de vendas (General) | 10 |
-| Grupos WhatsApp (General) | 4 |
-| Historico de chamados (General) | 12 |
-| Historico de chamados (Popular) | 9 |
-| Idioma da plataforma (General) | 1 |
-| Integracoes (General) | 2 |
-| Mensagens (General) | 13 |
-| Mensagens (Popular) | 8 |
-| Mensagens interativas (General) | 7 |
-| Meus dados (General) | 1 |
-| Notificacao (General) | 3 |
-| Organizacoes (General) | 5 |
-| Pessoas (General) | 5 |
-| Planos (General) | 2 |
-| Redefinir senha (General) | 1 |
-| Respostas rapidas (General) | 7 |
-| Robos (General) | 6 |
-| Tags (General) | 8 |
-| Templates (General) | 11 |
-| Termos de aceite (General) | 5 |
-| Tokens (General) | 5 |
-| Usuarios (General) | 6 |
-| Versoes (General) | 1 |
-| Webhooks (General) | 5 |
-| WhatsApp (General) | 1 |
+   | Instalação | Onde definir |
+   | --- | --- |
+   | **Docker / docker-compose** | Adicione em `environment:` do serviço n8n (ou no `.env`) e recrie o container (`docker compose up -d`). |
+   | **npm / npx** | Exporte antes de subir: `export N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true && n8n start`. |
+   | **n8n Cloud** | Já habilitado nos planos que suportam community nodes. |
+
+   Sem essa variável o node **não aparece** na lista de tools do AI Agent — é a causa nº 1 de "não acho o node como tool".
+
+2. **No workflow**, adicione um node **AI Agent**, conecte um **Chat Model** e, no conector **Tool**, adicione o **Digisac**. Escolha o **Resource** e a **Operation** que o agente pode usar (ex.: *Contatos (General)* → *Listar todos os contatos*). Crie uma tool por operação.
+
+### Deixe o modelo preencher os campos (`$fromAI`)
 
-## Uso como Tool de Agente de IA
+Em cada campo do node em modo tool aparece o botão **"Let the model define this parameter"**, que usa a expressão:
 
-O node pode ser conectado ao **AI Agent** do n8n como uma tool. A prática recomendada é criar uma tool por operação liberada para o agente. Isso limita o escopo do modelo e reduz risco de ações erradas.
+```javascript
+{{ $fromAI('text', 'Texto exato que será enviado ao contato', 'string') }}
+```
+
+- Assinatura: `$fromAI(key, description?, type?, defaultValue?)` — `key` de 1–64 caracteres (`[a-zA-Z0-9_-]`); `type` = `string` | `number` | `boolean` | `json`.
+- Você pode **misturar**: fixar alguns campos (ex.: sempre `Origin` = `bot`) e deixar o modelo preencher outros (texto, contato, período).
+- **Na versão 2 do node**, os campos de ID são Resource Locator. Para o modelo preencher um ID, mude o campo para o modo **By ID** e ponha a expressão `$fromAI` no valor. A lista **From List** serve para a pessoa que monta o workflow, não para o agente.
+- As **descrições de cada operação e campo** foram escritas para o LLM entender o que cada uma faz e como preencher; quanto mais específico o System Message do agente, melhor o resultado.
 
 ### Prompt recomendado para o System Message
 
 ```text
 Você pode usar as tools Digisac somente quando o usuário pedir para consultar, criar ou alterar dados na Digisac.
-Nunca invente IDs. Se faltar contactId, ticketId, departmentId, serviceId, userId, messageId, tagId, campaignId ou templateId, primeiro use uma operação de listagem ou busca.
+Nunca invente IDs. Qualquer campo terminado em Id ou Ids deve vir de busca/listagem anterior, entrada confirmada do usuário ou valor sentinela documentado como all.
+Não copie placeholders da documentação, como {{contactId}}, {{serviceId}} ou {{all/open/close}}. Substitua por valor real ou escolha uma opção válida.
 Para operações POST, PUT e PATCH, envie um body JSON mínimo, somente com os campos necessários.
-Quando a tool expuser Campos do Body, preencha os campos dedicados em vez de gerar um JSON manual.
+Quando a tool expuser Body Fields, preencha os campos dedicados em vez de gerar um JSON manual.
 Use Body JSON Avançado ou Query Avançada JSON apenas quando não existir campo dedicado suficiente para a chamada.
 Para filtros de data/hora, use ISO-8601 quando o endpoint esperar timestamp.
 Para exportações CSV, TXT ou PDF, use Response Format = Text se a resposta não for JSON.
 Antes de criar, editar, excluir, arquivar, bloquear, fechar chamado ou enviar mensagem, confirme que a intenção do usuário está clara.
 ```
 
-### Exemplos de `$fromAI()`
+### Exemplos de `$fromAI()` com os campos do node
 
-Contato existente:
+**Enviar mensagem** (*Mensagens (General)* → *Enviar mensagem*), em **Body Fields**:
 
-```javascript
-{{ $fromAI('contactId', 'ID existente de contato Digisac. Deve vir de uma busca/listagem anterior, nunca inventado.', 'string') }}
-```
+- `Text`: o modelo escreve o texto.
 
-Texto de mensagem:
+  ```javascript
+  {{ $fromAI('text', 'Texto exato que será enviado ao contato no WhatsApp/Digisac.', 'string') }}
+  ```
 
-```javascript
-{{ $fromAI('messageText', 'Texto exato que será enviado ao contato no WhatsApp/Digisac.', 'string') }}
-```
+- `Contact Id` (modo **By ID**): o ID vem de uma busca anterior, nunca inventado.
 
-Filtro de período:
+  ```javascript
+  {{ $fromAI('contactId', 'ID existente de contato Digisac. Deve vir de uma busca/listagem anterior.', 'string') }}
+  ```
 
-```javascript
-{{ $fromAI('startPeriod', 'Início do período em ISO-8601, por exemplo 2026-07-01T00:00:00.000Z.', 'string') }}
-```
+- `Type` = `chat` e `Origin` = `bot`: fixe estes dois no próprio campo, sem `$fromAI`.
+
+**Buscar estatísticas** (*Estatísticas de atendimento (General)*), nos campos de query:
+
+- `Start Period` e `End Period`: o seletor de data da versão 2 aceita a expressão.
 
-Campo de body estruturado:
+  ```javascript
+  {{ $fromAI('startPeriod', 'Início do período em ISO-8601 com fuso, por exemplo 2026-07-01T00:00:00.000Z.', 'string') }}
+  ```
+
+- `Department Id` e `User Id`: deixe `all` fixo quando o agente não precisa filtrar.
+
+**Campo de body estruturado** (envio de arquivo, `File` em *Body Fields*):
 
 ```javascript
 {{ $fromAI('file', 'Objeto JSON do arquivo com base64, mimetype e name quando a operação Digisac enviar mídia.', 'json') }}
@@ -306,90 +344,99 @@ Campo de body estruturado:
 - Em mensagens enviadas ao cliente, gere o texto em etapa anterior e passe o texto final para a tool.
 - Use campos dedicados sempre que existirem. Para bodies grandes ou arrays de múltiplos itens, use JSON explícito e valide campos obrigatórios no workflow antes da chamada.
 
-## Desenvolvimento
+### Referências
+
+- [Tools Agent — n8n Docs](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/tools-agent)
+- [Let AI specify tool parameters (`$fromAI`) — n8n Docs](https://docs.n8n.io/advanced-ai/examples/using-the-fromai-function/)
+- [Variáveis de ambiente de nodes — n8n Docs](https://docs.n8n.io/hosting/configuration/environment-variables/nodes/)
+
+## 🔀 Versão 1 ou 2 do node
+
+| | **Versão 1** | **Versão 2 (padrão em node novo)** |
+| --- | --- | --- |
+| IDs | Texto digitado | Lista pesquisável (8 tipos) ou **By ID** (os demais) |
+| Datas | Texto | Seletor de data, enviada em ISO UTC |
+| Valores fixos | Texto | Lista de opções |
+| Workflows salvos | Continuam iguais | Não são alterados |
+
+Se um workflow salvo usa a versão 1, ele continua enviando exatamente a mesma requisição. Para ganhar os campos guiados, adicione um node novo (versão 2) e escolha o valor de novo.
+
+## 🛠️ Desenvolvimento
 
 ```bash
+# Instalar dependências
 npm install
-npm run generate:endpoints
-npm run generate:docs
-npm run lint
+
+# Compilar (n8n-node build: tsc + cópia de ícones)
 npm run build
-npm run dev
-```
 
-Estrutura:
+# Testes (node --test sobre o dist)
+npm test
 
-```text
-n8n-nodes-digisac/
-├── credentials/
-│   └── DigisacApi.credentials.ts
-├── nodes/
-│   └── Digisac/
-│       ├── Digisac.node.ts
-│       ├── actions/
-│       ├── generated/
-│       ├── helpers/
-│       └── transport/
-├── scripts/
-│   ├── generate-docs.mjs
-│   └── generate-endpoints.mjs
-└── docs/
-    └── api-calls.md
+# Lint oficial do n8n (n8n-node lint)
+npm run lint
+npm run lint:fix
 ```
 
-## Como o catálogo é gerado
-
-O script `scripts/generate-endpoints.mjs` baixa a coleção pública:
+Estrutura resumida:
 
 ```text
-https://documenter.getpostman.com/view/53282970/2sBXihpXmF
+n8n-nodes-digisac/
+├── credentials/        # DigisacApi.credentials.ts
+├── nodes/Digisac/
+│   ├── actions/        # monta propriedades e executa cada chamada
+│   ├── generated/      # catálogo gerado da coleção Postman
+│   ├── helpers/        # IDs guiados, datas e opções (versão 2)
+│   ├── methods/        # listSearch das listas pesquisáveis
+│   └── transport/      # requisição HTTP com timeout
+├── scripts/            # geradores do catálogo e dos documentos
+├── docs/               # api-calls.md (gerado)
+└── test/               # node --test sobre o dist
 ```
 
-E gera:
+Os geradores são manuais e **não** rodam no build (o primeiro baixa a coleção da rede):
 
-```text
-nodes/Digisac/generated/endpoints.ts
+```bash
+npm run generate:endpoints   # baixa a coleção Postman e regrava o catálogo
+npm run generate:docs        # regrava docs/api-calls.md e a tabela de recursos deste README
 ```
 
-O script `scripts/generate-docs.mjs` lê esse catálogo e gera:
+## ✅ Compatibilidade
 
-```text
-README.md
-docs/api-calls.md
-```
+- Requer n8n com `n8nNodesApiVersion` 1 e uma conta Digisac com token de acesso pessoal.
+- A versão 2 do node é a padrão em node novo; a versão 1 continua disponível para workflows salvos.
 
-## Publicação no npm
+## 📚 Recursos
 
-O projeto publica pelo mesmo padrão do node Clinicorp: GitHub Actions + npm provenance.
+- [Documentação Postman da Digisac](https://documenter.getpostman.com/view/53282970/2sBXihpXmF)
+- [Documentação de community nodes do n8n](https://docs.n8n.io/integrations/community-nodes/)
+- [n8n: `$fromAI()`](https://docs.n8n.io/build/integrate-ai/ai-examples/use-ai-for-parameters/)
 
-Para publicar nova versão:
+## 🚀 Publicação
 
-```bash
-npm version patch
-git push origin main --tags
-```
+A tag `vX.Y.Z` dispara o workflow `publish.yml`, que envia a versão com `npm stage publish` e provenance. A versão **fica em espera**: ela só vai ao ar depois que o dono a aprova, com 2FA, na aba **Staged Packages** do npmjs.com. Sem a aprovação, nada muda no registro.
 
-O workflow executa:
+## 📈 Versões
 
-```bash
-npm ci --ignore-scripts
-npm run build
-npm publish --provenance --access public
-```
+- **1.1.0** — **IDs, datas e valores guiados.** Em node novo (versão 2 do node), contato, conexão, departamento, usuário, tag, cargo, robô e assunto aparecem em lista pesquisável; datas têm seletor; valores fixos viram opções. Workflows salvos continuam na versão 1. Migração para o `@n8n/node-cli` 0.55.5, lint oficial sem erros, testes, CI e timeout de 30 s. Veja o `CHANGELOG.md`.
+- **1.0.3** — Descrições de AI Tool reforçadas: regra para campos `Id/Ids`, alertas para placeholders, orientação Popular vs General e avisos por tipo de campo.
+- **1.0.2** — Interface simplificada: query e body com campos dedicados gerados da documentação. JSON fica em opções avançadas.
+- **1.0.1** — Documentação em PT-BR, exemplos, instruções de AI Tool e catálogo em `docs/api-calls.md`.
+- **1.0.0** — Primeira versão publicada: node único `Digisac`, credencial Bearer, 298 chamadas, suporte a AI Agent e publicação npm via GitHub Actions.
 
-## Versões
+## 🆘 Suporte
 
-- **1.0.2** — Interface simplificada: query e body agora usam campos dedicados gerados da documentação. JSON fica escondido em opções avançadas ou aparece apenas nas chamadas em que não há forma segura de gerar campos. Ícone atualizado a partir de `icon.webp`.
-- **1.0.1** — Documentação reescrita em PT-BR, com exemplos práticos, instruções de AI Tool e catálogo completo de chamadas em `docs/api-calls.md`.
-- **1.0.0** — Primeira versão publicada. Node único `Digisac`, credencial Bearer, catálogo com 298 chamadas da documentação Postman, suporte a AI Agent e publicação npm via GitHub Actions.
+Se algo não funcionar:
 
-## Referências
+1. Confirme a **Base URL** e o **token** da credencial (o teste da credencial chama `GET /api/v1/me`).
+2. Verifique se a versão do n8n é compatível.
+3. Consulte os logs do n8n para o erro detalhado.
+4. Abra uma [issue no GitHub](https://github.com/PedroHSGuimaraes/n8n-nodes-digisac/issues).
 
-- [Documentação Postman da Digisac](https://documenter.getpostman.com/view/53282970/2sBXihpXmF)
-- [n8n: building community nodes](https://docs.n8n.io/integrations/community-nodes/building-community-nodes/)
-- [n8n: programmatic node tutorial](https://docs.n8n.io/connect/create-nodes/build-your-node/tutorial-build-a-programmatic-style-node/)
-- [n8n: `$fromAI()`](https://docs.n8n.io/build/integrate-ai/ai-examples/use-ai-for-parameters/)
+## ☕ Apoie o projeto
+
+Este node é mantido de forma independente. Se ele ajuda suas automações, você pode apoiar o desenvolvimento, a manutenção e as novas integrações pelo [Buy Me a Coffee](https://buymeacoffee.com/qTny0AzFXS).
 
-## Licença
+## 📄 Licença
 
 [MIT](LICENSE.md)

package/dist/nodes/Digisac/Digisac.node.d.ts

@@ -1,5 +1,17 @@
 import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
 export declare class Digisac implements INodeType {
     description: INodeTypeDescription;
+    methods: {
+        listSearch: {
+            searchContacts: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchServices: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchDepartments: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchUsers: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchTags: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchRoles: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchBots: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchTicketTopics: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string, paginationToken?: unknown) => Promise<import("n8n-workflow").INodeListSearchResult>;
+        };
+    };
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
 }

package/dist/nodes/Digisac/Digisac.node.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Digisac = void 0;
 const n8n_workflow_1 = require("n8n-workflow");
 const actions_1 = require("./actions");
+const resourceLocator_1 = require("./helpers/resourceLocator");
+const listSearch_1 = require("./methods/listSearch");
+const defaultResource = actions_1.resourceOptions[0]?.value?.toString() ?? '';
 class Digisac {
     constructor() {
         this.description = {
@@ -10,7 +13,8 @@ class Digisac {
             name: 'digisac',
             icon: { light: 'file:digisac.png', dark: 'file:digisac.dark.png' },
             group: ['transform'],
-            version: 1,
+            version: [1, 2],
+            defaultVersion: 2,
             subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
             description: 'Use every documented Digisac API request from the public Postman documentation. Choose a resource folder and operation, fill required path parameters and use the generated query/body fields first. Advanced JSON fields are available only when an operation needs a custom payload or unsupported filter. Built for AI Agents: operation descriptions include method, path, source folder, required path variables, query guidance, body fields and explicit reminders to use IDs returned by Digisac instead of inventing values.',
             defaults: {
@@ -18,7 +22,11 @@ class Digisac {
             },
             inputs: [n8n_workflow_1.NodeConnectionTypes.Main],
             outputs: [n8n_workflow_1.NodeConnectionTypes.Main],
-            usableAsTool: true,
+            usableAsTool: {
+                replacements: {
+                    description: 'Ferramenta para executar chamadas documentadas da API Digisac dentro do n8n. Use somente para tarefas de Digisac, como consultar, criar ou alterar contatos, chamados, mensagens, campanhas, conexoes, departamentos, usuarios, tags, templates, webhooks, relatorios e estatisticas. Primeiro escolha Resource e Operation; a Operation informa metodo HTTP, endpoint, origem na documentacao, parametros obrigatorios, query e body. Nunca invente IDs: qualquer campo terminado em Id ou Ids deve vir de busca/listagem anterior, entrada confirmada do usuario ou valor sentinela documentado como all. Preencha campos dedicados de path, query e Body Fields; deixe campos vazios quando nao souber. Nao copie placeholders da documentacao como {{contactId}} ou {{all/open/close}}; substitua por valor real ou escolha uma opcao valida. Use Query Avancada JSON ou Body JSON Avancado apenas quando nao existir campo dedicado suficiente. Antes de enviar mensagem, excluir, arquivar, bloquear, fechar chamado, transferir chamado ou alterar dados, confirme que a intencao do usuario esta explicita.',
+                },
+            },
             credentials: [
                 {
                     name: 'digisacApi',
@@ -32,12 +40,13 @@ class Digisac {
                     type: 'options',
                     noDataExpression: true,
                     options: actions_1.resourceOptions,
-                    default: actions_1.resourceOptions[0]?.value ?? '',
-                    description: 'Digisac API area, grouped from the Postman documentation. Pick the folder that matches the task: contacts, tickets, messages, campaigns, services, dashboards, webhooks, and more.',
+                    default: defaultResource,
+                    description: 'Area da API Digisac agrupada pela documentacao Postman. Resources Popular sao atalhos para operacoes frequentes; resources General contem o catalogo mais completo. Se a mesma chamada existir em Popular e General, prefira Popular para fluxos comuns e General quando precisar de uma chamada que nao existe no Popular.',
                 },
-                ...actions_1.resourceProperties,
+                ...(0, resourceLocator_1.withGuidedIds)(actions_1.resourceProperties),
             ],
         };
+        this.methods = { listSearch: listSearch_1.listSearch };
     }
     async execute() {
         const items = this.getInputData();