Saltar a contenido

Cómo pausar o cancelar suscripciones de clientes a través de la API en 4Geeks Payments

🤖 Explicar con IA

Gestionar el ciclo de vida del cliente de forma eficiente es crucial para los negocios modernos de SaaS y basados en suscripciones. Aunque la 4Geeks Console proporciona una interfaz fácil de usar para la gestión manual, el escalado de las operaciones a menudo requiere un control programático. 4Geeks Payments ofrece una API robusta que permite a los desarrolladores pausar o cancelar suscripciones automáticamente, integrándose perfectamente con sus propios portales de clientes o herramientas administrativas internas.

Este artículo lo guía a través de los pasos técnicos para pausar o cancelar suscripciones de clientes utilizando la API de 4Geeks Payments, asegurando que su lógica de facturación siga siendo precisa y su experiencia de cliente fluida.

Requisitos previos

Antes de interactuar con la API, asegúrese de tener lo siguiente:

  • Cuenta activa de 4Geeks Payments: Debe tener el módulo 4Geeks Payments habilitado en su cuenta.
  • Credenciales de API: Su API Key y Secret son necesarios para la autenticación. Estos pueden generarse en la sección Developers de la 4Geeks Console.
  • ID de suscripción: El identificador único (subscription_id) de la suscripción específica del cliente que desea modificar.
  • Cliente de API: Una herramienta como Postman, cURL, o su lenguaje de programación preferido (Python, Node.js, etc.) para enviar solicitudes HTTP.

Instrucciones paso a paso

Paso 1: Autenticar su solicitud

Todas las solicitudes de API a 4Geeks Payments deben estar autenticadas para garantizar la seguridad. Se autenticará utilizando un Bearer Token en el encabezado (header) de su solicitud.

  1. Localice sus credenciales de API en la pestaña Settings > Developers del panel.
  2. Incluya el siguiente encabezado en su solicitud HTTP: Authorization: Bearer TU_CLAVE_API

Paso 2: Obtener el ID de la suscripción

Para modificar una suscripción, primero debe identificarla. Si aún no tiene el ID guardado en su base de datos, puede obtenerlo listando las suscripciones de un cliente específico.

  1. Envíe una solicitud GET al endpoint: https://api.4geeks.io/v1/subscriptions.
  2. Filtre por el correo electrónico del cliente o su ID de cliente único.
  3. De la respuesta JSON, copie la cadena id (por ejemplo, sub_1a2b3c4d5e).

Paso 3: Pausar una suscripción

La pausa es ideal para suspensiones temporales en las que espera que el cliente regrese. Detiene el ciclo de facturación sin eliminar el objeto de suscripción, lo que permite una reactivación sencilla.

  1. Endpoint: Prepare una solicitud POST a: https://api.4geeks.io/v1/subscriptions/{subscription_id}/pause
  2. Parámetros del cuerpo (Opcional): Puede especificar un parámetro resume_at (marca de tiempo Unix) si desea que la suscripción se reactive automáticamente en una fecha específica. 
    {
  "resume_at": 1735689600
}
  3. Ejecutar: Envíe la solicitud.
  4. Verificación: La API devolverá el objeto de suscripción con un estado de paused. Asegúrese de que su sistema interno actualice el nivel de acceso del usuario según corresponda.

Paso 4: Cancelar una suscripción

La cancelación finaliza permanentemente el ciclo de facturación. Dependiendo de su configuración, esto puede suceder de inmediato o al final del periodo de facturación actual.

  1. Endpoint: Prepare una solicitud DELETE (o POST, según la configuración específica) a: https://api.4geeks.io/v1/subscriptions/{subscription_id}/cancel
  2. Parámetros del cuerpo:
    • cancel_at_period_end (booleano): Establezca en true para permitir que el cliente termine el mes que ya pagó. Establezca en false para una revocación inmediata. 
      {
  "cancel_at_period_end": true
}
  3. Ejecutar: Envíe la solicitud.
  4. Verificación: La API devuelve el objeto con un estado de canceled (o active con una marca de tiempo cancel_at si eligió cancelar al final del periodo).

Casos de uso comunes

Escenario 1: La “Pausa Estacional”

Situación: Usted dirige una plataforma de educación que utiliza 4Geeks Payments, y un estudiante desea congelar su cuenta durante las vacaciones de verano en lugar de cancelarla por completo. Aplicación: Su portal de estudiantes activa el endpoint de Pausa (/pause) con una fecha resume_at establecida para el 1 de septiembre. Resultado: La facturación se detiene inmediatamente. El 1 de septiembre, la API reactiva automáticamente la suscripción e intenta realizar el pago, reteniendo al cliente sin intervención manual.

Escenario 2: Gestión de cancelaciones automatizada

Situación: Un cliente hace clic en “Cancelar cuenta” en su panel de SaaS. Aplicación: Su backend activa el endpoint de Cancelar (/cancel) con cancel_at_period_end: true. Resultado: El cliente mantiene el acceso hasta que expire su periodo pagado. 4Geeks Payments garantiza que no se generen más facturas, y el estado de la suscripción finalmente pasa a canceled automáticamente, manteniendo la precisión de sus registros financieros.

Solución de problemas

Problema 1: Error 401 Unauthorized

  • Causa: Su clave de API falta, es incorrecta o ha caducado.
  • Solución: Verifique el encabezado Authorization. Regenere sus claves en la 4Geeks Console si es necesario.

Problema 2: Error 404 Not Found

  • Causa: El subscription_id proporcionado no existe o pertenece a un entorno diferente (por ejemplo, Sandbox frente a Producción).
  • Solución: Verifique que el ID coincida con el entorno en el que está consultando. Asegúrese de no estar intentando acceder a un ID de Producción en el entorno Sandbox.

Problema 3: Conflicto de estado de suscripción (409)

  • Causa: Está intentando pausar una suscripción que ya está cancelada, o cancelar una suscripción que ya está pausada sin reactivarla primero.
  • Solución: Siempre verifique el campo status del objeto de suscripción mediante una solicitud GET antes de intentar un cambio de estado para asegurarse de que la acción sea válida.

Conclusión

Automatizar la gestión de suscripciones a través de la API permite a su negocio manejar bases de clientes en crecimiento con precisión. Al integrar la lógica de pausa y cancelación directamente en sus aplicaciones, reduce la carga de trabajo del personal de soporte y ofrece una experiencia más fluida a sus usuarios.

Para configuraciones más avanzadas, como el manejo de prorrateos durante las cancelaciones o la configuración de webhooks para cambios de estado, explore la Documentación para Desarrolladores en la 4Geeks Console.