ASAAS — licenças e cobrança

ASAAS — licenças e cobrança (Super Admin)

Esta página é para quem opera a plataforma e precisa ligar o Omniflow ao ASAAS para licenças, assinaturas e sincronização de cobranças via webhooks.

Onde configurar na aplicação

No painel, área Super Admin, abra ASAAS (integração de cobrança). Aí define a URL da API, a chave e o token do webhook. Os valores são guardados de forma encriptada e não voltam a ser mostrados depois de gravados — apenas indicação de “configurado” ou não.

1. URL base da API

Testes (sandbox): https://sandbox.asaas.com/api/v3
Produção: https://api.asaas.com/v3

Confirme sempre no ASAAS qual endpoint corresponde à conta e ao ambiente em uso.

2. API Key

Cole a API Key da conta ASAAS usada para criar clientes, assinaturas e consultar cobranças a partir do Omniflow. Para alterar, cole uma nova chave e grave; para remover, deixe o campo vazio e grave.

3. Webhook e token

Registe no ASAAS um webhook que aponte para o seu backend público:

POST /api/webhooks/asaas (URL completa: https:// + domínio ou host da API + /api/webhooks/asaas)

O Omniflow valida um token secreto que deve ser o mesmo que define no campo Webhook Token no painel. O token pode ser enviado pelo ASAAS num destes formatos (conforme permitido na configuração do webhook):

Cabeçalho asaas-access-token
Cabeçalho Authorization: Bearer <token>
Cabeçalho x-asaas-token

Produção

Em produção, o Webhook Token deve estar configurado no Omniflow; caso contrário os webhooks são rejeitados. Em sandbox, é possível operar sem token (menos seguro), útil só para testes.

No ASAAS, ative os eventos de pagamentos e assinaturas necessários para que o estado financeiro dos tenants se mantém atualizado no Omniflow.

4. Depois de configurado

Licenças e Cobranças: visão por tenant, cliente e assinatura no ASAAS, cobranças e ações de sincronização. Nos detalhes do tenant, pode remover a assinatura (motivo obrigatório para auditoria): o Omniflow pede ao ASAAS a exclusão das cobranças em aberto relacionadas à assinatura (listagem da própria assinatura) e das pendentes ou vencidas já registadas para o tenant, remove a assinatura no ASAAS, marca no Omniflow todas as cobranças pendentes ou vencidas desse tenant como excluídas, fecha agendamentos de bloqueio e define o tenant como ativo. Enquanto o tenant não tiver assinatura cobrável, eventos ASAAS que impliquem inadimplência não voltam a agendar bloqueio automático.
Agendamentos de bloqueio: fila de bloqueios previstos, cancelamento administrativo, liberação de confiança e execução quando aplicável à política da instalação.

Os administradores do tenant podem consultar informação da licença em Configurações → Licença no painel da empresa (sem expor credenciais ASAAS).

5. Formas de cobrança

A integração de licenças trabalha com Boleto e PIX como formas de cobrança suportadas neste fluxo.

6. Mudança de plano com confirmação (aplicar agora ou próximo ciclo)

Quando o tenant já tem assinatura ativa e o plano é alterado no Super Admin:

o sistema abre um modal de confirmação com resumo do impacto da troca;
pode escolher aplicar agora ou aplicar no próximo ciclo:
- Aplicar agora: atualização dos limites do tenant e sincronização da assinatura no Asaas de imediato, com as regras de ciclo abaixo (prorrata no upgrade e crédito proporcional no downgrade quando dentro do ciclo pago).
- Aplicar no próximo ciclo: não altera a cobrança atual nem os limites; guarda um agendamento até a cobrança em aberto do período atual ser quitada; só então o novo plano e o valor integral passam a valer. Na lista de tenants aparece um aviso «Troca agendada» com referência ao vencimento; em Agendamentos pode ver todas as trocas pendentes e cancelar um agendamento quando necessário.
após confirmar no modo imediato, a sincronização com o Asaas corre no mesmo fluxo da atualização do tenant.

Regra de ciclo (upgrade e downgrade) — modo aplicar agora

A lógica operacional considera que o tenant está dentro de ciclo quando, ao mesmo tempo:

existe uma última cobrança paga (confirmed ou received);
existe uma próxima cobrança em aberto (pending ou overdue);
a data atual está no intervalo entre essas duas cobranças.

Se não estiver dentro de ciclo, não há prorrata de meio de ciclo: o sistema aplica o novo valor/ciclo nas cobranças futuras normalmente.

Como a prorrata é calculada no meio do ciclo

Para upgrade e downgrade é usada a mesma regra proporcional por dia:

dias já usados no plano antigo + dias restantes no plano novo;
cálculo da cobrança aberta:
(valor_antigo / dias_do_ciclo * dias_usados) + (valor_novo / dias_do_ciclo * dias_restantes).

As próximas cobranças (ciclo seguinte em diante) ficam no valor cheio do novo plano.

No modo aplicar agora, para upgrade a cobrança em aberto é ajustada para o valor proporcional (blended). Para downgrade, é criado um crédito interno no Omniflow proporcional à diferença, aplicável às cobranças em aberto via fluxo de créditos (equivale ao proporcional sem baixar manualmente linha a linha).

Exemplo prático — agendar para o próximo ciclo

Tenant mensal com fatura em aberto vencendo em 01/02 e alteração pedida em 15/01.
Ao escolher próximo ciclo, até o cliente quitar essa fatura nada muda nos limites nem no valor da assinatura no Asaas.
Após o pagamento confirmado, o sistema aplica o novo plano (limites + assinatura Asaas + primeira cobrança do novo ciclo no valor cheio do plano novo).

Exemplos práticos (modo aplicar agora)

Exemplo 1 — Upgrade no meio do ciclo (mensal)

ciclo: 01/01 -> 01/02 (31 dias)
plano antigo: R$ 500
plano novo: R$ 1.000
troca em 15/01 (15 dias usados no antigo, 16 dias no novo)

Resultado da cobrança aberta:

(500/31 * 15) + (1000/31 * 16) = R$ 758,06

Próximas cobranças:

R$ 1.000,00

Exemplo 2 — Downgrade no meio do ciclo (mensal) — modo aplicar agora

ciclo: 01/01 -> 01/02 (31 dias)
plano antigo: R$ 500
plano novo: R$ 100
troca em 15/01

Valor proporcional de referência (mesma fórmula que no upgrade):

(500/31 * 15) + (100/31 * 16) = R$ 293,55

Na implementação atual, o downgrade cria um crédito interno correspondente à diferença entre o valor da cobrança em aberto e esse proporcional; esse crédito é consumido nas cobranças em aberto pelo fluxo habitual de créditos.

Próximas cobranças:

R$ 100,00

7. Cupons e indicações

No menu Cupons e Indicações do Super Admin é possível:

criar cupons com desconto percentual e duração configurável (primeiras cobranças ou vitalício);
criar links de indicação com identificação do indicador;
vincular cupom a uma indicação;
acompanhar comissões pendentes e marcar pagamento manual.

Os links de cadastro usam a página pública de registo com parâmetros (coupon e ref), aplicando automaticamente os dados promocionais no cadastro.