Nó Selectwin para n8n

O nó oficial da Selectwin para o n8n: opere a API de pagamentos da Selectwin (Pix, cartão, boleto, clientes, produtos, links de pagamento, assinaturas) e reaja aos webhooks, sem escrever código.

#O que é

• Nó Selectwin: cobre o dia a dia da API. Crie cobranças, cuide de clientes, produtos e links de pagamento, e consulte saldo, recebíveis e saques.
• Nó Selectwin Trigger: registra um webhook na API para os eventos que você escolher, confere a assinatura de cada entrega (em tempo constante e à prova de reenvio) e entrega o evento inteiro ao seu workflow.
• Sem dependências em tempo de execução. A autenticação é a sua SelectKey, e todo POST leva um X-Idempotency-Key automático.

#Instalação

#Pela interface do n8n (nós da comunidade)

1. No n8n, vá em Settings → Community Nodes → Install.
2. Digite n8n-nodes-selectwin e confirme.

#Manual (n8n próprio)

cd ~/.n8n/nodes   # a pasta de nós da comunidade do seu n8n
npm install n8n-nodes-selectwin

Depois, reinicie o n8n.

#Credencial

Crie uma credencial Selectwin API:

O ambiente é decidido pelo prefixo da chave, não pelo endereço. O teste da credencial chama GET /v1/balance. As requisições se autenticam com o cabeçalho selectkey.

#O nó Selectwin

As listagens paginam com Limit e Offset; a API responde no envelope { data[], hasMore, total, page }.

#O Selectwin Trigger

Escolha um ou mais eventos do catálogo da API (transaction.approved, transaction.refunded, subscription.canceled, checkout.session.completed, …). Ao ativar, o nó registra o webhook com POST /v1/webhooks e guarda o segredo devolvido; ao desativar, apaga o webhook.

Cada entrega é conferida antes de o seu workflow rodar:

• x-selectwin-signature-v1: t=<unix>,v1=<hmac-sha256-hex("<t>.<body>", secret)> — o preferido, à prova de reenvio (tolerância padrão de 300 s, ajustável em Options);
• x-selectwin-signature: sha256=<hmac-sha256-hex(body, secret)> — o formato antigo, aceito como alternativa.

A conferência é feita sobre os bytes recebidos, com comparação em tempo constante. Entrega inválida ou sem assinatura é recusada com 401 e nunca chega ao seu workflow.

#Chamada livre à API

A credencial Selectwin API também vale como tipo de credencial predefinido no nó HTTP Request do próprio n8n: o caminho para chegar a qualquer endpoint da API que o nó ainda não cobre.

#Desenvolvimento

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest (conferência da assinatura do webhook)
npm run build       # tsc + copia os ícones dos nós para dist/