> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/planes-y-suscripciones/terminos-de-relevancia.md). # Términos de relevancia La funcionalidad de **Planes y suscripciones** permite a un comercio configurar cobros recurrentes, vincular clientes a un plan mediante un medio de pago tokenizado y ejecutar cobros automáticos según las condiciones definidas. Antes de integrar estos endpoints, es importante entender los conceptos principales, cómo se relacionan entre sí y qué reglas influyen en el comportamiento de la solución. ### ¿Qué son los planes y las suscripciones? Esta solución se compone de tres entidades principales: **Plan**, **Suscripción** y **Cobro**. * Un **Plan** define las condiciones generales de un cobro recurrente, como el monto, la moneda, la frecuencia, el número total de cobros y las políticas aplicables en caso de fallo. Un mismo plan puede ser utilizado por múltiples clientes. * Una **Suscripción** representa la relación entre un cliente y un plan. Se crea cuando el cliente vincula su medio de pago y acepta las condiciones del cobro recurrente. Desde ese momento, la suscripción conserva la información necesaria para operar y los términos aceptados en el momento de la vinculación. * Un **Cobro** corresponde a la ejecución individual de un cargo dentro de una suscripción. Cada cobro tiene su propio estado, referencia y número de intento. #### Conceptos clave * **Plan**\ Es la configuración base de un cobro recurrente. Define las condiciones comunes para todos los clientes que se suscriban. * **Suscripción**\ Es el vínculo entre un cliente y un plan. Contiene la información del cliente, el medio de pago tokenizado, los términos aceptados y el estado del ciclo de cobro. * **Cobro recurrente**\ Es la ejecución periódica de un cargo sobre una suscripción activa, de acuerdo con las condiciones previamente definidas. * **Vinculación de medio de pago**\ Es el proceso mediante el cual un cliente registra un medio de pago para ser utilizado en cobros futuros. * **Tokenización**\ Es el mecanismo que reemplaza la información sensible del medio de pago por un token seguro provisto por el proveedor de pagos. *** ### Flujo general De forma general, el flujo funciona así: {% stepper %} {% step %} #### Crear el plan El comercio crea un plan con las condiciones del cobro recurrente. {% endstep %} {% step %} #### Vincular al cliente El cliente se vincula a ese plan. {% endstep %} {% step %} #### Tokenizar el medio de pago El proveedor correspondiente tokeniza el medio de pago. {% endstep %} {% step %} #### Crear la suscripción Se crea una suscripción con los términos vigentes al momento de la aceptación. {% endstep %} {% step %} #### Ejecutar los cobros El sistema ejecuta los cobros automáticos según la frecuencia configurada. {% endstep %} {% step %} #### Reintentar cobros fallidos Si un cobro falla, se aplican las políticas de reintento definidas. {% endstep %} {% step %} #### Registrar el cobro Cada ejecución genera un registro de cobro independiente. {% endstep %} {% endstepper %} *** ### Reglas del modelo


Un plan no representa a un cliente	Los planes definen condiciones generales. La relación con un cliente específico existe únicamente a través de una suscripción.
La suscripción conserva los términos aceptados	Cuando un cliente se suscribe, la suscripción almacena una copia de las condiciones vigentes en ese momento. Si el plan cambia más adelante, esos cambios no modifican automáticamente las condiciones ya aceptadas por suscripciones existentes.
Cada cobro es una ejecución independiente	Una suscripción puede generar múltiples cobros a lo largo del tiempo. Cada uno conserva su propio estado, referencia e historial de intentos.
La operación real ocurre sobre la suscripción	Aunque el plan define las reglas generales, la ejecución de cobros depende de la información operativa de cada suscripción, como su estado, sus términos y su próxima fecha de cobro.

*** ### Variables dinámicas de descripción La descripción de un cobro puede construirse usando variables dinámicas que se resuelven en el momento real de la ejecución. Esto permite mostrar información más clara al cliente y mantener consistencia entre la ejecución del cobro y su descripción. **Variables disponibles:** * `{{charge_number}}`: número del cobro dentro del ciclo * `{{month}}`: nombre del mes de ejecución * `{{week}}`: rango semanal asociado a la fecha de ejecución * `{{biweek}}`: rango quincenal asociado a la fecha de ejecución * `{{day}}`: fecha legible de ejecución Estas variables deben resolverse con base en la fecha efectiva del cobro, no solo en la fecha programada, ya que un cobro puede ejecutarse posteriormente debido a reintentos u otras condiciones operativas. **Ejemplo:** Si un plan define la descripción: `Cobro {{charge_number}} - {{month}}` y el sistema ejecuta el tercer cobro en agosto, la descripción generada sería: `Cobro 3 - Agosto` También es posible usar formatos como: * `Suscripción {{charge_number}} - {{day}}` * `Cobro correspondiente a {{week}}` * `Pago recurrente {{charge_number}} - {{biweek}}` *** ### Estados Plan y Suscripción manejan estados separados. El estado del Plan define si sigue abierto a nuevos suscriptores; el de la Suscripción, en qué punto del ciclo de cobro está cada cliente. Los cambios en el Plan no alteran las suscripciones activas. #### Planes

Estado	Significado
`ACTIVE`	Disponible para nuevas suscripciones.
`PAUSED`	No acepta nuevas suscripciones temporalmente. Las suscripciones existentes siguen cobrando normal.
`CANCELED`	Retirado permanentemente. No acepta nuevas suscripciones. Las suscripciones existentes no se ven afectadas, siguen cobrando con sus `terms` congelados hasta que se cancelen individualmente.

#### Suscripción

Estado	Significado
`PENDING`	Creada por API o diligenciada en la web, esperando que el cliente vincule su medio de pago.
`ACTIVE`	Medio de pago vinculado y operando. Puede tener cobros individuales fallidos en curso sin dejar de estar activa.
`OVERDUE`	Se agotaron los reintentos (`max_retries`) y `status_after_retry = OVERDUE`.
`CANCELED`	Reintentos agotados con `status_after_retry = CANCELED`, o cancelación manual (API o vista del cliente).
`FULFILLED`	Se alcanzó el número de cobros permitidos (`charges_executed` alcanzó `total_charges`).

*** ### Consideraciones importantes Antes de implementar esta funcionalidad, es importante tener en cuenta algunos comportamientos y límites del modelo. **Límite de cobros por plan** Cada plan puede definir un máximo de cobros dentro del ciclo recurrente. Este valor se establece al crear el plan y determina cuántas ejecuciones puede generar cada suscripción asociada. El máximo permitido es de 12 cobros. Al alcanzar este límite, se debe crear una nueva suscripción o solicitar la actualización del medio de pago. **Uso de `trial_days`** El campo `trial_days` permite definir un período de gracia antes del primer cobro. Durante ese tiempo, la suscripción puede quedar activa sin generar un cargo inmediato, según la configuración del plan. **Reintentos de cobro** Cuando un cobro falla, el sistema puede aplicar una política de reintentos definida en el plan. Esta configuración permite establecer cuántos intentos adicionales se realizarán y cada cuánto tiempo. Si se alcanza el número máximo de reintentos sin éxito, la suscripción puede pasar al estado configurado para ese caso. Esto permite definir de antemano el comportamiento esperado del ciclo de cobro. **Vinculación mediante enlace seguro** La captura y tokenización del medio de pago no ocurre directamente en la integración del comercio. En su lugar, la plataforma genera un enlace de vinculación que el cliente debe completar para registrar su medio de pago de forma segura. **Creación de suscripciones por API** Cuando una suscripción se crea por API, la respuesta incluye un enlace de vinculación para completar el registro del medio de pago. La suscripción solo podrá operar normalmente una vez este paso haya sido completado. **Cambios en un plan y suscripciones existentes** Las actualizaciones realizadas sobre un plan no modifican automáticamente las condiciones ya aceptadas por suscripciones existentes. Cada suscripción conserva los términos vigentes al momento de su creación.