Dancei · Guia de configuraçãoInclui os eventos de assinatura

Conectar o Asaas ao Dancei

Depois desta configuração, todo pagamento que cair no Asaas atualiza sozinho no Dancei: a cobrança vira Paga, o recebimento entra no histórico e o aluno sai da inadimplência. Sem ninguém dar baixa na mão.

Tempo10 a 15 minutos
Você vai precisarAcesso de administrador no Dancei e no Asaas
Feito uma vezPor escola, e vale para sempre

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.

Etapa 1 · no Dancei

Gerar o token de segurança

Comece aqui. O token gerado nesta etapa é usado na Etapa 2.

1

Abra as configurações de pagamento

Entre no Dancei como administrador e vá em Configurações → Pagamentos.

2

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.

Chave de produção — cobranças reais$aact_prod_…Selecione o ambiente Produção.
Chave de testes — nada é cobrado de verdade$aact_hmlg_…Selecione o ambiente Sandbox.
Atenção
A chave e o ambiente têm que combinar. Chave de produção com ambiente Sandbox (ou o contrário) faz todas as cobranças falharem.
3

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.

Não pule o Salvar
Gerar não salva. Se sair da tela sem clicar em Salvar Token de Segurança, o token some e o Asaas será recusado depois.
Trate como senha
Não mande esse token por grupo de WhatsApp, não cole em print de tela e não passe para terceiros. Se vazar, volte nesta tela, gere outro e atualize no Asaas.
Etapa 2 · no Asaas

Cadastrar o webhook

Abra o painel do Asaas em outra aba — asaas.com para produção, sandbox.asaas.com para testes.

4

Vá para a tela de webhooks

No Asaas: Configurações → Integrações → Webhooks. Clique em Novo Webhook.

5

Preencha os dados do webhook

Copie cada valor exatamente como está abaixo.

Nome
Dancei — Cobranças
Nome livre, serve só para você identificar depois.
URL de integração
https://dancei.com.br/api/webhooks/asaas
É a mesma URL para todas as escolas. Quem separa uma escola da outra é o token.
E-mail para notificação de falhasseu e-mail administrativoO Asaas avisa aqui se o envio começar a falhar. Use um e-mail que alguém realmente lê.
StatusAtivo
Versão da APIv3
6

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.

Token de autenticaçãocole aqui o token de 64 caracteres gerado no DanceiCole inteiro, sem espaço antes nem depois. Um caractere a mais ou a menos e o Dancei recusa o aviso.
Não clique em “Gerar Token” aqui
Do lado do campo existe um botão Gerar Token. Ele cria um token novo, inventado pelo Asaas, que o Dancei não conhece — e todos os avisos passam a ser recusados. O token válido é só o que veio do Dancei. Se você clicou por engano, apague o conteúdo do campo e cole o token do Dancei por cima.
Não procure por campo de header
O Asaas não pede o nome do header. Ele envia esse token sozinho, no header asaas-access-token, que é exatamente o que o Dancei espera. Você só precisa colar o valor.
Etapa 2 · no Asaas

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.

EventoQuando disparaO que o Dancei fazTipo
PAYMENT_RECEIVEDPagamento recebidoBoleto compensou ou o dinheiro caiu na contaCobrança vira Paga, lança o recebimento e regulariza o alunoEntrada
PAYMENT_CONFIRMEDPagamento confirmadoPIX ou cartão aprovado na horaMesma coisa, só que instantâneoEntrada
PAYMENT_OVERDUEPagamento vencidoPassou do vencimento sem pagarCobrança vira Atrasada e o aluno entra como inadimplenteRisco
PAYMENT_DELETEDCobrança removidaA cobrança foi apagada no AsaasCobrança vira Cancelada no DanceiControle
PAYMENT_REFUNDEDPagamento estornadoO valor foi devolvido ao alunoCobrança volta para PendenteControle
Por que não marcar tudo
O próprio Asaas avisa na tela: quanto menos eventos selecionados, mais rápido é o envio. Ele oferece dezenas — 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.
Recebimento em dinheiro
Não procure por um evento de “recebido em dinheiro” — ele não existe nessa lista. Quando alguém marca uma cobrança como paga em espécie no Asaas, o aviso que sai é o 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.
Etapa 2 · no Asaas

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.

7

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.

EventoQuando disparaO que o Dancei faz
SUBSCRIPTION_OVERDUEAssinatura vencidaA assinatura ficou em atrasoMarca o aluno como inadimplente
SUBSCRIPTION_DELETEDAssinatura canceladaA assinatura foi encerrada no AsaasDesvincula a assinatura da matrícula, para não gerar cobrança fantasma
SUBSCRIPTION_CREATEDAssinatura criadaAssinatura foi abertaNada muda na tela — marque para o ciclo ficar completo
SUBSCRIPTION_RENEWEDAssinatura renovadaVirou o ciclo e nasceu a próxima parcelaNada muda na tela — a parcela em si entra pelos eventos de cobrança
SUBSCRIPTION_INACTIVEAssinatura inativaA assinatura foi suspensaNada muda na tela — marque para o ciclo ficar completo
Não marque
SUBSCRIPTION_UPDATED não é usado pelo Dancei. Deixe desmarcado.
Etapa 2 · no Asaas

Ajustes finais e salvar

8

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.
9

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.

A

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.

Abrir no navegador
https://dancei.com.br/api/webhooks/asaas
B

Teste com uma cobrança de verdade

  1. Gere uma cobrança de valor baixo para um aluno no Dancei.
  2. Pague o PIX (ou, no ambiente de testes, use Simular pagamento no Asaas).
  3. Volte ao Dancei e atualize a tela do financeiro.
Deu certo quando
Em menos de um minuto a cobrança aparece como Paga, o recebimento está no histórico do aluno e, se ele estava devendo, o status volta para Ativo.

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.

O Asaas mostra erro 401
Token errado, ausente ou não salvo. Na maioria das vezes é porque alguém clicou em Gerar Token dentro do Asaas em vez de colar o token do Dancei. Volte ao Dancei em Configurações → Pagamentos, copie o token de novo e cole por cima no campo Token de autenticação do Asaas.
O Asaas mostra erro 307 ou fica redirecionando
A URL está diferente. Precisa ser https://dancei.com.br/api/webhooks/asaas — com https, sem barra no final e sem nada depois de asaas.
Nenhum aviso chega, nem erro aparece
O webhook está inativo ou nenhum evento foi marcado. Abra o webhook no Asaas, confirme o status Ativo e confira as marcações da lista de eventos.
O pagamento entra, mas o aluno continua inadimplente
Faltou marcar PAYMENT_CONFIRMED ou PAYMENT_RECEIVED. Muita gente marca só um dos dois — os dois precisam estar ligados, porque PIX e boleto usam caminhos diferentes.
A fila do Asaas vive travada ou atrasada
Eventos demais marcados. Volte na lista e desmarque tudo que não está nas tabelas deste guia — principalmente PAYMENT_CREATED e PAYMENT_UPDATED, que disparam o tempo todo e o Dancei descarta.
Cobrança não aparece como atrasada
Faltou PAYMENT_OVERDUE.
O plano é anual no cartão e nada atualiza
Faltam os eventos de Assinaturas. Volte à Etapa 7 deste guia.
Funcionava e parou do nada
Alguém trocou a API Key ou gerou um token novo no Dancei sem atualizar no Asaas. Gerar token novo invalida o anterior na hora — sempre atualize os dois lados juntos.

Checklist final

Passe o olho antes de dar por encerrado.

No Dancei

API Key do Asaas cadastrada
Ambiente combina com o tipo da chave
Token gerado e salvo
Token copiado por inteiro

No Asaas

URL https://dancei.com.br/api/webhooks/asaas
Token de autenticação = o token vindo do Dancei (não o gerado no Asaas)
Os 5 eventos de cobrança marcados
Os 5 de assinatura, se houver plano recorrente
Versão da API em v3
Fila de sincronização ativada
Nenhum evento extra marcado
Status Ativo e configuração salva

Teste

Cobrança de teste paga
Status virou Paga sozinho
Recebimento no histórico do aluno