Riesgo Documentación
Visión general
Detección de anomalías y fraude, riesgo de crédito y descuentos falsos.
Esta referencia cubre 10 engines. Cada endpoint trae ruta, permiso, parámetros, respuesta y los errores posibles.
Anomalías (fraude)
Propósito
Detección de fraude/anomalías con aceleración dedicada vía competencia multi-algoritmo (Isolation Forest, LOF, autoencoder opcional).
¿Por qué? Detección de anomalías y fraude a escala, sin exigir la elección manual del método: el engine ejecuta múltiples algoritmos y selecciona el mejor. Maneja datos mixtos, numéricos y categóricos, con preprocesamiento automático y entrega flags y scores de anomalía por registro.
¿Cómo? Ejecuta Isolation Forest y LOF con aceleración dedicada, además de un AutoEncoder que puntúa anomalías por el error de reconstrucción. Cuando hay labels disponibles, el mejor modelo se selecciona automáticamente por ROC-AUC; el preprocesamiento aplica encoding a las features categóricas y scaling a las numéricas.
Origen Las bases son el Isolation Forest de Liu, Ting y Zhou (2008), presentado en ICDM, y los fundamentos de redes neuronales consolidados por Goodfellow y coautores en "Deep Learning" (MIT Press, 2016).
Literatura de referencia
- Liu, F. T., Ting, K. M. & Zhou, Z.-H. (2008). "Isolation Forest." ICDM.
- Goodfellow, I. et al. (2016). "Deep Learning." MIT Press.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
contamination | number | no | 0.05 | Fracción esperada de filas anómalas. Entre 0.001 y 0.3. |
n_estimators | integer | no | 200 | Número de árboles del Isolation Forest. >= 10. |
features | array | no | Lista explícita de columnas usadas como features. Por defecto: toda columna excepto customer_id/id/user_id/transaction_id y la indicada por label_column. Cuando se envía, la lista vale tal cual: una columna de etiqueta listada aquí se entrena junto, lo que infla el ROC-AUC hasta un 1.0 sin significado. | |
label_column | string | no | Columna con etiquetas binarias de anomalía conocidas (0/1). Cuando está presente, los modelos se evalúan y eligen por ROC-AUC en vez de la varianza del score. La columna misma queda fuera de las features detectadas automáticamente. | |
use_autoencoder | boolean | no | false | Habilita el modelo autoencoder (con aceleración dedicada cuando está disponible). |
autoencoder_epochs | integer | no | 50 | Épocas de entrenamiento del autoencoder, usadas solo con use_autoencoder true. |
random_state | integer | no | 42 | Semilla aleatoria para reproducibilidad del entrenamiento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
amount | number | no | Feature numérica de ejemplo. Cualquier columna numérica o categórica se detecta como feature, excluyendo customer_id/id/user_id/transaction_id y la columna indicada por label_column. Enviar features reemplaza la detección automática, y esas exclusiones dejan de aplicarse. Al menos una feature y 20 filas. |
merchant_category | string | no | Feature categórica de ejemplo, one-hot automática. |
hour_of_day | integer | no | Feature numérica de ejemplo. |
is_fraud | integer | no | Columna opcional de etiqueta binaria (0/1). Apunta label_column a este nombre para habilitar la selección por ROC-AUC. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Anomalías en cuentas
Propósito
Detección multidimensional de anomalías por Z-score sobre features numéricas por cuenta.
¿Por qué? Detecta cuentas anómalas analizando múltiples features numéricas al mismo tiempo, en lugar de marcar outliers en una sola variable. Entrega flags por cuenta con la dirección de cada desvío (high o low), un score compuesto que ordena la severidad y un resumen por columna, priorizando la investigación de las cuentas consistentemente fuera del patrón en varias dimensiones.
¿Cómo? Calcula Z-scores por feature contra la media y la desviación estándar globales y marca la feature como anómala cuando |z| excede el threshold (por defecto 3.0). La cuenta se marca cuando el número de features anómalas alcanza min_anomalous_features (por defecto 2), y el score compuesto es la suma de los |Z-scores| anómalos.
Origen La base científica proviene de la taxonomía de detección de anomalías de Chandola, Banerjee y Kumar (2009), "Anomaly Detection: A Survey" (ACM Computing Surveys), y de la noción de distancia multidimensional introducida por Mahalanobis (1936) en "On the generalized distance in statistics".
Literatura de referencia
- Chandola, V., Banerjee, A. & Kumar, V. (2009). "Anomaly Detection: A Survey." ACM Computing Surveys, 41(3), 1-58.
- Mahalanobis, P. C. (1936). "On the generalized distance in statistics."
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
threshold | number | no | 3 | Umbral de Z-score por encima del cual una feature se considera anómala para la cuenta. |
min_anomalous_features | integer | no | 2 | Mínimo de features anómalas para que la cuenta sea señalada. |
columns | array | no | Columnas numéricas específicas a analizar. Por defecto: toda columna numérica además de account_id. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
account_id | string | sí | Identificador de la cuenta. |
transaction_count | number | no | Feature numérica de ejemplo analizada. Cualquier columna numérica además de account_id se detecta como feature, salvo restricción por el param columns. |
total_amount | number | no | Feature numérica de ejemplo analizada. |
avg_amount | number | no | Feature numérica de ejemplo analizada. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly_accounts/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Anomalías (profundas)
Propósito
Detección profunda de anomalías con aceleración dedicada vía VAE/DAGMM más baselines Isolation Forest y LOF.
Entrena un Variational AutoEncoder y/o un Deep Autoencoding Gaussian Mixture Model (con aceleración dedicada cuando está disponible) junto a las baselines Isolation Forest y LOF, y luego selecciona el mejor modelo por ROC-AUC cuando label_column entrega etiquetas conocidas, si no por la desviación estándar del score.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
contamination | number | no | 0.05 | Fracción esperada de filas anómalas. Entre 0.001 y 0.3. |
algorithm | string | no | "auto" | Uno de 'auto', 'vae', 'dagmm', 'isolation_forest', 'lof'. 'auto' evalúa todos los disponibles y elige el mejor. |
latent_dim | integer | no | 8 | Dimensionalidad del espacio latente de los modelos profundos VAE/DAGMM. Entero positivo. |
epochs | integer | no | 100 | Épocas de entrenamiento de los modelos profundos VAE/DAGMM. Entero positivo. |
features | array | no | Lista explícita de columnas usadas como features. Por defecto: toda columna excepto customer_id/id/user_id/transaction_id y la indicada por label_column. Cuando se envía, la lista vale tal cual: una columna de etiqueta listada aquí se entrena junto, lo que infla el ROC-AUC hasta un 1.0 sin significado. | |
label_column | string | no | Columna con etiquetas binarias de anomalía conocidas (0/1). Cuando está presente, los modelos se eligen por ROC-AUC. La columna misma queda fuera de las features detectadas automáticamente. | |
random_state | integer | no | 42 | Semilla aleatoria para reproducibilidad. Entero no negativo. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
amount | number | no | Feature numérica de ejemplo. Cualquier columna numérica o categórica se detecta como feature, excluyendo customer_id/id/user_id/transaction_id y la columna indicada por label_column. Enviar features reemplaza la detección automática, y esas exclusiones dejan de aplicarse. Al menos una feature y 20 filas. |
merchant_category | string | no | Feature categórica de ejemplo, one-hot automática. |
hour_of_day | integer | no | Feature numérica de ejemplo. |
is_fraud | integer | no | Columna opcional de etiqueta binaria (0/1). Apunta label_column a este nombre para habilitar la selección por ROC-AUC. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly_deep/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Detección de anomalías
Propósito
Detección no supervisada de anomalías vía Isolation Forest o Local Outlier Factor.
¿Por qué? Detecta anomalías en datos transaccionales o de cuentas sin necesidad de datos etiquetados, siendo ideal para detección de fraude y de comportamiento atípico. Cubre tanto grandes volúmenes como anomalías locales sutiles, entregando las observaciones marcadas como fuera del patrón.
¿Cómo? El Isolation Forest aísla observaciones construyendo árboles de decisión aleatorios, y las anomalías quedan aisladas en menos splits (menor path length). El Local Outlier Factor (LOF) compara la densidad local de cada punto con la de sus vecinos, marcando los puntos de densidad mucho menor, con normalización de features antes del ajuste.
Origen Los métodos fueron propuestos por Liu, Ting y Zhou (2008) en "Isolation Forest" (ICDM) y por Breunig y coautores (2000) en "LOF: Identifying Density-Based Local Outliers" (SIGMOD).
Literatura de referencia
- Liu, F. T., Ting, K. M. & Zhou, Z.-H. (2008). "Isolation Forest." ICDM.
- Breunig, M. M. et al. (2000). "LOF: Identifying Density-Based Local Outliers." SIGMOD.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
method | string | no | "auto" | Uno de 'auto', 'isolation_forest', 'lof'. 'auto' usa Isolation Forest. |
contamination | number | no | 0.05 | Proporción esperada de anomalías. Estrictamente entre 0 y 0.5. |
random_state | integer | no | 42 | Semilla aleatoria del modelo Isolation Forest. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
transaction_amount | number | no | Feature numérica de ejemplo. Cualquier columna numérica se detecta como feature, excluyendo id/customer_id/user_id/index/transaction_id/account_id. Al menos 1 feature y 20 filas. |
session_duration | number | no | Feature numérica de ejemplo. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly_detection/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Anomalías en grafo
Propósito
Detección de anomalías en redes de transacciones vía Z-scores de centralidad/PageRank.
¿Por qué? Detecta anomalías en redes de transacciones por la posición topológica de cada nodo, revelando intermediarios y hubs atípicos que pasarían inadvertidos en análisis cuenta por cuenta. Entrega los nodos sospechosos marcados, con detección opcional de comunidades en la red.
¿Cómo? Construye un grafo dirigido ponderado y computa siete métricas de centralidad, agrupadas en cuatro familias independientes: grado, valor, PageRank y betweenness. Un nodo se señala cuando el Z-score de cola superior excede el umbral en al menos el número pedido de familias distintas, y el score compuesto promedia el Z-score más fuerte de cada familia. Las comunidades se detectan por modularidad.
Origen Las bases son el PageRank de Page y coautores (1999), "The PageRank Citation Ranking" (Stanford InfoLab), y la detección de comunidades de Girvan y Newman (2002) en "Community Structure in Social and Biological Networks", publicado en PNAS.
Literatura de referencia
- Page, L. et al. (1999). "The PageRank Citation Ranking." Stanford InfoLab.
- Girvan, M. & Newman, M. E. J. (2002). "Community Structure in Social and Biological Networks." PNAS, 99(12), 7821-7826.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
threshold | number | no | 3 | Umbral de Z-score por encima del cual una métrica del grafo se considera anómala. Solo cuenta la cola superior: toda tipología detectada aquí (mula colectora, puente de estratificación, dispersor de estructuración) se define por un valor ALTO, y un nodo por debajo del promedio es una cuenta tranquila, no un sospechoso. Número positivo. |
min_anomalous_metrics | integer | no | 2 | Mínimo de FAMILIAS de métricas independientes por encima del umbral para que un nodo sea señalado. Las cuatro familias son grado (entrada/salida/total), valor (grado ponderado de entrada y de salida), pagerank y betweenness; contar familias en vez de métricas crudas impide que una sola transferencia extrema pase por dos evidencias. Entero entre 1 y 4, ya que un valor mayor nunca podría alcanzarse y se rechaza. |
detect_communities | boolean | no | true | Si debe correr la detección de comunidades por modularidad greedy y marcar las anomalías con su comunidad. |
community_weight | boolean | no | false | Pondera la detección de comunidades por amount, en vez de solo por la topología. Aplica a la partición Y a la modularidad reportada de ella, que nunca pueden discrepar. Apagado por defecto: amount suele abarcar varios órdenes de magnitud y sus extremos pertenecen justamente a las cuentas bajo sospecha, así que ponderar deja que el fraude redibuje la medida de la estructura en que se esconde. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
source | string | sí | Nodo de origen (ID de cuenta/entidad) de la arista de transacción. |
target | string | sí | Nodo de destino (ID de cuenta/entidad) de la arista de transacción. |
amount | number | no | Monto de la transacción, usado como peso de la arista. Por defecto 1.0 por ocurrencia cuando está ausente. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly_graph/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Anomalías multivariadas
Propósito
Detección multivariada de anomalías (Isolation Forest / LOF) para lotes grandes, con estadísticas univariadas opcionales por columna.
Detecta anomalías en la combinación de las features, y no por columna, usando Isolation Forest (por defecto) o Local Outlier Factor sobre columnas numéricas detectadas automáticamente. Pensada para lotes de más de 100 filas; los lotes pequeños deben usar la engine anomaly_zscore. Cuando include_univariate es true, también devuelve estadísticas Z-score/MAD por columna en el mismo formato que anomaly_zscore.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
method | string | no | "auto" | Uno de 'auto', 'isolation_forest', 'lof'. 'auto' usa Isolation Forest. |
contamination | number | no | 0.05 | Proporción esperada de anomalías. Estrictamente entre 0 y 0.5. |
random_state | integer | no | 42 | Semilla aleatoria del modelo Isolation Forest. |
threshold | number | no | 3 | Umbral de Z-score/Z-score modificado de las estadísticas univariadas por columna cuando include_univariate es true. |
include_univariate | boolean | no | true | También calcula estadísticas Z-score/MAD por columna junto al resultado multivariado. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
page_views | number | no | Feature numérica de ejemplo. Cualquier columna numérica se detecta como feature, excluyendo id/visitor_id/customer_id/user_id/account_id/transaction_id/index/tracking_id/session_id/device_id. Al menos 30 filas. |
session_duration | number | no | Feature numérica de ejemplo. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly_multivariate/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Anomalías (Z-score)
Propósito
Detección univariada de anomalías por columna numérica: Z-score, IQR, MAD o Grubbs.
¿Por qué? Detecta outliers en columnas numéricas combinando múltiples métodos estadísticos, sirviendo como triaje rápido de datos fuera del patrón antes de análisis más profundos. Puede auto-detectar todas las columnas numéricas o analizar solo las indicadas en columns, entregando los valores anómalos por columna con el método aplicado.
¿Cómo? Aplica Z-score, IQR (Tukey), MAD (Median Absolute Deviation) o la prueba de Grubbs, cada uno con su criterio de corte (threshold por defecto 3.0 para Z-score, fences de Tukey para IQR, Z-score modificado para MAD, valor crítico de la distribución t para Grubbs). El modo automático elige MAD cuando los datos tienen colas pesadas (IQR/desviación estándar > 1.5) y Z-score en caso contrario.
Origen La prueba de outliers de Grubbs fue formalizada por Grubbs (1969) en "Procedures for Detecting Outlying Observations in Samples" (Technometrics), y las técnicas robustas de detección siguen a Iglewicz y Hoaglin (1993) en "How to Detect and Handle Outliers" (ASQ Press).
Literatura de referencia
- Grubbs, F. E. (1969). "Procedures for Detecting Outlying Observations in Samples." Technometrics, 11(1), 1-21.
- Iglewicz, B. & Hoaglin, D. C. (1993). "Volume 16: How to Detect and Handle Outliers." ASQ Press.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
method | string | no | "auto" | Uno de 'auto', 'zscore', 'iqr', 'mad', 'grubbs'. |
threshold | number | no | 3 | Umbral de score por encima del cual un valor se señala como anómalo. La interpretación depende del método (Z-score/Z-score modificado/estadística de Grubbs; para IQR, threshold=3.0 mapea al clásico multiplicador de cerca k=1.5, si no k=threshold/2). |
columns | array | no | Columnas numéricas específicas a analizar. Por defecto: toda columna numérica de la entrada. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
amount | number | no | Columna numérica de ejemplo. Cualquier columna numérica se detecta y analiza de forma independiente, salvo restricción por el param columns. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/anomaly_zscore/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Riesgo de crédito
Propósito
Score de riesgo de incumplimiento vía clasificadores calibrados Regresión Logística / Random Forest.
¿Por qué? Evalúa riesgo crediticio con scores interpretables, siendo la base para decisiones de crédito automatizadas. Mapea probabilidades calibradas a clases de riesgo (low, medium, high) y entrega un ranking de feature importance que muestra qué pesa más en la evaluación, permitiendo aprobar, tarifar o rechazar operaciones de forma consistente.
¿Cómo? Random Forest y Logistic Regression actúan como modelos base, con calibración de probabilidades por Platt scaling. La importancia de las features proviene de los atributos del propio modelo (importancia de Gini en Random Forest), y la clasificación en tiers de riesgo usa thresholds de probabilidad.
Origen El modelado de riesgo crediticio se remonta a Altman (1968), "Financial Ratios, Discriminant Analysis and the Prediction of Corporate Bankruptcy" (The Journal of Finance), y el Random Forest fue propuesto por Breiman (2001) en "Random Forests" (Machine Learning).
Literatura de referencia
- Altman, E. I. (1968). "Financial Ratios, Discriminant Analysis and the Prediction of Corporate Bankruptcy." The Journal of Finance, 23(4), 589-609.
- Breiman, L. (2001). "Random Forests." Machine Learning, 45(1), 5-32.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
label_column | string | sí | Nombre de la columna objetivo binaria (0=sin default, 1=default). Necesita al menos 2 muestras en cada clase. | |
algorithm | string | no | "auto" | Uno de 'auto', 'logistic', 'random_forest'. 'auto' entrena ambos y se queda con el mejor por ROC-AUC. |
random_state | integer | no | 42 | Semilla aleatoria del split y del entrenamiento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
default | integer | sí | Columna objetivo binaria (0=sin default, 1=default). El nombre es configurable vía label_column; al menos 30 filas y 2 muestras por clase. |
income | number | no | Feature numérica de ejemplo. Cualquier columna numérica se detecta como feature, excluyendo label_column/customer_id/id/user_id/index/loan_id. |
debt_ratio | number | no | Feature numérica de ejemplo. |
credit_score | number | no | Feature numérica de ejemplo. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/credit_risk/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Riesgo de crédito (explicable)
Propósito
Score de riesgo de crédito explicable: importancia global por permutación más explicaciones de factores por muestra.
¿Por qué? Explica las predicciones del modelo de riesgo crediticio, agregando la capa de interpretabilidad esencial para el compliance regulatorio y la transparencia. Entrega la importancia global de las features y explicaciones en lenguaje natural por muestra, listas para justificar cada decisión de crédito ante analistas, auditores y clientes.
¿Cómo? Sobre un modelo base de Random Forest o Logistic Regression, calcula la importancia global de las features por permutación. Para cada muestra individual, analiza el desvío de las features respecto a la distribución del dataset y genera explicaciones en lenguaje natural.
Origen La tradición de modelado de riesgo crediticio se remonta a Altman (1968), "Financial Ratios, Discriminant Analysis and the Prediction of Corporate Bankruptcy", y la importancia por permutación sigue a Fisher, Rudin y Dominici (2019) en "All Models are Wrong, but Many are Useful" (JMLR).
Literatura de referencia
- Altman, E. I. (1968). "Financial Ratios, Discriminant Analysis and the Prediction of Corporate Bankruptcy."
- Fisher, A., Rudin, C. & Dominici, F. (2019). "All Models are Wrong, but Many are Useful." JMLR, 20, 1-81.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
label_column | string | sí | Nombre de la columna objetivo binaria (0=sin default, 1=default). Necesita al menos 2 muestras en cada clase. | |
algorithm | string | no | "auto" | Uno de 'auto', 'logistic', 'random_forest'. 'auto' entrena ambos y se queda con el mejor por ROC-AUC. |
n_top_features | integer | no | 5 | Cantidad de features contribuyentes en cada explicación por muestra. Entero positivo. |
random_state | integer | no | 42 | Semilla aleatoria del split y del entrenamiento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
default | integer | sí | Columna objetivo binaria (0=sin default, 1=default). El nombre es configurable vía label_column; al menos 30 filas y 2 muestras por clase. |
income | number | no | Feature numérica de ejemplo. Cualquier columna numérica se detecta como feature, excluyendo label_column/customer_id/id/user_id/index/loan_id. |
debt_ratio | number | no | Feature numérica de ejemplo. |
credit_score | number | no | Feature numérica de ejemplo. |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/credit_risk_explain/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Detector de descuento falso
Propósito
Detecta patrones fraudulentos de descuento en que los precios se inflan antes de la promoción para simular un descuento mayor.
Agrupa observaciones de precio por (product_id, site_name), calcula un precio base (mediana de los primeros baseline_days), el pico pre-evento y el menor precio en la ventana del evento, y luego deriva el % de inflación, la brecha entre descuento anunciado y real y un flag de patrón pico-caída. Combina todo en un fraud_score ponderado (0-1) y una clasificación clean/suspicious/likely_fraud/fraud, más un resumen de reputación por sitio según la tasa de fraude.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
baseline_days | integer | no | 90 | Días desde la primera observación usados para calcular el precio base (mediana). |
inflation_threshold_pct | number | no | 15 | Aumento porcentual mínimo sobre la base para que un punto de precio cuente en el patrón de inflación recurrente. |
min_discount_gap_pct | number | no | 10 | Brecha mínima (puntos porcentuales) entre descuento anunciado y real para que el texto de evidencia la señale. |
spike_drop_threshold_pct | number | no | 20 | Pico porcentual mínimo seguido de caída porcentual, dentro de spike_drop_window_days, para señalar el patrón pico-caída. |
spike_drop_window_days | integer | no | 14 | Ventana (días) que acota los pares del patrón pico-caída y selecciona las observaciones de la ventana del evento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
product_id | string | sí | Identificador del producto. |
site_name | string | sí | Identificador del retailer/sitio. El análisis se agrupa por (product_id, site_name). |
price | number | sí | Precio observado en recorded_at. |
recorded_at | string | sí | Fecha de la observación (ISO 8601 u otros formatos aceptados). |
original_price | number | no | Precio original alegado por el retailer antes del descuento, si está presente en una fila de la ventana del evento. |
discount_percent | number | no | Porcentaje de descuento alegado por el retailer, si está presente en una fila de la ventana del evento. Derivado de original_price y del precio del evento cuando está ausente. |
product_name | string | no | Nombre de exhibición opcional del producto, retornado por product_id (gana el primer valor no nulo). |
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á enallowed_enginesde tu suscripción.413- subida por encima demax_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.
curl -X POST "https://intelligence.echosistema.live/api/v1/fake_discount_detector/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"