Faturamento - Trocar de Plano

O que é

A troca de plano é o caminho para subir (upgrade) ou descer (downgrade) o nível da sua assinatura no Viagilize sem perder dados. Os planos disponíveis são Free, Starter, Profissional e White Label, ofertados em ciclo mensal ou anual.

O usuário normalmente chega aqui em duas situações: quando precisa liberar recursos bloqueados (limites de excursões, módulos exclusivos de planos superiores) ou quando quer reduzir a mensalidade após uma temporada de menor uso. A página apresenta todos os planos lado a lado, marca o plano atual e habilita botões diferentes conforme o destino é maior ou menor que o plano atual.

Como usar

Fazer upgrade (plano maior que o atual)

1. Vá em Configurações > Faturamento no sidebar (ou abra /admin/billing).
2. Role até a seção Planos e escolha a aba Mensal ou Anual conforme o ciclo desejado.
3. No card do plano superior, clique em Fazer Upgrade.
4. No modal Upgrade para {nome do plano}, leia o aviso de Cobrança Proporcional e confirme em Ver Cálculo e Pagar.
5. Você é levado para /admin/billing/upgrade?plan_slug=..., onde aparece o Cálculo do Valor: crédito do plano atual (proporcional aos dias restantes), valor do novo plano também proporcional, e o Total a pagar agora.
6. Em Escolha a forma de pagamento, selecione PIX ou Cartão de Crédito (Mercado Pago).
7. Clique em Gerar QR Code PIX (verde) ou Pagar com Cartão (roxo).
8. Para PIX: escaneie o QR Code ou use o campo PIX Copia e Cola e aguarde a confirmação automática (a página faz polling a cada 5 segundos). O PIX expira em 30 minutos.
9. Assim que o pagamento é confirmado, o plano é trocado automaticamente e você é redirecionado para /admin/billing.

Fazer downgrade (plano menor que o atual)

1. Acesse /admin/billing e, no card do plano inferior, clique em Mudar para este.
2. No modal Mudar para {nome do plano}, leia a seção Como funciona o downgrade e o aviso Atenção sobre funcionalidades.
3. Confira a Data de mudança (que é o final do período pago atual) e o novo valor.
4. Clique em Confirmar Mudança.
5. A página exibe um aviso azul Downgrade agendado no topo do card do plano atual com a data efetiva.

Cancelar um downgrade agendado

1. Em /admin/billing, localize o aviso azul Downgrade agendado logo abaixo do card do plano atual.
2. Clique em Cancelar downgrade.
3. O agendamento é desfeito e o plano atual continua valendo após a próxima renovação.

Casos especiais

Upgrade gratuito (sem cobrança proporcional)

Se a sua empresa está em um plano sem custo (ex.: Free) e migra para outro também sem custo, ou o cálculo proporcional resulta em valor zero, o sistema aplica a troca imediatamente sem gerar PIX nem checkout. A página retorna direto para /admin/billing com a mensagem Plano atualizado com sucesso!.

Upgrade pendente de pagamento

Se você gerou um PIX de upgrade e ainda não pagou, o card do plano destino mostra dois botões em vez de Fazer Upgrade:

• Pagar Upgrade (verde, cor PIX #32BCAD) abre o modal com o QR Code já gerado.
• Cancelar Upgrade (vermelho) descarta o pagamento pendente e libera o botão Fazer Upgrade de novo.

Trocar de plano por meio de um PIX novo cancela automaticamente PIX anteriores do tipo subscription e upgrade para evitar cobrança duplicada.

Downgrade já agendado para outro plano

Se já existe um downgrade agendado e você clica em Mudar para este em um plano diferente, o agendamento anterior é substituído pelo novo destino. O card do plano com agendamento ativo mostra a tarja Mudança Agendada e o botão Agendado para dd/mm, desabilitado.

Tela de assinatura bloqueada

Quando a assinatura está em status blocked, você é forçado para /admin/subscription/blocked. Nessa tela existe uma variação do upgrade - Trocar plano - que aciona a rota subscription.change-plan (POST /admin/subscription/change-plan) e gera um PIX consolidando o novo plano com os módulos adicionais já contratados. Planos gratuitos não são aceitos nesse fluxo, porque a tela de bloqueio exige um plano pago para reativar.

Plano marcado como Inativo no catálogo

Se o plano atual da sua empresa foi marcado como inativo pelo SuperAdmin, todos os outros planos aparecem com o botão Assinar Agora (em vez de Fazer Upgrade ou Mudar para este), porque o sistema não consegue calcular diferença proporcional contra um plano descontinuado.

Erros comuns e como resolver

• "Você já está neste plano." - Causa: o plan_slug enviado é igual ao plano atual. Solução: escolha outro plano na grade.
• "Erro ao gerar pagamento de upgrade." - Causa: falha do meio de pagamento ao criar o PIX (instabilidade do Mercado Pago ou credenciais inválidas). Solução: tente novamente em alguns minutos. Se persistir, abra um chamado em Suporte.
• "Erro ao agendar downgrade." - Causa: validação do BillingService::scheduleDowngrade falhou (ex.: período atual sem data definida). Solução: confira em Plano Atual se a Próxima cobrança tem data válida; se não tiver, contate o suporte.
• "Plano não encontrado." - Causa: plan_slug da URL não bate com nenhum plano ativo em billing_plans. Solução: volte para /admin/billing e clique novamente no card pelo botão da tela.
• "Selecione um plano pago para reativar a assinatura." - Causa: na tela de bloqueio, foi escolhido um plano de preço zero. Solução: escolha Starter, Profissional ou White Label.

Onde encontrar

• URL: /admin/billing (grade de planos) e /admin/billing/upgrade (cálculo + pagamento)
• Caminho no menu: Configurações > Faturamento
• Permissão necessária: nenhuma específica - qualquer usuário com acesso à área administrativa enxerga, mas o Proprietário é o papel recomendado para confirmar a troca, pois a ação altera o valor cobrado.
• Módulo necessário: nenhum.

Veja também

• Visão Geral do Faturamento - entender o ciclo de cobrança e os componentes do plano antes de trocar.
• Módulos Adicionais - depois do upgrade, ative os módulos extras que o novo plano não inclua.
• Formas de Pagamento - escolher PIX ou cartão para a cobrança proporcional.
• Carteira de Créditos - o saldo da carteira (comissões de afiliados) é aplicado automaticamente na próxima cobrança gerada pela troca.