Liquidación de Comisiones y Costos de Proveedor

Cada transacción procesada genera una entrada de comisión (y, si aplica, una entrada de costo de proveedor). Estas entradas se acumulan en un período y luego se liquidan. Esta página describe cómo se calculan, cómo funciona el estado pendiente → liquidada y por qué un período puede liquidarse más de una vez. El flujo de uso desde la pantalla está en Planes y comisiones.

Entradas de comisión

Una entrada de comisión guarda el monto (con signo), el período (YYYY-MM, derivado de la fecha de pago), el vendedor (la API key de origen) y su estado:

Estado	Significado
`pending`	Comisión generada, aún no liquidada.
`settled`	Comisión liquidada (transición de un solo sentido).

Cómo se calcula

Comisiones de suscripción: se calculan como un porcentaje del monto del pago. La tasa proviene de la configuración del socio (la API key); por defecto 20 %.
Comisiones de servicios de clínica: usan el valor resuelto del catálogo, que puede ser un monto fijo o un porcentaje del importe cobrado. La resolución multinivel se describe en Precios multinivel.

Costos de proveedor

Además de la comisión, una transacción puede generar un costo hacia el proveedor del plan:

El costo se calcula como costo unitario × cantidad del pago.
Si el pago es negativo (devolución), el costo se niega en consecuencia.

Existe un modelo de descuentos por volumen por proveedor (tramos por cantidad de usuarios), pero no se aplica de forma activa en esta versión; se reserva para uso futuro.

Devoluciones

Las notas de crédito no revierten las entradas ya existentes. En su lugar:

Una devolución genera una nueva entrada de comisión negativa (y un costo negativo) en su período.
Las entradas ya liquidadas no se deshacen automáticamente: requieren revisión manual antes de liquidar el período afectado.

Ver Notas de crédito.

Liquidación

graph TD
    A[Transacción procesada] --> B[Entrada pending]
    B --> C{Liquidar período + alcance}
    C --> D[Solo las entradas pending<br/>pasan a settled]
    D --> E[Se crea un registro de liquidación<br/>con totales y notas]
    F[Entradas pending tardías<br/>del mismo período] --> C

La liquidación es de un solo sentido: solo las entradas pending del período y alcance elegidos pasan a settled. El alcance puede ser:

Alcance	Qué liquida
`all`	Todas las comisiones y costos pendientes del período.
`seller`	Las comisiones de un vendedor (API key) específico.
`provider`	Los costos de un proveedor específico.

El registro de liquidación guarda el período, el alcance, el total de comisión, el total de costo de proveedor, la fecha y notas.

Importante: el sistema no impide volver a liquidar un período. Si tras liquidar llegan transacciones tardías que generan nuevas entradas pending, ese mismo período y alcance pueden liquidarse otra vez; solo se incluyen las entradas que aún están pending. Si no hay nada pendiente, la liquidación se rechaza (no hace nada).

Casos esperados en pruebas

Una comisión de suscripción equivale al porcentaje configurado del pago (20 % por defecto).
Una devolución crea una entrada de comisión negativa, no revierte la original.
Liquidar un período pasa a settled solo las entradas pendientes.
Volver a liquidar un período sin nuevas entradas pendientes no produce cambios.
Una transacción tardía permite liquidar de nuevo el mismo período por su monto pendiente.