Base de Conhecimento

Asaas no n8n: cobranças e avisos de pagamento

  • asaas, n8n, cobranças, webhook, pix, automação
  • Usuários acharam útil: 0

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

Arte da Eleven Host: janela de terminal com o título: Asaas no n8n: cobranças e avisos de pagamento

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

  • id da cobrança, no formato pay_..., e status;
  • invoiceUrl (URL da fatura) e bankSlipUrl (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.

Esta resposta lhe foi útil?

Artigos Relacionados