Notas de Crédito

Una nota de crédito (devolución) es una transacción con cantidad negativa que revierte una venta previa. Llega por el mismo canal de ingesta que las ventas y, según el SKU, el sistema revierte la suscripción, un segmento de la línea de tiempo del plan o una compra de acceso de cabina.

Cómo se identifica

No existe un tipo de transacción separado: una nota de crédito se reconoce porque la cantidad total (retailQuantity) del ítem es menor que cero sobre un SKU mapeado a un plan o a un acceso de cabina.

Entra por el mismo endpoint que las ventas:

POST /api/hola-doc/transactions/ingest

Por eso conviene leer primero Integraciones y API, que describe el formato de la transacción y los rechazos persistidos.

Flujo de procesamiento

graph TD
    A[Ingesta de transacción] --> B{¿Cantidad negativa?}
    B -->|No| V[Procesar como venta]
    B -->|Sí| C{¿Existe suscripción o compra activa?}
    C -->|No| R[Rechazo persistido]
    C -->|Sí| D{¿El plan coincide?}
    D -->|No| R
    D -->|Sí| E{¿Meses no consumidos suficientes?}
    E -->|No| R
    E -->|Sí| F{¿Reembolso total o parcial?}
    F -->|Total| G[Cancelar suscripción / eliminar compra]
    F -->|Parcial| H[Reducir vigencia / recortar segmentos]
    G --> P[Registrar pago negativo]
    H --> P

Tipos de impacto

Caso	Comportamiento
Plan activo, reembolso parcial	Reduce la vigencia (`ValidUntil`) por la cantidad de meses devueltos y elimina o recorta los segmentos futuros de la línea de tiempo.
Plan activo, reembolso total	La suscripción pasa a estado CANCELLED y se limpia la línea de tiempo (segmentos activos y programados).
Plan programado (a futuro)	Recorta o elimina el segmento programado correspondiente y registra el cambio en la bitácora del cambio de plan.
Acceso de cabina	Elimina compras de cabina no consumidas (las más recientes primero), separando extras de cuenta de compras de no suscriptor.

Límites y reglas

Las notas de crédito están acotadas por reglas de negocio. Si una nota no cumple una regla, se rechaza y el rechazo queda persistido para consulta operativa.

Regla	Detalle
Debe existir algo que revertir	Tiene que haber una suscripción o compra activa asociada al cliente.
El plan debe coincidir	El plan de la nota debe corresponder al plan activo o a un segmento programado de la suscripción.
No exceder lo no consumido	No se pueden devolver más meses de los no consumidos. La respuesta incluye `maxRefundableQty` con el máximo permitido.
Ciclo con uso de cabina	Un ciclo en el que ya hubo uso de cabina no es reembolsable: solo se devuelven meses futuros (más el ciclo actual únicamente si no hubo uso).
Suscripción suspendida	Solo se aceptan notas de crédito; los pagos positivos sobre una suscripción suspendida se rechazan.
Suscripción expirada	Una suscripción con vigencia agotada (`SUSPENDED_EXPIRED`) tiene 0 meses reembolsables.
Grupo no activado	El reembolso total de un plan grupal aún no activado elimina a todos los miembros y desactiva la cuenta.
Grupo activado	El reembolso total de un plan grupal ya activado conserva la cuenta y los miembros.
Tamaño de lote	La ingesta admite un máximo de 10,000 transacciones por batch (ver Integraciones y API).

Rechazos

Cuando una nota de crédito no cumple las reglas, se persiste un rechazo con uno de estos códigos. Estos rechazos aparecen en la sección “Rechazos persistidos” de Integraciones y API.

Código	Motivo
`NO_ACTIVE_SUBSCRIPTION_FOR_REFUND`	Nota de crédito sin suscripción activa que revertir.
`INSUFFICIENT_UNCONSUMED_MONTHS`	No hay suficientes meses sin consumir para el reembolso (incluye `maxRefundableQty`).
`PLAN_MISMATCH_FOR_REFUND`	El plan de la nota de crédito no coincide con el de la suscripción.
`SUBSCRIPTION_SUSPENDED`	No se permiten pagos positivos sobre una suscripción suspendida.

Efecto en comisiones

Importante: las entradas de comisión no se revierten automáticamente cuando una nota de crédito cancela o reduce una suscripción. Permanecen en el período de liquidación actual y requieren revisión manual antes de liquidar. Consulte Planes y Comisiones para el proceso de liquidación.

Casos esperados en pruebas

Al validar el comportamiento de devoluciones, se esperan estos resultados (ver Configuración y pruebas):

Se aceptan devoluciones parciales.
Se aceptan devoluciones totales.
Se rechaza devolver más de lo comprado.
Se rechaza devolver un producto ya consumido.
El reembolso total de un plan grupal no activado elimina a todos los miembros y desactiva la cuenta.
El reembolso total de un plan grupal activado conserva la cuenta y los miembros.
Las notas de crédito eliminan las compras de acceso de cabina no consumidas.