Gusta Coins para n8n

Node para consultar e administrar preços e produtos da Gusta Coins em workflows do n8n. O pacote é público no npm para permitir sua instalação, mas é destinado ao uso interno e não é submetido ao catálogo de nodes verificados do n8n.

Recursos

• Preços de Coins: consultar e atualizar os preços-base de console e PC.
• Contas: cadastrar, consultar, listar, atualizar e mover produtos para a lixeira.
• WL/DR: cadastrar, consultar, listar, atualizar e mover produtos para a lixeira.
• DME: cadastrar, consultar, listar, atualizar e mover produtos para a lixeira.
• Formulários em português com os mesmos termos usados no catálogo da loja.
• Entrada por campos ou JSON nas operações de escrita.
• Paginação automática e resposta simplificada ou completa.
• Upload de imagens JPEG, PNG e WebP a partir dos dados binários de entrada.

O node implementa as 17 operações documentadas pelo OpenAPI 3.1 v4.0.0 do projeto gusta-coins-store. O filtro interno available não foi incluído porque ainda não aparece no documento OpenAPI.

Requisitos

• Node.js 22 ou superior.
• Uma instalação self-hosted do n8n compatível com community/custom nodes.
• O valor de API_TOKEN configurado na Gusta Coins.

Desenvolvimento local

npm install
npm run dev

O comando de desenvolvimento compila o node, inicia uma instância local do n8n e observa alterações.

Validações disponíveis:

npm run lint
npm run build
npm test

Instalação

O pacote é publicado no npm como @wocody/n8n-nodes-gusta-coins e pode ser instalado sem autenticação:

mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install @wocody/[email protected]

Reinicie o n8n depois de instalar ou atualizar o node. Fixe sempre uma versão explícita em produção.

As instruções completas para publicação no npm e instalação no EasyPanel estão em docs/PRODUCAO.md.

Credencial

Crie uma credencial Gusta Coins API com:

• URL da API: https://gustacoins.com.br por padrão. Também pode apontar para staging ou http://localhost:3000.
• Token da API: o valor secreto de API_TOKEN da loja.

O teste da credencial chama GET /api/prices. O token é enviado como Authorization: Bearer <token>.

Operações de escrita

Em Modo de entrada, escolha:

• Campos: usa campos, selects e coleções visuais. Campos opcionais só são enviados quando adicionados.
• JSON: aceita um objeto ou uma expressão que resulte em objeto. Use este modo para valores null, listas vazias explícitas ou payloads inteiramente dinâmicos.

Valores monetários de produtos devem ser strings com duas casas, por exemplo "403.00". Datas são enviadas em ISO 8601. O modo do produto é definido pelo recurso e não deve aparecer no corpo.

Produtos são criados como rascunho por padrão. A API é a fonte final das regras de publicação e devolve os campos incompletos em erros de validação.

Listagens e respostas

• Retornar tudo percorre as páginas da API com até 100 produtos por requisição.
• Limite restringe o total de produtos retornados quando Retornar tudo está desligado.
• Simplificar resposta, ativado por padrão, remove { data } e cria um item n8n para cada produto listado.
• Com a simplificação desligada, operações individuais preservam o envelope e listagens retornam um item por página com data e pagination.

O node preserva o vínculo entre cada item de entrada e os itens gerados. A opção nativa Continuar em caso de falha retorna o erro ligado ao item original.

Upload de imagens

Ative Enviar imagens em Cadastrar ou Atualizar. Para cada imagem, informe:

• Campo de dados de entrada: nome do campo binário, como data, cover ou reward.
• Papel da imagem: as opções mudam conforme Contas, WL/DR ou DME.
• Índice do jogador ou recompensa: obrigatório quando a imagem pertence a um item de uma lista; o primeiro índice é zero.
• Posição na galeria e Texto alternativo.

O node gera fileIndex, payload e manifest, e envia cada arquivo repetindo o campo multipart files.

Limites atuais da API:

• JPEG, PNG ou WebP.
• Até 20 imagens.
• Até 10 MB por imagem.
• Até 50 MB no conjunto de imagens.

Smoke test somente leitura

Depois que os endpoints do OpenAPI v4 estiverem publicados, é possível validar preços e as três listagens sem alterar dados:

GUSTA_COINS_API_URL=https://gustacoins.com.br \
GUSTA_COINS_API_TOKEN=seu-token \
npm run test:smoke

O script nunca executa criação, atualização ou exclusão.