Financiero Documentación

Engine

break_even

Grupo

financial

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Análisis de punto de equilibrio: BEP en unidades/ingresos, margen de contribución, margen de seguridad, DOL y sensibilidad.

¿Por qué? Use este engine para responder objetivamente cuánto hay que vender para no perder dinero y qué tan cerca de eso está la operación. Calcula el punto de equilibrio en unidades y en ingresos, el margen de contribución por unidad y su porcentaje, y, cuando se informa actual_units_sold, el margen de seguridad y el grado de apalancamiento operativo (GAO). Opera en modo producto único o multiproducto y completa el análisis con sensibilidad a variaciones de +/-10% y +/-20% y una curva volumen-utilidad de 10 puntos.

¿Cómo? El margen de contribución es el precio unitario menos el costo variable unitario; el punto de equilibrio en unidades divide los costos fijos por ese margen (redondeando hacia arriba) y el punto de equilibrio en ingresos divide los costos fijos por el índice de margen de contribución. El margen de seguridad mide la distancia porcentual entre los ingresos reales y los ingresos de equilibrio, y el GAO relaciona la contribución total con la utilidad operativa. La sensibilidad recalcula el punto de equilibrio variando precio, costos fijos y costos variables en +/-10% y +/-20%. Exige un precio unitario mayor que el costo variable unitario.

Origen El análisis costo-volumen-utilidad fue introducido por Rautenstrauch (1930, The Successful Control of Profits) y está consolidado en la contabilidad gerencial por Horngren, Datar y Rajan (2018, Cost Accounting: A Managerial Emphasis).

Literatura de referencia

• Horngren, C. T., Datar, S. M. & Rajan, M. V. (2018). "Cost Accounting: A Managerial Emphasis." 16th ed., Pearson.
• Rautenstrauch, W. (1930). "The Successful Control of Profits."

Parámetros (params)

Columnas de data[]

Respuesta

En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).

Errores

• 403 - la engine no está en allowed_engines de tu suscripción.
• 413 - subida por encima de max_upload_mb.
• 422 - engine desconocida o inactiva en el catálogo.
• 429 - cuota diaria (max_jobs_per_day) o por minuto excedida.

La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.

Engine

monte_carlo

Grupo

financial

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Simulación Monte Carlo de VAN: distribución probabilística de VAN y TIR con VaR/CVaR y percentiles.

¿Por qué? Use este engine para evaluar no solo el retorno esperado de una inversión con flujos de caja inciertos, sino el riesgo real de que salga mal. Simulando cientos de miles de escenarios, entrega las distribuciones de VAN y TIR: media, desviación estándar, percentiles, histograma y, en cada nivel de confianza pedido, VaR y CVaR. Con semilla configurable, los resultados son reproducibles.

¿Cómo? En cada simulación y cada período se muestrea un flujo de caja de la distribución de ese período, y el VAN del escenario es la inversión inicial más la suma de los flujos descontados a la tasa indicada. Tras N simulaciones agrega media, desviación estándar, percentiles e histograma; para cada nivel de confianza, el VaR es el percentil correspondiente a la cola mala y el CVaR es la media de los escenarios más allá de él. La TIR sale por bisección y, por encima de 10000 escenarios, sobre una submuestra de ese tamaño: los escenarios en que ninguna tasa anula el VAN quedan fuera, y cuando no queda ninguno la TIR media vuelve en cero. La semilla hace determinista la secuencia, así que la misma entrada devuelve el mismo resultado.

Origen El método de Monte Carlo fue formalizado por Metropolis y Ulam (1949, Journal of the American Statistical Association); su aplicación al análisis de riesgo de inversión viene de Hertz (1964, Harvard Business Review).

Literatura de referencia

• Metropolis, N. & Ulam, S. (1949). "The Monte Carlo Method." Journal of the American Statistical Association, 44(247), 335-341.
• Hertz, D. B. (1964). "Risk Analysis in Capital Investment." Harvard Business Review.

Parámetros (params)

Columnas de data[]

Respuesta

En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).

Errores

• 403 - la engine no está en allowed_engines de tu suscripción.
• 413 - subida por encima de max_upload_mb.
• 422 - engine desconocida o inactiva en el catálogo.
• 429 - cuota diaria (max_jobs_per_day) o por minuto excedida.

La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.

Engine

monte_carlo_deep

Grupo

financial

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Simulación Monte Carlo de VPN/TIR a gran escala con aceleración dedicada (fallback en CPU).

Simulación Monte Carlo masivamente paralela de VPN y TIR sobre distribuciones de flujo de caja por período (normal, uniforme, triangular o lognormal), ejecutada con aceleración dedicada y fallback automático en CPU. Devuelve las distribuciones de VPN/TIR, percentiles, un histograma y VaR/CVaR en cada nivel de confianza pedido.

Parámetros (params)

Columnas de data[]

Respuesta

En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).

Errores

• 403 - la engine no está en allowed_engines de tu suscripción.
• 413 - subida por encima de max_upload_mb.
• 422 - engine desconocida o inactiva en el catálogo.
• 429 - cuota diaria (max_jobs_per_day) o por minuto excedida.

La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.

Engine

npv

Grupo

financial

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Calculadora de VPN: valor presente neto, TIR, payback fraccionario e índice de rentabilidad.

¿Por qué? Use este engine para decidir si una inversión vale el capital: descuenta una serie de flujos de caja futuros a valor presente y entrega cuatro métricas clásicas de decisión. Son el NPV (valor presente neto), la TIR (tasa interna de retorno), el Payback Period sobre el flujo descontado acumulado y el Profitability Index, donde PI > 1 indica una inversión viable. El detalle por período hace el cálculo auditable línea por línea, base para comparar proyectos con objetividad.

¿Cómo? Cada flujo se multiplica por el factor de descuento 1 / (1 + r)^t y el NPV suma los flujos descontados restando la inversión inicial. La TIR es la tasa que lleva el NPV a cero, encontrada por el método de bisección en el intervalo -0.99 a 10.0 con tolerancia 1e-7 y hasta 1000 iteraciones. El Payback Period es el primer período en que el flujo descontado acumulado recupera la inversión, y el PI es la razón entre el valor presente de los flujos y la inversión inicial.

Origen La teoría del descuento de flujos de caja se remonta a Fisher (1930, The Theory of Interest); la práctica consolidada de evaluación de inversiones sigue a Brealey, Myers y Allen (2020, Principles of Corporate Finance).

Literatura de referencia

• Fisher, I. (1930). "The Theory of Interest." Macmillan.
• Brealey, R. A., Myers, S. C. & Allen, F. (2020). "Principles of Corporate Finance." 13th ed., McGraw-Hill.

Parámetros (params)

Columnas de data[]

Respuesta

En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).

Errores

• 403 - la engine no está en allowed_engines de tu suscripción.
• 413 - subida por encima de max_upload_mb.
• 422 - engine desconocida o inactiva en el catálogo.
• 429 - cuota diaria (max_jobs_per_day) o por minuto excedida.

La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.

Engine

revenue_waterfall

Grupo

financial

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Cascada de ingresos: descompone la variación de ingresos entre dos períodos en clientes nuevos/perdidos, frecuencia y ticket promedio.

Compara los ingresos por cliente entre dos períodos y descompone la variación de forma exacta (sin término residual) en ingresos de clientes nuevos, ingresos de clientes perdidos, un efecto de frecuencia (ΔFrecuencia × AOV_período1) y un efecto de AOV (ΔAOV × Frecuencia_período2). Si no se dan los límites de los períodos, los datos se dividen automáticamente en la fecha del punto medio.

Parámetros (params)

Columnas de data[]

Respuesta

En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).

Errores

• 403 - la engine no está en allowed_engines de tu suscripción.
• 413 - subida por encima de max_upload_mb.
• 422 - engine desconocida o inactiva en el catálogo.
• 429 - cuota diaria (max_jobs_per_day) o por minuto excedida.

La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.

Engine

sales_performance

Grupo

financial

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Desempeño de ventas: ingresos por producto, cantidad, tendencia de ingresos, participación de mercado y margen de ganancia opcional.

¿Por qué? Use este engine para ver de una sola vez qué sostiene los ingresos, qué está creciendo y qué se está encogiendo en el portafolio. Para cada producto entrega ingresos totales, cantidad vendida, precio promedio, tendencia de ingresos, market share porcentual y, cuando la columna cost está presente, el margen de utilidad. Ordena los productos por ingresos y destaca los mejores y peores performers, además de la tasa de crecimiento general del período.

¿Cómo? Agrega las transacciones por product_id, sumando ingresos y cantidad, y deriva el precio promedio unitario. Divide el período por la mediana de las fechas de venta en dos mitades y calcula la tendencia de cada producto como la variación porcentual entre las sumas de ingresos de la primera y la segunda mitad; el market share es la participación del producto en los ingresos totales. Como la tendencia compara sumas absolutas, mitades con distinta cantidad de períodos pueden sesgar el resultado, y los datasets con más puntos temporales producen divisiones más equilibradas.

Origen El análisis de desempeño de ventas por producto sigue los fundamentos de gestión de marketing de Kotler y Keller (2016, Marketing Management).

Literatura de referencia

• Kotler, P. & Keller, K. L. (2016). "Marketing Management." 15th ed., Pearson.

Parámetros (params)

Columnas de data[]

Respuesta

En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).

Errores

• 403 - la engine no está en allowed_engines de tu suscripción.
• 413 - subida por encima de max_upload_mb.
• 422 - engine desconocida o inactiva en el catálogo.
• 429 - cuota diaria (max_jobs_per_day) o por minuto excedida.

La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.