Ir para o conteúdo

Gerenciando Upgrades e Downgrades de Assinatura com Prorrogação (Proration) no 4Geeks Payments

🤖 Explicar com IA

Gerenciar os ciclos de vida das assinaturas é uma parte crítica da operação de um negócio SaaS ou de membros. Quando um cliente faz um upgrade ou downgrade de seu plano no meio de um ciclo de cobrança, o 4Geeks Payments lida automaticamente com os cálculos de prorrogação (proration). Isso garante que seus clientes sejam cobrados de forma justa — pagando apenas pelo tempo que usaram em cada plano — sem que você precise realizar cálculos manuais ou emitir reembolsos separados.

Este guia explica como realizar upgrades ou downgrades de assinatura programaticamente usando a API do 4Geeks Payments e como o sistema calcula as cobranças ou créditos proporcionais resultantes.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

  • Uma Conta 4Geeks Payments: Você deve ter uma conta de comerciante ativa.
  • Chaves de API: Suas chaves sk_test_ (para sandbox) ou sk_live_ (para produção).
  • ID da Assinatura: O identificador exclusivo (UUID) da assinatura que você deseja modificar.
  • ID do Plano: O identificador exclusivo do novo plano para o qual o cliente está mudando.
  • Acesso ao 4Geeks Console: Faça login para gerenciar e verificar as alterações.

Como Atualizar uma Assinatura

O 4Geeks Payments simplifica as alterações tratando upgrades e downgrades como uma atualização do objeto de assinatura existente. O sistema detecta automaticamente a diferença de preço e aplica a prorrogação necessária.

Passo 1: Recuperar a Assinatura Atual

  1. Faça login no 4Geeks Console.
  2. Navegue até o módulo Payments.
  3. Selecione Subscriptions na barra lateral.
  4. Pesquise pelo cliente por e-mail ou ID para listar suas assinaturas ativas.
  5. Anote o subscription_id da que você deseja atualizar.

Como alternativa, use a API para buscar assinaturas programaticamente:

  • Endpoint: GET https://api.4geeks.io/v1/subscriptions/?customer={customer_id}

Passo 2: Atualizar o Plano de Assinatura

Envie uma solicitação PUT para o endpoint da assinatura com o novo plan_id. Isso aciona a lógica de prorrogação.

  1. Prepare sua solicitação de API com a chave apropriada.
  2. Inclua os detalhes do novo plano no corpo da solicitação.

Exemplo de Solicitação (usando cURL):

curl -X PUT "https://api.4geeks.io/v1/subscriptions/sub_123456789" \
  -u "sk_test_SUA_CHAVE_API:" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "id_do_novo_plano"
  }'
  1. Envie a solicitação. O sistema calcula a prorrogação imediatamente para o ciclo de cobrança atual.

Dica: Para upgrades, espere uma fatura imediata. Para downgrades, um crédito é aplicado a faturas futuras. Evite misturar IDs de modo de teste e produção para evitar erros.

Passo 3: Verificar a Fatura Prorrogada

  1. Verifique a resposta da API para obter os detalhes da assinatura atualizada, incluindo a latest_invoice.
  2. No 4Geeks Console, vá em Invoices para visualizar a nova fatura prorrogada.
  3. Confirme o status (ex: “paid” ou “open”) e o valor devido.

Exemplo de Resposta (JSON Simplificado):

{
  "id": "sub_123456789",
  "status": "active",
  "plan": {
    "id": "id_do_novo_plano",
    "name": "Plano Pro",
    "amount": 50.00
  },
  "current_period_end": "2023-12-01T00:00:00Z",
  "latest_invoice": {
    "id": "inv_987654321",
    "amount_due": 15.50,
    "status": "paid"
  }
}

Melhor Prática: Monitore os webhooks para eventos como invoice.created ou invoice.payment_succeeded para automatizar notificações ou atualizações em seu sistema.

Casos de Uso Comuns

Cenário 1: Upgrade no Meio do Ciclo (Cobrança Imediata)

Um cliente em um Plano Básico de $10/mês faz upgrade para um Plano Pro de $30/mês na metade do mês.

  • O sistema credita ~\(5 pelo tempo não utilizado do Plano Básico e cobra ~\)15 pelo tempo restante do Plano Pro.
  • Resultado: Fatura imediata de $10. Sem interrupção de serviço, e o ciclo de cobrança permanece o mesmo.

Isso mantém os clientes satisfeitos, fornecendo acesso instantâneo a novos recursos, enquanto garante uma cobrança justa.

Cenário 2: Downgrade no Meio do Ciclo (Crédito Aplicado)

Um cliente faz downgrade de um Plano Pro de $30/mês para um Plano Básico de $10/mês na metade do ciclo.

  • Credita ~\(15 pelo tempo não utilizado do Plano Pro e cobra ~\)5 pelo tempo restante do Plano Básico.
  • Resultado: Crédito de $10 armazenado no saldo do cliente, aplicado na próxima fatura.

Ideal para reter clientes que precisam de flexibilidade sem pagar a mais.

Solução de Problemas

Problema 1: API Retorna 404 Not Found

  • Causa: subscription_id ou plan_id incorreto.
  • Solução: Verifique novamente os IDs no 4Geeks Console. Garanta a consistência entre o modo de teste/produção.

Problema 2: Falha na Fatura de Upgrade (402 Payment Required)

  • Causa: O cartão do cliente recusa a cobrança proporcional.
  • Solução: Verifique o status da latest_invoice. Peça ao cliente para atualizar o método de pagamento por meio do link do portal do cliente.

Problema 3: Nenhuma Cobrança Visível após Downgrade

  • Causa: Downgrades criam créditos, não reembolsos imediatos.
  • Solução: Verifique o saldo do cliente na API ou no 4Geeks Console. Os créditos são aplicados automaticamente a contas futuras.

Conclusão

Com o 4Geeks Payments, lidar com mudanças de assinatura é contínuo e automatizado, reduzindo a carga administrativa e melhorando a satisfação do cliente. Implemente estas etapas para gerenciar upgrades e downgrades com eficiência. Para automação mais avançada, explore a integração com os 4Geeks AI Agents.

Recursos Adicionais