n8n-nodes-digisac 1.0.3 → 1.2.0

package/README.md

@@ -1,24 +1,32 @@
 # 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` com descrição específica de ferramenta e textos pensados para LLMs entenderem método, caminho, efeito da operação, parâmetros, regra de 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** — 315 chamadas em 52 recursos, geradas da coleção pública Postman, incluindo o **Kanban** (quadros, colunas e cards).
+- **Kanban com lista pesquisável** — na versão 2, quadro e coluna aparecem como lista da sua conta, e o card aparece depois de você escolher a coluna. Excluir quadro, coluna ou card só roda com **Confirm Delete** ligado.
+- **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,54 +38,129 @@ 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.
 
-Resources marcados como **Popular** são atalhos herdados da coleção Postman para operações frequentes. Resources **General** contêm o catálogo mais completo. Se a mesma chamada existir nos dois, use **Popular** para fluxos comuns e **General** quando precisar de uma operação que não aparece em Popular.
+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}}`.
 
-Regra para AI Tools e automações: qualquer campo terminado em `Id` ou `Ids` deve vir de busca/listagem anterior, entrada confirmada do usuário ou valor sentinela documentado, como `all`. Nunca copie placeholders como `{{contactId}}`, `{{serviceId}}` ou `{{all/open/close}}`.
+| Campo | Uso |
+| --- | --- |
+| **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. |
 
-## Campos principais do node
+### Kanban (quadros, colunas e cards)
 
-| Campo | Uso |
+O resource **Kanban (General)** tem 17 operações, três por tipo mais as de ordem:
+
+| Tipo | Operações |
 | --- | --- |
-| **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. Chaves iguais substituem campos gerados; 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. |
+| Quadro | **Listar quadros**, **Buscar quadro**, **Criar quadro**, **Editar quadro**, **Excluir quadro** |
+| Coluna | **Listar colunas**, **Buscar coluna**, **Criar coluna**, **Editar coluna**, **Excluir coluna**, **Reordenar coluna** |
+| Card | **Listar cards**, **Buscar card**, **Criar card**, **Editar card**, **Excluir card**, **Reordenar card** |
+
+- **Escolha em cascata (versão 2).** Em operações que pedem uma coluna, o campo **Filter by Board** estreita a lista de colunas a um quadro. Em operações que pedem um card, o campo **Filter by Column** mostra os cards daquela coluna. Esses dois campos só ajudam a escolher: o node não os envia ao Digisac. Sem a coluna escolhida, a lista de cards fica vazia; cole o ID no modo **By ID** se já o tem.
+- **Excluir exige confirmação.** **Excluir quadro**, **Excluir coluna** e **Excluir card** têm o campo **Confirm Delete**, desligado por padrão. Sem ele ligado, o node para antes de chamar a API.
+- **Body Fields começa vazio.** Em criar e editar, adicione só os campos que quer enviar. Assim, editar um card não sobrescreve a posição, e editar um quadro não troca os departamentos.
+- **Duas suposições sem chamada real.** A coleção do Digisac traz **Editar coluna** e **Editar card** como `/v1/...`, sem `/api`. O node usa `/api/v1/kanban-columns/...` e `/api/v1/kanban-cards/...`, como as outras 15 rotas. Se essas duas operações responderem `404`, o caminho da coleção é o certo; abra uma issue. Também por suposição, `Position` (editar card) vai como número, e a coleção mostra `"1"` entre aspas.
+- **Versão 1.** Quem usa a versão 1 vê as mesmas 17 operações com campos de texto, sem a lista pesquisável.
+
+### Todas as chamadas da API
+
+O catálogo completo fica em [docs/api-calls.md](docs/api-calls.md). Resumo por método:
+
+```text
+GET: 150 | POST: 96 | PUT: 37 | PATCH: 3 | DELETE: 29
+```
+
+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 |
+| Kanban (General) | 17 |
+| 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
+## 💡 Exemplos práticos
 
 ### Listar contatos
 
@@ -103,7 +186,7 @@ Preencha:
 Resource: **Mensagens (General)**  
 Operation: **Enviar mensagem**
 
-Em **Campos do Body**, preencha:
+Em **Body Fields**, preencha:
 
 - `Text`: `Olá, tudo bem?`
 - `Type`: `chat`
@@ -116,7 +199,7 @@ 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 somente o objeto do arquivo, não o body inteiro:
+Use **Body Fields** para `Text`, `Number` e `Service Id`. No campo `File`, informe somente o objeto do arquivo, não o body inteiro:
 
 ```json
 {
@@ -155,7 +238,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"]
@@ -175,86 +258,68 @@ Preencha os campos de query:
 - `Period Type`: `open` ou `close`
 - `Status`: `all`, `open` ou `close`
 
+### Mover card entre colunas
+
+Resource: **Kanban (General)**  
+Operation: **Editar card**
+
+Escolha o card (versão 2: use **Filter by Column** para achar o card na lista, ou cole o ID no modo **By ID**). Em **Body Fields**, adicione:
+
+- `Column Id`: a coluna de destino, escolhida na lista.
+- `Position`: opcional, o número da posição na coluna.
+
+### Excluir card com confirmação
+
+Resource: **Kanban (General)**  
+Operation: **Excluir card**
+
+Escolha o card e ligue **Confirm Delete**. Sem isso o node recusa a chamada com a mensagem `Turn on 'Confirm Delete' to delete this kanban card`.
+
 ### Criar webhook
 
 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".
 
-## Uso como Tool de Agente de IA
+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.
 
-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.
+### Deixe o modelo preencher os campos (`$fromAI`)
+
+Em cada campo do node em modo tool aparece o botão **"Let the model define this parameter"**, que usa a expressão:
+
+```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
 
@@ -263,34 +328,42 @@ Você pode usar as tools Digisac somente quando o usuário pedir para consultar,
 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`.
 
-Campo de body estruturado:
+**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.
+
+  ```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') }}
@@ -303,94 +376,104 @@ Campo de body estruturado:
 - Nunca deixe o modelo inventar IDs.
 - Use credenciais dedicadas por ambiente/cliente.
 - Para operações destrutivas (`DELETE`, arquivar, bloquear, fechar chamado), coloque etapa humana de confirmação quando o fluxo for sensível.
+- **Kanban como tool.** As 17 operações do Kanban funcionam como tool. Para **Excluir quadro**, **Excluir coluna** e **Excluir card**, deixe **Confirm Delete** desligado na tool e ligue só num fluxo que você revisou: o agente não consegue apagar sem esse campo. O agente deve achar o quadro com **Listar quadros**, a coluna com **Listar colunas** e o card com **Listar cards** antes de mover ou excluir.
 - 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, mais quadro, coluna e card do Kanban) 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.2.0** — **Kanban.** 17 operações novas de quadros, colunas e cards, com lista pesquisável na versão 2 e **Confirm Delete** nas três de excluir. O catálogo passa a guardar o ID de cada operação: nenhum workflow salvo muda de operação. Veja o `CHANGELOG.md`.
+- **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.3** — Descrições de AI Tool reforçadas: regra genérica para campos `Id/Ids`, alertas para placeholders, orientação Popular vs General, avisos por tipo de campo de body/query e exemplo de arquivo corrigido.
-- **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,20 @@
 import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
 export declare class Digisac implements INodeType {
     description: INodeTypeDescription;
+    methods: {
+        listSearch: {
+            searchKanbanBoards: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchKanbanColumns: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            searchKanbanCards: (this: import("n8n-workflow").ILoadOptionsFunctions, filter?: string) => Promise<import("n8n-workflow").INodeListSearchResult>;
+            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[][]>;
 }