asaas-billing

Asaas (API v3) nodes for n8n: customers, payments (Pix, boleto, card), card tokenization, subscriptions (recurring billing), webhooks and a webhook trigger

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.2
Author: Parenzo

Available Nodes

Documentation generating…

Asaas icon
Asaas
Clientes, cobranças (Pix, boleto, cartão), tokenização de cartão, assinaturas e webhooks do Asaas
Asaas Trigger icon
Asaas Trigger
Inicia o workflow com eventos de cobrança e assinatura do Asaas

Documentation

n8n-nodes-asaas-billing

O nome n8n-nodes-asaas já existe no npm (de outro autor); este pacote é publicado como n8n-nodes-asaas-billing.

Community nodes do n8n para a API v3 do Asaas: clientes, cobranças (Pix, boleto e cartão), tokenização de cartão, assinaturas (recorrência), webhooks e um trigger de eventos.

Criado para o Parenzo (cobrança dos planos), mas genérico: serve para qualquer conta Asaas.

Funcionalidades

Fonte da verdade do que o pacote faz. Toda operação nova, alterada ou removida atualiza esta lista no mesmo commit.

Credencial Asaas API

Campo Uso
Environment Sandbox → https://api-sandbox.asaas.com/v3 · Production → https://api.asaas.com/v3
API Key $aact_hmlg_... (sandbox) ou $aact_prod_... (produção), enviada no header access_token
User-Agent Obrigatório para contas criadas a partir de 13/06/2024 (padrão n8n-nodes-asaas)

O botão Test da credencial lista 1 cliente para validar a chave.

Node Asaas

Recurso Operações Endpoint
Customer Create, Get, Get Many (filtros: nome, e-mail, CPF/CNPJ, externalReference, grupo), Update, Delete, Restore /customers
Payment Create (Pix, boleto, cartão, parcelado, pré-autorização, desconto/multa/juros/split), Get, Get Many (filtros: cliente, assinatura, parcelamento, forma, status, externalReference, datas de vencimento e pagamento), Update, Delete, Restore, Refund (total ou parcial), Get Pix QR Code, Get Status, Get Boleto Line, Pay With Credit Card, Receive in Cash /payments
Credit Card Tokenize: devolve creditCardToken + bandeira + final para cobranças e assinaturas sem guardar número/CVV /creditCard/tokenizeCreditCard
Subscription Create (ciclos semanal a anual, token do cartão, data final, máximo de cobranças, desconto/multa/juros/split), Get, Get Many, Update (inclusive status e "atualizar cobranças pendentes"), Delete, Get Payments, Update Credit Card /subscriptions
Webhook Create, Get, Get Many, Update, Delete /webhooks
  • Get Many pagina sozinho (offset/limit de 100) com Return All ou Limit.
  • Datas aceitam AAAA-MM-DD ou ISO completo (o node corta para AAAA-MM-DD).
  • Cobrança/assinatura no cartão sem Remote IP é recusada antes de chamar o Asaas (o Asaas exige o IP do comprador).
  • Erros do Asaas ({ errors: [{ code, description }] }) viram a mensagem do erro do node, com o HTTP status. O corpo da requisição nunca é anexado ao erro.
  • Pode ser usado como tool de agentes de IA (usableAsTool).

Node Asaas Trigger

  • Recebe os eventos escolhidos (PAYMENT_*, SUBSCRIPTION_*).
  • Registra o webhook no Asaas ao ativar o workflow e remove ao desativar (pode desligar e configurar manualmente no painel).
  • Exige Auth Token (32 a 255 caracteres): o Asaas envia no header asaas-access-token; chamada sem o token certo recebe 401 (comparação em tempo constante).
  • Eventos não escolhidos recebem 200 e são ignorados (o Asaas não pausa a fila).

Recorrência com cartão (fluxo típico)

  1. Customer › Create (com externalReference = id do seu sistema).
  2. Credit Card › Tokenize → guarde creditCardToken, creditCardBrand, creditCardNumber (final).
  3. Escolha:
    • Subscription › Create com billingType = CREDIT_CARD, cycle e o token: o Asaas gera e cobra cada ciclo sozinho; ou
    • Payment › Create com o token a cada ciclo, se a recorrência é controlada pelo seu sistema (é o caso do Parenzo).
  4. Asaas Trigger com PAYMENT_CONFIRMED/PAYMENT_RECEIVED/PAYMENT_OVERDUE/PAYMENT_CREDIT_CARD_CAPTURE_REFUSED para atualizar o seu sistema.
  5. Trocar cartão de uma assinatura: Subscription › Update Credit Card.

Tokenização em produção precisa ser liberada pelo gerente da conta Asaas.

Segurança (PCI)

  • Número e CVV passam pela execução em Credit Card › Tokenize e nos campos Credit Card (JSON). Em todo workflow que usa essas operações, desligue Settings › Save successful/failed production executions (e não use Save manual executions com dados reais).
  • Os campos de número, CVV, token e auth token são do tipo senha (não aparecem na tela).
  • Guarde só o token e o final do cartão.

Instalação

Pela interface (instância self-hosted)

Settings › Community Nodes › Install → n8n-nodes-asaas-billing (depois de publicado no npm).

Manual (sem publicar)

cd ~/workspace/parenzo/n8n/n8n-nodes-asaas && npm install && npm run build && npm pack
# copie o .tgz para o servidor do n8n e, dentro de ~/.n8n/nodes:
npm install /caminho/n8n-nodes-asaas-billing-0.1.0.tgz
# reinicie o n8n

Publicar no npm

cd ~/workspace/parenzo/n8n/n8n-nodes-asaas && npm version patch && npm run release

Build

cd ~/workspace/parenzo/n8n/n8n-nodes-asaas && npm install && npm test && npm run build && npm run copy-assets

O pacote usa prepack e prepare (mesmo padrão dos pacotes do Léo Delivery), então npm install, npm pack e npm publish geram o dist/ com os ícones. O dist/ é versionado. Publicação: NODE_AUTH_TOKEN=... npm run release (o .npmrc lê o token da variável).

  • credentials/AsaasApi.credentials.ts: credencial e teste.
  • nodes/Asaas/Asaas.node.ts: execução das operações.
  • nodes/Asaas/descriptions/*: campos de cada recurso.
  • nodes/Asaas/AsaasTrigger.node.ts: trigger (registro e validação do webhook).
  • nodes/Asaas/GenericFunctions.ts: requisição autenticada, paginação, tratamento de erro.
  • index.ts: exporta nodes e credentials; index.test.ts e nodes/Asaas/Asaas.node.test.ts: testes (vitest).

Referência da API: https://docs.asaas.com

Discussion