Suscripciones
En DEUNA, las Suscripciones son una relación entre un cliente y un plan de producto o servicio.
La API de Suscripciones gestiona las suscripciones de usuarios a planes ofrecidos por tu sistema.
Usa esta API para controlar los estados de las suscripciones y planes. Garantiza que el proceso de facturación, activación, cancelación, y expiración se realice correctamente.
La API de Sucripciones incluye un mecanismo de reintentos inteligentes para manejar fallos temporales en la comunicación con procesadores de pago.
Las suscripciones se constituyen de la siguiente forma:
Atributo | Descripción | Contiene |
---|---|---|
Plan | Producto o servicio que se ofrece a los clientes. | - Un código único - Nombre - Moneda - Descripción - Precio - Intervalo de facturación - Estado: - active - pending |
Suscripción | Relación entre un cliente y un plan | - ID único - Estado - active - pending - cancelled - expired - Fechas - Creación - Activación - Cancelación - Expiración |
Ciclo de facturación | Periodo de tiempo en el que se cobra un plan. | - DAILY: Diariamente - WEEKLY: Semanalmente - BIWEEKLY: Cada dos semanas - THIRTY_DAYS: Cada 30 días - SIXTY_DAYS: Cada 60 días - NINETY_DAYS: Cada 90 días - MONTHLY: Mensualmente - BIMESTRIAL: Cada 2 meses - QUARTERLY: Cada 3 meses - ANNUAL: Anualmente - BIENNIAL Cada 2 años - TRIANNUAL: 3 veces al año - BIANNUAL: 2 veces al año |
Estados de suscripción
Los estados de suscripción son:
pending
: La suscripción ha sido creada en nuestro sistema, pero el cobro aún no ha sido realizado. Este estado se mantiene hasta que el sistema confirme que el cobro ha sido realizado o falle.active
: La suscripción está activa cuando el proceso de pago ha sido completado con éxito, confirmando la validez de la suscripción. Este estado se alcanza cuando el sistema recibe una respuesta exitosa y la suscripción ha sido validada.canceled
: La suscripción ha sido cancelada, ya sea por el cliente o por el comercio. Este estado es el resultado de una acción explícita del cliente o del sistema para terminar la suscripción antes de su expiración.expired
: La suscripción ha terminado, ya sea porque ha llegado a su fecha de expiración o ha sido terminada manualmente por el cliente o el comercio. Este estado se activa cuando la suscripción llega a su fecha de expiración o se cancela por alguna de las partes.
Estados de plan
Los estados de plan son:
active
: El plan está activo y disponible para nuevas suscripciones.Pending
: El plan se ha intentado crear pero por falla interna del sistema, este no se completa.
Administrar suscripciones
Administra tus suscripciones mediante la API de Suscripciones.
Usa esta API para controlar los estados de las suscripciones y planes. Garantiza que el proceso de facturación, activación, cancelación, y expiración se realice correctamente.
Crear una suscripción
Usa el endpoint Crear una suscripción para crear una suscripción.
Si recibes un error por timeout al crear una suscripción, recupera el
suscription_ID
dentro del detalle de la respuesta.
Cancelar una suscripción
Cambia el estado a cancelado
y se puede especificar:
- Cancelación al final del ciclo de facturación actual.
- Cancelación al final del ciclo de renovación.
- Una suscripción mensual renovada por 1 año se cancela al completar ese tiempo.
term_end
indica el fin del ciclo actual y genera un reembolso.bill_date
indica el inicio del proximo ciclo (24 horas de diferencia con term_end) y genera un reembolso.
Terminar una suscripción
Cambia inmediatamente el estado a expirado
. Esto permite:
- Realizar reembolsos (totales o parciales).
- No realizar reembolsos, cobrando solo por el tiempo en que la suscripción estuvo activa.
Usa el endpoint Obtener lista de suscripciones para recibir una lista de todas las sucripciones de un usuario.
El parámetro
subscription_end_date
representa la fecha en la que se realiza el cobro para una suscripción.
Facturas vencidas
Si después de 24 horas el cobro no se realiza:
- La factura pasa al estado
past_due
. - Notificaremos al comercio sobre los fallos y el cambio de estado.
Actualización de tarjeta
Si el cliente actualiza su tarjeta, puedes:
- Llamar a Actualizar suscripción para actualizar la suscripción.
- Reintentar el cobro de la factura vencida.
Reintentos
El mecanismo de reintentos inteligentes está diseñado para manejar fallos temporales durante la creación o validación de las suscripciones.
Este mecanismo asegura que los procesos de pago y activación se completen sin necesidad de intervención manual, incluso en caso de fallos intermitentes.
Características clave:
- Reintento automático: Si el cobro o la activación de la suscripción falla, el sistema intenta realizar el proceso de nuevo después de un breve retraso.
- Control de fallos: El sistema establece un número máximo de intentos para evitar bucles infinitos de reintento y garantiza que el sistema no se vea sobrecargado.
Secuencia de Reintento Inteligente
-
Fallo Inicial: En caso de un error temporal, como un problema con el servicio de pago, el sistema reintenta automáticamente en un intervalo predeterminado.
-
Reintentos: Cada reintento aumenta progresivamente el tiempo de espera entre intentos, basándose en una política de "backoff exponencial" para evitar sobrecargar el sistema.
-
Límite de Reintentos: Si el número de reintentos alcanza un máximo configurable (por ejemplo, 6 intentos), el sistema marcará la suscripción como fallida y notificará al usuario o administrador.
-
Notificación: Después de varios intentos fallidos, el sistema puede enviar notificaciones al cliente o al administrador, informando sobre el estado de la suscripción y los fallos ocurridos.
Reintentos Escalonados
Intento | Tiempo de Espera |
---|---|
Primer Intento | - |
Segundo Intento | 5 minutos |
Tercer Intento | 60 minutos |
Cuarto Intento | 5 horas |
Quinto Intento | 12 horas |
Sexto Intento | 24 horas |
Updated 8 days ago