n8n-nodes-verdesk

Node comunitário do n8n para integrar com a API do Verdesk (CRM de atendimento via
WhatsApp, parte do ecossistema Prontuário Verde).

Cobre os recursos:

• Contact — buscar, criar, adicionar/remover tags, telefone e email
• Opportunity — criar, listar por contato, mover entre etapas do funil, finalizar
• Message — enviar mensagem WhatsApp, enviar template, listar templates
• Funnel — listar funis e etapas

Base da API: https://api.prontuarioverde.com.br/ords/ovyva/vd/v1
(documentação oficial: https://prontuarioverde.com.br/desenvolvedores/verdesk/)

1. Antes de tudo: pegar as credenciais da API

Você ainda não tem client_id / client_secret. Para solicitar:

1. Confirme com o cliente que o plano do Prontuário Verde contempla uso de API
   (é um add-on separado do plano normal).
2. Acesse o painel do Prontuário Verde → menu Desenvolvedores / Integrações / API.
3. Gere as credenciais de integração (client_id e client_secret) para o Verdesk.
4. Guarde os dois valores com segurança — serão usados na credencial do n8n.

Sem isso não dá pra testar nada; o restante do pacote já está pronto, só falta
plugar as credenciais.

2. Instalar dependências e compilar

cd /Users/amatobackstage/n8n-nodes-verdesk
npm install
npm run build

Isso gera a pasta dist/ com o JS compilado (é o que o n8n carrega, não o .ts).

3. Carregar o node no n8n self-hosted (sem publicar no npm)

Como o n8n é self-hosted, dá pra testar localmente sem precisar publicar o pacote:

# dentro da pasta do node
npm link

# na pasta de dados do n8n (cria se não existir)
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm init -y   # só na primeira vez, se não houver package.json aqui
npm link n8n-nodes-verdesk

Reinicie o n8n (n8n start, ou reinicie o container/serviço). O node "Verdesk"
deve aparecer na busca de nodes.

Se o n8n rodar em Docker, monte ~/.n8n como volume (já costuma ser o padrão) e
rode o npm link de dentro do container, ou copie a pasta dist +
package.json do node para ~/.n8n/nodes/node_modules/n8n-nodes-verdesk/ e
rode npm install lá dentro do container.

Quando quiser distribuir de forma definitiva (outros clientes, outros
servidores), publique o pacote no npm com npm publish e instale via
Settings → Community Nodes direto na UI do n8n — sem precisar mexer em
arquivos manualmente.

4. Configurar a credencial no n8n

1. Crie uma credencial do tipo Verdesk OAuth2 API.
2. Preencha Client ID e Client Secret com o que veio do painel do
   Prontuário Verde.
3. Os demais campos (Grant Type, Access Token URL, Authentication) já vêm
   pré-preenchidos e ocultos — não precisa mexer.
4. Salve e use "Connect"/teste de conexão para confirmar que o token é obtido.

5. Estrutura do projeto

credentials/
  VerdeskOAuth2Api.credentials.ts   # credencial OAuth2 (client_credentials)
nodes/Verdesk/
  Verdesk.node.ts                  # lógica do node (resources/operations)
  GenericFunctions.ts               # helper de request autenticado
  verdesk.svg                       # ícone do node

6. Operações ainda não cobertas

A API também expõe GET /canais (canais) e GET /usuarios (usuários), e um
endpoint POST /oportunidades/receber-mensagem que parece ser usado pelo
próprio Verdesk para registrar uma mensagem recebida (não está claro se é
para uso externo). Não há webhook documentado para dispará-lo automaticamente
quando chega mensagem nova — se você precisar de um trigger em tempo real
("quando chegar mensagem no Verdesk, rodar workflow"), isso precisa ser
confirmado com o suporte da Verdesk (polling programado ou webhook a ser
liberado por eles).