N8N
Entenda quando usar o nó oficial do Asaas no n8n, como configurar workflows financeiros, tratar erros e publicar automações com segurança.
Integre o Asaas ao n8n
Use o nó oficial do Asaas no n8n para executar operações da API em workflows visuais e conectar processos financeiros a outros sistemas.
Para começar, instale o nó e configure uma credencial do Asaas no ambiente que será utilizado.
Quando utilizar
Use o nó do Asaas quando precisar:
- criar e gerenciar clientes;
- emitir e consultar cobranças;
- criar assinaturas e parcelamentos;
- trabalhar com Pix;
- consultar dados comerciais ou financeiros;
- gerenciar notificações;
- integrar o Asaas a ERPs, CRMs, e-commerces e outras aplicações;
- reagir a eventos do Asaas por Webhooks.
Considere uma integração direta com a API quando precisar de controle próprio sobre arquitetura, concorrência, retentativas, idempotência ou regras de negócio que não se adaptem bem a workflows visuais.
Escolha como integrar
| Necessidade | Recomendação |
|---|---|
| A operação está disponível no nó do Asaas | Use o nó oficial |
| A API possui o recurso, mas ele não está disponível no nó | Use o HTTP Request do n8n |
| A operação exige arquitetura ou controle avançado | Considere uma integração direta com a API |
O nó utiliza a API oficial do Asaas. Portanto, as mesmas regras de autenticação, validação, limites e comportamento dos recursos continuam válidas.
Recursos disponíveis
O nó organiza as operações por recursos, como:
- Clientes;
- Cobranças;
- Assinaturas;
- Parcelamentos;
- Pix (Cash-in);
- Notificações;
- Dados comerciais;
- Dados financeiros;
- Webhooks.
Novas operações podem ser adicionadas conforme novas versões do nó forem publicadas.
Antes de começar
Tenha:
- uma conta Asaas em Sandbox ou Produção;
- uma API Key do mesmo ambiente;
- uma instalação compatível do n8n;
- uma versão compatível do Node.js;
- o nó oficial do Asaas instalado.
Consulte Instalação para verificar as versões suportadas, instalar o pacote @asaasbr/n8n-nodes-asaas e configurar a credencial Asaas API.
Use uma API Key de Sandbox durante o desenvolvimento e troque para a API Key de Produção somente depois de validar o workflow completo.
As contas, dados e chaves de Sandbox e Produção são independentes.
Consulte como criar e gerenciar Chaves de API.
Como funciona
Cada workflow combina um gatilho, os nós necessários para processar os dados e as ações que serão executadas no Asaas ou em outros sistemas.
Um fluxo de cobrança pode seguir esta estrutura:
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["Receber o pedido"] --> B["Preparar os dados"]
B --> C["Localizar ou criar o cliente"]
C --> D["Criar a cobrança"]
D --> E["Armazenar o ID"]
E --> F["Receber eventos por Webhook"]
F --> G["Atualizar o sistema de origem"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
class A inicio
class B,C,D,E,F validacao
class G sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
Ao configurar um nó do Asaas, escolha:
| Item | Função |
|---|---|
| Credencial | Define a conta e o ambiente utilizados |
| Recurso | Define a área da API, como clientes ou cobranças |
| Operação | Define a ação executada no recurso |
| Campos da operação | Recebem os dados exigidos pela ação selecionada |
Utilize a resposta de cada operação para direcionar as próximas etapas e armazene os IDs necessários para reutilizar os recursos no workflow.
Acompanhe mudanças por Webhooks
A criação de um recurso não encerra necessariamente o fluxo financeiro.
Para acompanhar recebimentos, vencimentos, estornos ou outras mudanças de estado, prefira Webhooks a consultas recorrentes à API.
O n8n pode receber o evento e continuar o workflow a partir dos dados enviados pelo Asaas.
Ao processar eventos, considere que os Webhooks do Asaas utilizam entrega at least once. Armazene o id do evento para evitar executar novamente a mesma regra de negócio.
Antes de usar Produção
Valide o workflow completo em Sandbox antes de trocar as credenciais.
Confirme principalmente:
- recurso e operação selecionados;
- mapeamento dos campos;
- tratamento das respostas;
- armazenamento dos IDs retornados;
- comportamento quando um nó falha;
- tratamento de execuções duplicadas;
- recebimento dos Webhooks necessários.
Operações executadas em Produção podem criar clientes, cobranças, assinaturas e outras movimentações reais.
Próximos passos
Updated 1 day ago