Calculadora de Pago de Comisiones de Ventas

--- name: sales-commission-payout-calculator description: Calcula los pagos de comisiones de ventas para un período a partir de tu plan de compensación y un CSV de acuerdos - crédito de cuota por tipo de acuerdo, acuerdos divididos, tasas escalonadas con aceleradores (marginal o fijo), límites de crédito y pago, SPIFFs, recuperaciones por cancelaciones anticipadas, pago al reservar o al cobrar, y anticipos. Retiene acuerdos con divisiones incorrectas, representantes desconocidos o descuentos no aprobados y redacta estados de cuenta para representantes. Incluye una calculadora estándar de Python sin conexión. --- # Calculadora de Pago de Comisiones de Ventas Ayudas a operaciones de ventas, finanzas y fundadores a pagar comisiones correctas a la primera. Las ejecuciones de comisiones fallan de maneras predecibles: un acuerdo dividido suma hasta 90%, un acelerador se aplica a todo el trimestre en lugar del crédito por encima del umbral, una renovación se acredita a valor completo, un acuerdo con un descuento no aprobado del 30% se cuela, un cliente cancela después de 55 días y nadie recupera la comisión, o el mismo acuerdo aparece dos veces en la exportación. Conviertes el plan y la exportación de acuerdos en un pago por representante que cualquiera pueda recalcular, con cada acuerdo retenido y decisión subjetiva listada. Aplicas el plan que el usuario te da. No decides lo que el plan debería decir, si una recuperación o un saldo negativo pueden deducirse legalmente del pago, o cómo se gravan las comisiones; dilo y señala el plan de compensación firmado, RR.HH./nómina y la ley laboral local. ## Archivos en esta habilidad - `scripts/commission_calc.py` - lee un JSON de plan (período, niveles como fracciones de cuota, método marginal o fijo, límite de crédito, pago máximo, crédito por tipo de acuerdo, límite de descuento, SPIFFs, ventana de recuperación, pago al reservar o al cobrar, representantes con cuota y anticipo opcional) y un CSV de acuerdos (id de acuerdo, fecha de cierre, cuenta, división del propietario, tipo, monto, descuento, facturación, estado, fecha de cancelación, comisión ya pagada, aprobación, cobro); calcula crédito, porciones de nivel por acuerdo en orden de cierre, límites, SPIFFs, recuperaciones, diferimientos y complemento o recuperación de anticipo con aritmética Decimal; reporta hallazgos CM01-CM11, una tabla de pagos, líneas de acuerdos por representante y acuerdos retenidos/excluidos (solo biblioteca estándar de Python 3.8+) - `references/plan-mechanics.md` - niveles, marginal vs fijo, límites, reglas de crédito, divisiones, SPIFFs, recuperaciones, anticipos, tiempos, con números trabajados - `references/checks-and-codes.md` - cada código de hallazgo, su severidad y qué hacer al respecto, y los campos de entrada - `templates/commission-statement.md` - el estado de cuenta que cada representante recibe y firma - `examples/comp-plan.json` - un plan de AE para octubre de 2026: 4 niveles (5/8/12/15%), límite de crédito 200%, pago máximo 8,000, renovaciones al 50% de crédito, límite de descuento 20%, SPIFF de prepago anual, recuperación a 90 días, tres representantes, uno con anticipo recuperable - `examples/deals.csv` - 15 filas: acuerdos normales, una división 60/40, una renovación, un gran descuento aprobado y uno no aprobado, una división que suma 90%, un acuerdo para un representante desconocido con separador de miles, dos cancelaciones (dentro y fuera de la ventana de recuperación), un acuerdo de septiembre y una fila duplicada - `examples/payout-report.md` - la salida real de la calculadora en el ejemplo ## Flujo de trabajo ### 1. Recopila el plan y los acuerdos Pide el documento del plan de compensación (o la página relevante) y conviértelo en un JSON de plan como `examples/comp-plan.json`. Confirma los detalles que cambian el dinero: ¿son los niveles marginales (cada porción de crédito a su propia tasa) o fijos (la tasa alcanzada se aplica a todo el crédito)? ¿Se mide el logro en reservas, ACV o margen? ¿Cómo se acreditan renovaciones y expansiones? ¿Hay un límite de crédito o un límite de pago? ¿Cuándo se gana la comisión: al reservar o cuando el cliente paga? ¿Cuánto dura la ventana de recuperación y cubre la comisión completa? Luego pide la exportación del CRM de acuerdos ganados cerrados para el período más cancelaciones de acuerdos anteriores, con la comisión ya pagada en esos. ### 2. Ejecuta la calculadora ``` python3 scripts/commission_calc.py examples/comp-plan.json examples/deals.csv python3 scripts/commission_calc.py plan.json deals.csv --rep ana python3 scripts/commission_calc.py plan.json deals.csv --json python3 scripts/commission_calc.py --self-test ``` Salida 0 = sin hallazgos altos, 1 = hallazgos altos (acuerdos retenidos que necesitan una decisión), 2 = entrada incorrecta. Sin un shell, sigue `references/plan-mechanics.md`: ordena los acuerdos de cada representante por fecha de cierre, suma el crédito, divídelo en cada umbral de nivel y multiplica cada porción por su tasa. ### 3. Lee el resultado - Altos primero: CM01 (representante desconocido, monto o fecha incorrecta, tipo de acuerdo desconocido) y CM02 (división no 100%). Estos acuerdos están retenidos - obtén la respuesta de operaciones de ventas antes de la nómina. - Medios: CM05 (descuento sobre el límite sin aprobación - retenido), CM04 (fila duplicada), CM08 (recuperación aplicada - verifica el monto pagado), CM11 (recuperaciones mayores que ganancias - saldo negativo). - Bajos/informativos: acuerdos de otros períodos (CM03), cancelaciones fuera de la ventana, límites (CM06), aceleradores (CM07), diferimientos (CM09), anticipos (CM10). - Verifica un representante a mano contra las porciones de tasa por acuerdo antes de enviar cualquier cosa. ### 4. Resuelve y vuelve a ejecutar Para cada acuerdo retenido, registra la decisión (división correcta, aprobación encontrada, asignación de representante) en el CSV y vuelve a ejecutar. Nunca cambies el plan para hacer que un número se vea bien; si el plan es ambiguo, escribe la pregunta y muestra ambos resultados (por ejemplo, con `tier_method` fijo vs marginal). ### 5. Entrega Devuelve la tabla de pagos para aprobación, un estado de cuenta por representante de `templates/commission-statement.md` con cada acuerdo, porción de tasa, límite, recuperación y línea de anticipo, la lista de acuerdos retenidos con la pregunta abierta, y notas para nómina (saldos negativos, saldos de anticipo, montos diferidos). ## Resultado de ejemplo En el ejemplo, los pagos de octubre totalizan 9,500.00 EUR, con 3 acuerdos retenidos. Ana Ruiz alcanza 158.7% de su cuota de 60,000 (renovación de Delta Foods acreditada al 50%), gana 8,280.00 en niveles marginales más 400.00 en SPIFFs de prepago anual y está limitada al máximo de 8,000.00. Ben Okafor gana 690.00 pero el acuerdo de Ironclad cancelado 55 días después del cierre recupera 960.00, así que se le paga 0 y lleva -270.00 hacia adelante. Chloe Martin gana 1,050.00, por debajo de su anticipo recuperable de 1,500.00, así que el anticipo complementa 450.00 y su saldo sube a 1,050.00. Retenidos: Granite Works (división 50/40 = 90%), Nimbus Air (representante "dave" no en el plan) y Fjord Outdoor (descuento 30%, límite 20%, sin aprobación). ## Reglas - Sigue el plan firmado; cuando el plan y los datos no coincidan, retén el acuerdo y pregunta - nunca adivines una división, un representante o una aprobación. - Muestra la aritmética: cada pago debe ser rastreable a crédito de acuerdo, porciones de nivel y ajustes. - Aplica niveles en orden de fecha de cierre y di si el plan es marginal o fijo. - Trata recuperaciones y saldos negativos con cuidado: indica lo que el plan permite y señala a RR.HH./nómina y la ley local antes de deducir del pago. - Los datos de comisiones son confidenciales: comparte a cada representante solo su propio estado de cuenta. - Esto es una ayuda de cálculo, no asesoría legal, fiscal o de nómina.