Como funciona
O Asaas cobra e recebe. O Dancei controla matrículas, mensalidades e inadimplência. O webhook é o aviso automático que o Asaas dispara para o Dancei toda vez que algo acontece com uma cobrança — pagou, venceu, foi estornada.
Para o Asaas ter certeza de que está falando com a sua escola e não com outra, ele envia junto uma senha secreta (chamada de token). Essa senha é gerada dentro do Dancei e colada no Asaas. É só isso que este guia faz: gerar a senha, cadastrar o endereço e escolher quais avisos você quer receber.
Gerar o token de segurança
Comece aqui. O token gerado nesta etapa é usado na Etapa 2.
Abra as configurações de pagamento
Entre no Dancei como administrador e vá em Configurações → Pagamentos.
Cadastre suas credenciais do Asaas
Preencha a API Key (copiada do painel do Asaas em Configurações → Integrações → API) e escolha o Ambiente. Clique em Salvar Configurações.
Gere e salve o token
Ainda na mesma tela, desça até Token de Segurança do Webhook. Clique em Gerar Token — aparece um código de 64 caracteres. Clique no ícone de copiar ao lado do campo e depois em Salvar Token de Segurança.
Cadastrar o webhook
Abra o painel do Asaas em outra aba — asaas.com para produção, sandbox.asaas.com para testes.
Vá para a tela de webhooks
No Asaas: Configurações → Integrações → Webhooks. Clique em Novo Webhook.
Preencha os dados do webhook
Copie cada valor exatamente como está abaixo.
Cole o token no campo Token de autenticação
Esta é a parte que mais dá erro. No campo Token de autenticação, cole o token de 64 caracteres que você gerou no Dancei no passo 3.
asaas-access-token, que é exatamente o que o Dancei espera. Você só precisa colar o valor.Marque estes 5 eventos de cobrança
Role até Adicionar Eventos e abra o grupo Cobranças. A lista é longa — marque exatamente estes cinco e ignore o resto.
| Evento | Quando dispara | O que o Dancei faz | Tipo |
|---|---|---|---|
| PAYMENT_RECEIVEDPagamento recebido | Boleto compensou ou o dinheiro caiu na conta | Cobrança vira Paga, lança o recebimento e regulariza o aluno | Entrada |
| PAYMENT_CONFIRMEDPagamento confirmado | PIX ou cartão aprovado na hora | Mesma coisa, só que instantâneo | Entrada |
| PAYMENT_OVERDUEPagamento vencido | Passou do vencimento sem pagar | Cobrança vira Atrasada e o aluno entra como inadimplente | Risco |
| PAYMENT_DELETEDCobrança removida | A cobrança foi apagada no Asaas | Cobrança vira Cancelada no Dancei | Controle |
| PAYMENT_REFUNDEDPagamento estornado | O valor foi devolvido ao aluno | Cobrança volta para Pendente | Controle |
PAYMENT_CREATED, PAYMENT_UPDATED, PAYMENT_BANK_SLIP_VIEWED, PAYMENT_CHECKOUT_VIEWED, análise de risco, chargeback. O Dancei ignora todos esses. Marcá-los só enche a fila de avisos inúteis e atrasa os que importam.PAYMENT_RECEIVED, que você já marcou. PAYMENT_RECEIVED_IN_CASH_UNDONE é outra coisa (desfazer esse recebimento) e ainda não é tratado pelo Dancei — deixe desmarcado.Se a escola cobra planos recorrentes no cartão
Vale para planos trimestral, semestral ou anual cobrados como assinatura no cartão. Se a escola só trabalha com mensalidade em PIX e boleto, pule esta parte.
Marque também os eventos de assinatura
Na mesma tela de eventos, procure o grupo Assinaturas e marque os cinco abaixo. Se o seu painel não permitir juntar cobranças e assinaturas no mesmo webhook, crie um segundo webhook com a mesma URL e o mesmo token, marcando só estes eventos.
| Evento | Quando dispara | O que o Dancei faz |
|---|---|---|
| SUBSCRIPTION_OVERDUEAssinatura vencida | A assinatura ficou em atraso | Marca o aluno como inadimplente |
| SUBSCRIPTION_DELETEDAssinatura cancelada | A assinatura foi encerrada no Asaas | Desvincula a assinatura da matrícula, para não gerar cobrança fantasma |
| SUBSCRIPTION_CREATEDAssinatura criada | Assinatura foi aberta | Nada muda na tela — marque para o ciclo ficar completo |
| SUBSCRIPTION_RENEWEDAssinatura renovada | Virou o ciclo e nasceu a próxima parcela | Nada muda na tela — a parcela em si entra pelos eventos de cobrança |
| SUBSCRIPTION_INACTIVEAssinatura inativa | A assinatura foi suspensa | Nada muda na tela — marque para o ciclo ficar completo |
SUBSCRIPTION_UPDATED não é usado pelo Dancei. Deixe desmarcado.Ajustes finais e salvar
Confira as opções de envio
- Fila de sincronização ativa. Se o sistema ficar fora do ar por um instante, o Asaas guarda os avisos e reenvia. Sem isso, um pagamento pode se perder.
- Status Ativo, senão o webhook fica cadastrado mas mudo.
- Nenhum evento sobrando. Passe o olho na lista antes de salvar: só devem estar marcados os das tabelas acima.
Salve
Clique em Salvar. Pronto — a integração já está no ar.
Confirme que funcionou
Não confie no “salvou sem erro”. Faça um teste de verdade, leva dois minutos.
Teste rápido do endereço
Abra este link no navegador. Se aparecer um texto com a lista de eventos, o endereço está no ar.
Teste com uma cobrança de verdade
- Gere uma cobrança de valor baixo para um aluno no Dancei.
- Pague o PIX (ou, no ambiente de testes, use Simular pagamento no Asaas).
- Volte ao Dancei e atualize a tela do financeiro.
Quando não funciona
No Asaas, a tela Configurações → Integrações → Webhooks mostra o histórico de envios e o erro de cada um. Comece a investigar por ali.
https://dancei.com.br/api/webhooks/asaas — com https, sem barra no final e sem nada depois de asaas.PAYMENT_CONFIRMED ou PAYMENT_RECEIVED. Muita gente marca só um dos dois — os dois precisam estar ligados, porque PIX e boleto usam caminhos diferentes.PAYMENT_CREATED e PAYMENT_UPDATED, que disparam o tempo todo e o Dancei descarta.PAYMENT_OVERDUE.Checklist final
Passe o olho antes de dar por encerrado.
No Dancei
No Asaas
https://dancei.com.br/api/webhooks/asaas