Asaas no n8n: cobranças e avisos de pagamento
Monte o HTTP Request com a chave do Sandbox, crie cliente e cobrança, cadastre o webhook no Asaas, trate eventos repetidos e só depois passe para a produção.
Por Redação Eleven Host · @robson.direitodigital · 17 de novembro de 2026 · 9 min de leitura

Capa da Redação Eleven Host para o guia: Asaas no n8n: cobranças e avisos de pagamento Arte: Eleven Host
Usar asaas no n8n é criar clientes e cobranças pela API do Asaas com o nó HTTP Request e receber os avisos de pagamento com o nó Webhook, porque o n8n não tem nó oficial do Asaas.
PAYMENT_CONFIRMED não significa dinheiro disponível na conta. O evento de cobrança recebida, com o valor disponível, é o PAYMENT_RECEIVED.
Atualizado em 17/11/2026. Em 17/11/2026, a versão estável do n8n é a 2.48.4, publicada em 13/11/2026, e a lista de nós nativos não traz o Asaas.
O que existe e o que falta no n8n
Sem nó do Asaas entre os nós nativos, o caminho é montado com dois deles: o HTTP Request chama a API do Asaas, e o Webhook recebe os avisos de pagamento. A autenticação usa o cabeçalho access_token.
O próprio Asaas publica um nó da comunidade, o pacote @asaasbr/n8n-nodes-asaas, que a documentação do Asaas chama de nó oficial do Asaas. Para o n8n, ele é um nó de terceiros, instalado em Settings > Community Nodes. Os passos abaixo usam só nós do próprio n8n.
Para quem serve
Serve para quem cobra pelo Asaas e roda o n8n na própria VPS: criar cliente e cobrança, gerar o Pix copia e cola e dar baixa quando o pagamento chega. Para o básico de servidor, há o artigo sobre servidor VPS.
Opções de VPS à venda na Eleven Host, em seis planos. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver VPS
Passo 1: começar pelo Sandbox
O Asaas tem dois ambientes, cada um com URL e chave próprias. A produção usa https://api.asaas.com/v3, e o Sandbox usa https://api-sandbox.asaas.com/v3. A chave do Sandbox começa com $aact_hmlg_. Uma chave de um ambiente não funciona no outro.
Crie uma conta Sandbox e faça os testes nela. A produção entra só no último passo.
Passo 2: gerar a chave de API e criar a credencial
Na aplicação web do Asaas, abra Integrações > Chaves de API. Só o administrador cria chaves, e o app de celular não faz isso. A chave aparece uma única vez e não pode ser recuperada depois, então copie na hora. Se perder, crie outra.
A chave sem uso é desabilitada após 3 meses e expira após 6 meses, e a chave expirada não pode ser reativada. Por isso, um fluxo pouco usado pode parar sozinho.
No n8n, crie uma credencial Header Auth com Name igual a access_token e Value igual à chave do Sandbox. Não coloque a chave em código público, aplicação de frontend, imagem, log ou repositório.
Passo 3: criar um cliente
Crie um workflow com gatilho manual e um nó HTTP Request. Use o método POST e a URL https://api-sandbox.asaas.com/v3/customers. Em Authentication, escolha Generic Credential Type, depois Header Auth e a credencial do passo 2. Em Send Headers, acrescente User-Agent com o nome da sua aplicação, como minha-empresa-n8n, exigido das contas raiz criadas a partir de 13/06/2024.
Ative Send Body com Body Content Type igual a JSON. O cliente exige name e cpfCnpj; email, mobilePhone e externalReference são opcionais. O externalReference guarda o identificador do cliente no seu sistema.
Um exemplo de corpo, para conferir na documentação do Asaas antes de usar:
{ "name": "{{ $json.nome }}", "cpfCnpj": "{{ $json.cpf }}", "email": "{{ $json.email }}", "externalReference": "{{ $json.id }}" }
A resposta traz o id do cliente, no formato cus_.... A API permite cliente duplicado, então consulte antes de criar. Se a chamada der timeout, confira se o cliente foi criado antes de repetir.
Passo 4: criar e consultar uma cobrança
Um segundo nó HTTP Request faz POST em https://api-sandbox.asaas.com/v3/payments. Os campos obrigatórios são customer (o id cus_...), billingType, value e dueDate. O billingType aceita BOLETO, CREDIT_CARD, PIX e UNDEFINED, em que o pagador escolhe entre as formas habilitadas.
Um exemplo de corpo para uma cobrança Pix, também para conferir na documentação do Asaas:
{ "customer": "{{ $json.id }}", "billingType": "PIX", "value": 99.90, "dueDate": "2026-12-10" }
O que a resposta traz
idda cobrança, no formatopay_..., estatus;invoiceUrl(URL da fatura) ebankSlipUrl(URL do boleto).
Para o Pix copia e cola, outro HTTP Request faz GET em /v3/payments/{id}/pixQrCode. A resposta traz encodedImage (a imagem do QR Code em base64), payload (o copia e cola) e expirationDate. Se a cobrança for alterada, busque um QR Code novo.
Para consultar uma cobrança, use GET em /v3/payments/{id}. Se a conta tem configuração global de juros e multa, não envie os objetos interest e fine, porque enviar valor nulo ou vazio pode sobrescrever a configuração. Com webhook ativo, o Asaas orienta a não repetir consultas GET para acompanhar mudanças.
Passo 5: o nó Webhook no n8n
O Asaas é quem chama o seu fluxo, então o n8n precisa de uma URL pública. Com proxy reverso, defina N8N_WEBHOOK_URL com o endereço público, como https://n8n.exemplo.com/, junto com N8N_PROXY_HOPS=1. A variável antiga WEBHOOK_URL está obsoleta desde o n8n 2.35.0 e gera aviso no log. Recomendamos HTTPS.
Adicione um nó Webhook com HTTP Method igual a POST e Respond igual a Immediately, já que o Asaas pede que não se demore para responder. Em Authentication, escolha Header Auth e crie uma credencial com Name igual a asaas-access-token. No Value vai o mesmo token que será informado no Auth Token do Asaas no passo seguinte; se ainda não o tiver, use um valor provisório e troque depois de gerar o token.
O nó mostra a Test URL, que só escuta enquanto você clica em Listen for Test Event, e a Production URL, que só funciona depois de publicar o fluxo. É a Production URL que vai para o Asaas, e os dados recebidos aparecem em Executions.
Passo 6: cadastrar o webhook no Asaas
No Sandbox, abra o menu do usuário e vá em Integrações > Webhooks, depois em criar webhook. Preencha nome, URL (a Production URL do passo 5), e-mail e Auth Token. O botão Gerar token cria o valor; copie-o para o Value da credencial do passo 5.
O token deve ter entre 32 e 255 caracteres, sem espaços em branco, e evitar sequências simples. Também não pode ser uma chave de API do Asaas. Ele chega no cabeçalho asaas-access-token, e a autenticação do nó Webhook deve conferir esse valor antes de o fluxo rodar; confira isso no seu servidor. Marque só os eventos de que precisa, como PAYMENT_RECEIVED e PAYMENT_OVERDUE.
PAYMENT_CONFIRMED ou PAYMENT_RECEIVED
O PAYMENT_CONFIRMED indica pagamento efetuado, mas com saldo ainda não disponível. O PAYMENT_RECEIVED indica cobrança recebida, com o valor disponível na conta Asaas. Por isso, recomendamos decidir, para cada forma de pagamento, em qual dos dois eventos o pedido é liberado.
Como cada forma de pagamento se comporta
- Pix: não tem CONFIRMED e vai direto para RECEIVED;
- Boleto: passa por CONFIRMED e depois vai para RECEIVED;
- Cartão de crédito: fica CONFIRMED em dia e só vira RECEIVED após 32 dias;
- Cartão de débito: a passagem para RECEIVED leva 3 dias.
Passo 7: eventos repetidos e fila pausada
O aviso é um POST com o id do evento, o event (por exemplo PAYMENT_RECEIVED) e o objeto payment.
A entrega segue o modelo at least once: o mesmo evento pode chegar mais de uma vez. Guarde o id do evento numa planilha ou num banco e confira se ele já foi tratado antes de agir. O Asaas orienta responder 200 depois de registrar o evento, sem esperar processamentos demorados. Com Immediately, o n8n responde assim que o fluxo começa, então registre o evento logo nos primeiros nós.
Depois de 15 falhas consecutivas, a fila daquele webhook é interrompida. Os eventos novos ficam guardados, mas os que passam de 14 dias são excluídos de forma permanente. Veja a causa nos Logs de Webhooks.
Corrija a falha antes de reativar a fila pelo painel. Os eventos guardados são reenviados.
Passo 8: ir para a produção
Com o fluxo ajustado no Sandbox, gere uma chave de produção, crie outra credencial no n8n e troque a URL para https://api.asaas.com/v3. Cadastre também um webhook novo na conta de produção: contas e chaves dos dois ambientes não se misturam.
Combinações para começar
Um exemplo: pedido novo vira cobrança. O fluxo consulta o cliente, cria se não existir, cria a cobrança Pix e envia o copia e cola ao comprador. Confira no seu servidor, com a chave do Sandbox.
Um exemplo: baixa automática de um Pix. O Webhook recebe o aviso, um nó IF confere se o campo event é PAYMENT_RECEIVED, e só então o pedido é liberado. Veja também Mercado Pago no n8n: receba avisos de pagamento.
Um exemplo: aviso de vencimento. O evento PAYMENT_OVERDUE dispara uma mensagem à equipe financeira. Outra API de cobrança está em Stripe no n8n: automatize cobranças e pagamentos.
Problemas comuns
- Erro 401 com
invalid_environment: a chave é de outro ambiente; - Erro 401 com
access_token_not_found: o cabeçalho não foi enviado; - Erro 401 com
invalid_access_token_format: há espaço ou caractere a mais na chave; - Erro 429: passou do limite de 50 requisições GET concorrentes ou de 25.000 requisições a cada 12 horas. Não repita a chamada na hora;
- O aviso não chega: confira se o fluxo está publicado e se o Asaas recebeu a Production URL.
Outros guias de n8n
Na base de conhecimento há outros artigos sobre n8n com meios de pagamento.
Uma VPS Eleven Host tem mensalidade conforme o plano. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver planos
Perguntas frequentes
O n8n tem nó oficial do Asaas?
Não. Na versão 2.48.4, a lista de nós nativos não traz o Asaas. O caminho é o HTTP Request com o cabeçalho access_token e o nó Webhook para os avisos.
Dá para consultar a chave de API depois?
Não. Ela aparece uma única vez, e quem perde a chave cria outra.
O Asaas envia cada evento uma vez só?
Não. A entrega é at least once, e o mesmo evento pode chegar mais de uma vez. Use o id do evento para não processar duas vezes.