Ir para o conteúdo

Como Pausar ou Cancelar Assinaturas de Clientes via API no 4Geeks Payments

🤖 Explicar com IA

Gerenciar o ciclo de vida do cliente de forma eficiente é crucial para empresas modernas de SaaS e baseadas em assinaturas. Embora o 4Geeks Console forneça uma interface intuitiva para gestão manual, a escalabilidade das operações muitas vezes exige controle programático. O 4Geeks Payments oferece uma API robusta que permite aos desenvolvedores pausar ou cancelar assinaturas automaticamente, integrando-se perfeitamente aos seus próprios portais de clientes ou ferramentas administrativas internas.

Este artigo orienta você pelas etapas técnicas para pausar ou cancelar assinaturas de clientes usando a API do 4Geeks Payments, garantindo que sua lógica de faturamento permaneça precisa e a experiência do seu cliente seja fluida.

Pré-requisitos

Antes de interagir com a API, certifique-se de ter o seguinte:

  • Conta Ativa no 4Geeks Payments: Você deve ter o módulo 4Geeks Payments habilitado em sua conta.
  • Credenciais de API: Sua API Key e Secret são necessários para a autenticação. Eles podem ser gerados na seção Developers do 4Geeks Console.
  • ID da Assinatura: O identificador exclusivo (subscription_id) da assinatura específica do cliente que você deseja modificar.
  • Cliente de API: Uma ferramenta como Postman, cURL ou sua linguagem de programação de preferência (Python, Node.js, etc.) para enviar solicitações HTTP.

Instruções Passo a Passo

Passo 1: Autenticar sua Solicitação

Todas as solicitações de API para o 4Geeks Payments devem ser autenticadas para garantir a segurança. Você se autenticará usando um Bearer Token no cabeçalho da sua solicitação.

  1. Localize suas credenciais de API na aba Settings > Developers do painel.
  2. Inclua o seguinte cabeçalho em sua solicitação HTTP: Authorization: Bearer SUA_CHAVE_API

Passo 2: Recuperar o ID da Assinatura

Para modificar uma assinatura, primeiro você precisa identificá-la. Se você ainda não possui o ID armazenado em seu banco de dados, pode recuperá-lo listando as assinaturas de um cliente específico.

  1. Envie uma solicitação GET para o endpoint: https://api.4geeks.io/v1/subscriptions.
  2. Filtre pelo e-mail do cliente ou pelo ID exclusivo do cliente.
  3. Na resposta JSON, copie a string id (ex: sub_1a2b3c4d5e).

Passo 3: Pausar uma Assinatura

A pausa é ideal para suspensões temporárias em que você espera que o cliente retorne. Ela interrompe o ciclo de faturamento sem excluir o objeto de assinatura, permitindo uma reativação fácil.

  1. Endpoint: Prepare uma solicitação POST para: https://api.4geeks.io/v1/subscriptions/{subscription_id}/pause
  2. Parâmetros do Corpo (Opcional): Você pode especificar um parâmetro resume_at (Unix timestamp) se desejar que a assinatura seja reativada automaticamente em uma data específica. 
    {
  "resume_at": 1735689600
}
  3. Executar: Envie a solicitação.
  4. Verificação: A API retornará o objeto de assinatura com o status paused. Certifique-se de que seu sistema interno atualize o nível de acesso do usuário conforme necessário.

Passo 4: Cancelar uma Assinatura

O cancelamento encerra permanentemente o ciclo de faturamento. Dependendo da sua configuração, isso pode acontecer imediatamente ou ao final do período de faturamento atual.

  1. Endpoint: Prepare uma solicitação DELETE (ou POST, dependendo da configuração específica) para: https://api.4geeks.io/v1/subscriptions/{subscription_id}/cancel
  2. Parâmetros do Corpo:
    • cancel_at_period_end (booleano): Defina como true para permitir que o cliente termine o mês que já pagou. Defina como false para revogação imediata. 
      {
  "cancel_at_period_end": true
}
  3. Executar: Envie a solicitação.
  4. Verificação: A API retorna o objeto com o status canceled (ou active com um timestamp cancel_at se você optou por cancelar ao final do período).

Casos de Uso Comuns

Cenário 1: “Pausa Sazonal”

Situação: Você gerencia uma plataforma de educação usando o 4Geeks Payments e um aluno deseja congelar sua conta durante as férias de verão em vez de cancelar totalmente. Aplicação: Seu portal do aluno dispara o endpoint de Pausa (/pause) com uma data resume_at definida para 1º de setembro. Resultado: O faturamento para imediatamente. Em 1º de setembro, a API reativa automaticamente a assinatura e tenta realizar o pagamento, retendo o cliente sem intervenção manual.

Cenário 2: Gestão Automatizada de Evasão (Churn)

Situação: Um cliente clica em “Cancelar Conta” no painel do seu SaaS. Aplicação: Seu backend dispara o endpoint de Cancelamento (/cancel) com cancel_at_period_end: true. Resultado: O cliente mantém o acesso até que seu prazo pago expire. O 4Geeks Payments garante que nenhuma fatura futura seja gerada e o status da assinatura eventualmente transita para canceled automaticamente, mantendo seus registros financeiros precisos.

Solução de Problemas

Problema 1: Erro 401 Unauthorized

  • Causa: Sua API Key está ausente, incorreta ou expirou.
  • Solução: Verifique o cabeçalho Authorization. Gere novas chaves no 4Geeks Console, se necessário.

Problema 2: 404 Not Found

  • Causa: O subscription_id fornecido não existe ou pertence a um ambiente diferente (ex: Sandbox vs. Produção).
  • Solução: Verifique se o ID corresponde ao ambiente que você está consultando. Certifique-se de não estar tentando acessar um ID Live no ambiente Sandbox.

Problema 3: Conflito de Status de Assinatura (409)

  • Causa: Você está tentando pausar uma assinatura que já está cancelada, ou cancelar uma assinatura que já está pausada sem reativá-la primeiro.
  • Solução: Sempre verifique o campo status do objeto de assinatura via uma solicitação GET antes de tentar uma mudança de estado para garantir que a ação seja válida.

Conclusão

Automatizar a gestão de assinaturas via API capacita sua empresa a lidar com bases de clientes crescentes com precisão. Ao integrar a lógica de pausa e cancelamento diretamente em suas aplicações, você reduz a carga de trabalho da equipe de suporte e oferece uma experiência mais fluida para seus usuários.

Para configurações mais avançadas, como lidar com o rateio (proration) durante cancelamentos ou configurar webhooks para mudanças de status, explore a Documentação para Desenvolvedores no 4Geeks Console.