Este artigo mostra, passo a passo, como ligar o Asaas ao sistema: gerar a chave de API, cadastrá-la, criar o webhook que avisa os pagamentos e testar. Antes, leia Pagamentos: como funciona a integração para entender o que é sincronizado.
Onde encontrar (caminho até a tela):
- Pagamentos: Menu lateral › Configurações › aba Pagamentos › cartão Asaas
- No Asaas: Menu do usuário › Integrações
Precisa da permissão Gerenciar métodos de pagamento. Também dá para chegar pelo botão Cadastrar chave do aviso no Faturamento.
O sistema só acompanha as faturas geradas dentro dele. Cobranças criadas direto no painel do Asaas não entram.
Antes de começar
- Tenha uma conta no Asaas e um usuário administrador: só administradores criam chaves de API.
- Acesse o Asaas pelo navegador. A chave não é criada pelo aplicativo.
- O Asaas tem dois ambientes separados: Produção e Sandbox (testes, em sandbox.asaas.com). Cada um tem as suas próprias chaves, clientes, cobranças e webhooks. A chave de um ambiente não funciona no outro (erro 401).
- O sistema usa o ambiente definido pelo administrador da plataforma. Use a chave do mesmo ambiente. Em dúvida, pergunte a quem administra o sistema.
Passo 1: gerar a chave de API no Asaas
- No Asaas, abra o Menu do usuário › Integrações › Chaves de API (em algumas telas aparece como Chave de API).
- Clique em Gerar nova chave de API.
- Dê um nome que identifique o uso, por exemplo “Sistema de atendimento”, e, se quiser, uma data de expiração.
- Copie a chave na hora e guarde-a em local seguro. O Asaas a mostra uma única vez e ela não pode ser recuperada depois; se perder, crie outra.
| Ambiente | Como a chave começa |
|---|---|
| Produção | $aact_prod_ |
| Sandbox | $aact_hmlg_ |
- Cada conta pode ter até 10 chaves. Você pode nomear, definir expiração, desativar temporariamente ou excluir cada uma. Chave excluída não volta.
- Chave sem uso por 3 meses é desativada e, aos 6 meses, expira de vez. Chave desativada responde 401.
- Nunca guarde a chave em locais públicos, prints ou arquivos compartilhados.
Passo 2: cadastrar a chave no sistema
- Vá em Configurações › Pagamentos.
- No cartão Asaas, cole a chave no campo Token Asaas.
- Deixe Ativo ligado e, se for o gateway que você mais usa, marque Principal.
- Clique em Salvar. A chave passa a aparecer só com os 4 últimos caracteres.
Depois de salvar, aparece o bloco Token do webhook no cartão do Asaas (passo 4).
Passo 3: criar o webhook no Asaas
Sem o webhook, o link funciona e o cliente consegue pagar, mas o sistema não fica sabendo e a fatura continua aberta.
- No sistema, em Configurações › Pagamentos, copie a URL de webhook do cartão Asaas (ícone de copiar).
- No Asaas, abra Menu do usuário › Integrações › Webhooks e clique em Criar Webhook.
- Preencha o formulário conforme a tabela abaixo.
- Escolha os eventos (veja a seguir).
- Salve.
| Campo no Asaas | O que colocar |
|---|---|
| Nome | Um nome para identificar, por exemplo “Sistema de atendimento” |
| URL | A URL de webhook copiada do sistema |
| Endereço que recebe os alertas de falha do webhook | |
| Versão da API | v3, a mesma que o sistema usa |
| Auth Token | Opcional. Veja o passo 4 |
| Fila (interrompida) | Deixe desmarcada: fila interrompida não envia avisos |
| Ativo | Ligado |
| Tipo de envio | Sequencial ou Não sequencial. Qualquer um serve: o sistema consulta o estado atual da cobrança a cada aviso, então a ordem não muda o resultado |
Quais eventos marcar
Escolha os eventos de Cobranças. Os que o sistema usa para atualizar a fatura:
| Evento | Quando acontece |
|---|---|
PAYMENT_CONFIRMED | Pagamento feito, mas o saldo ainda não está disponível. O sistema já marca a fatura como Paga |
PAYMENT_RECEIVED | Cobrança recebida, com o valor disponível na conta. Paga |
PAYMENT_OVERDUE | Cobrança vencida sem pagamento. Vencida |
PAYMENT_REFUNDED | Cobrança estornada. Cancelada |
PAYMENT_CHARGEBACK_REQUESTED | Chargeback recebido. Cancelada |
- Não há problema em marcar todos os eventos de cobrança: o sistema ignora o que não usa. O Asaas recomenda marcar só o necessário.
- Se você usa a emissão de nota fiscal pelo Asaas (veja Notas fiscais (Beta)), marque também os eventos de Notas fiscais (
INVOICE_AUTHORIZED,INVOICE_CANCELED,INVOICE_ERRORe os demais). Eles chegam à mesma URL.
Regras da URL e da entrega
- A URL precisa ser pública, em HTTPS e acessível pela internet. Endereço local (localhost) não recebe avisos.
- A URL não pode redirecionar: o Asaas não segue redirecionamentos.
- O Asaas só considera entregue o aviso respondido com HTTP 200. Qualquer outro código (inclusive 201 e 204), erro de conexão ou demora conta como falha.
- O Asaas pode reenviar o mesmo aviso mais de uma vez; o sistema trata isso sem duplicar nada.
- Cada conta pode ter até 10 webhooks, cada um com seus eventos.
- Se a sua infraestrutura restringe o acesso por IP (firewall), libere a lista oficial de IPs do Asaas. Um 403 costuma indicar firewall bloqueando.
Passo 4: token do webhook (opcional)
No cartão do Asaas, o bloco Token do webhook é opcional. Sem token, o sistema já confirma cada pagamento direto no Asaas e a conta fica protegida. Para uma camada a mais:
- No sistema, clique em Gerar token.
- Copie o token na hora: ele não aparece de novo.
- No Asaas, na criação ou edição do webhook, cole no campo Auth Token. O Asaas envia esse valor no cabeçalho de cada aviso.
- Salve no Asaas.
- O token gerado pelo sistema tem 64 caracteres (letras e números), dentro do que o Asaas aceita: de 32 a 255 caracteres, sem espaços e que não seja uma chave de API.
- Gerar outro invalida o token atual. Cole o novo no Asaas, ou os pagamentos só serão processados quando o Asaas reenviar com o token certo.
- Desativar volta a depender só da confirmação direta no Asaas. O token antigo que ainda esteja no painel do Asaas passa a ser ignorado.
Passo 5: testar
- Crie uma fatura de valor baixo para um cliente seu e gere o link. Veja Link de pagamento, envio ao cliente e régua de cobrança.
- Pague pelo link, de preferência no Sandbox, se o sistema estiver apontando para ele.
- Volte ao Faturamento: a fatura deve ficar Paga, com valor, data e forma de pagamento no detalhe.
- Se não mudou, no Asaas abra Menu do usuário › Integrações › Logs de Webhooks. Eles mostram o aviso enviado, o código de resposta, as tentativas e os erros.
Se a fila do webhook for interrompida
Depois de 15 falhas seguidas, o Asaas interrompe a fila daquele webhook (os outros continuam funcionando). Os eventos ficam guardados, mas os mais antigos que 14 dias são apagados de vez.
- Em Integrações › Webhooks, o webhook mostra o status de fila interrompida. O Asaas também avisa por e-mail.
- Abra os Logs de Webhooks e descubra a causa (código de resposta e mensagem).
- Corrija o problema (URL errada, servidor fora do ar, firewall, redirecionamento).
- Reative a fila no painel do Asaas. Os avisos acumulados são reenviados.
Cuidados de segurança
- Em Integrações › Mecanismos de segurança, o Asaas permite restringir por IP quem pode usar a chave. Se você ligar isso, o IP do servidor do sistema precisa estar na lista, senão as chamadas recebem 403. Pergunte o IP a quem administra a plataforma.
- Se a chave vazar, gere outra, cadastre no sistema e exclua a antiga no Asaas.
- Sandbox e Produção têm configurações separadas: refaça o webhook em cada um.
Perguntas frequentes
O cliente pagou e a fatura continua aberta. O que conferir?
Nesta ordem: 1) o link foi gerado pelo sistema? 2) o webhook existe, está ativo e com a URL certa? 3) o Auth Token do Asaas é o mesmo do sistema (ou o token foi desativado)? 4) a fila não está interrompida? 5) a chave cadastrada é do mesmo ambiente do webhook (produção ou sandbox)? Os Logs de Webhooks do Asaas mostram o resultado de cada tentativa.
O link não foi gerado e apareceu erro de documento.
O Asaas recusou o CPF ou CNPJ do cliente. Corrija o documento no cadastro do cliente e gere o link de novo.
Apareceu erro 401 ao gerar o link.
A chave é de outro ambiente (produção x sandbox), foi desativada, expirou ou foi excluída. Gere uma nova e cadastre no sistema.
Apareceu erro 403.
A chave está restrita por IP e o servidor do sistema não está na lista, ou um firewall está bloqueando.
Criei uma cobrança direto no Asaas e ela não aparece no sistema.
É o esperado. O sistema só acompanha as faturas geradas por ele.
Posso usar a mesma chave em outro sistema?
Pode, mas o ideal é uma chave por sistema, com nome identificável, para desativar uma sem afetar a outra.
Documentação oficial do Asaas
- Chaves de API
- Criar novo webhook pela aplicação web
- Eventos de cobranças
- Fila pausada
- Whitelist de IPs