Analytics Documentación
Visión general
Tests A/B, embudos, jornadas, atribución de marketing, Pareto y estacionalidad.
Esta referencia cubre 15 engines. Cada endpoint trae ruta, permiso, parámetros, respuesta y los errores posibles.
Test A/B
Propósito
Significancia de test A/B: z-test de dos proporciones o t-test de Welch, con análisis de poder.
¿Por qué? Use este engine para cerrar un experimento con una decisión defendible: si la diferencia entre Control (A) y Tratamiento (B) es real o solo fruto del azar. Entrega p-value, significancia, intervalos de confianza, lift porcentual, tamaño de efecto (Cohen's h en las proporciones, Cohen's d en las medias), poder estadístico y el tamaño muestral mínimo recomendado para 80% de poder. En la práctica, responde si la variante B puede lanzarse con seguridad o si el test todavía necesita más datos.
¿Cómo? Para tasas de conversión aplica un Z-test de proporciones con proporción combinada de ambos grupos y considera el resultado significativo cuando el p-value cae por debajo de alpha (1 menos el nivel de confianza). Cuando se proporciona value_column, corre además el t-test de Welch para métricas continuas, con grados de libertad de Welch-Satterthwaite. Completa con el tamaño de efecto interpretado en bandas (de negligible a grande), análisis de poder y el lift porcentual entre los grupos. El tamaño muestral mínimo sale de la aproximación normal con varianza combinada (Cohen, 1988).
Origen El diseño de experimentos controlados fue formalizado por Fisher (1935, The Design of Experiments); la práctica moderna de pruebas A/B en línea sigue a Kohavi, Tang y Xu (2020, Trustworthy Online Controlled Experiments).
Literatura de referencia
- Fisher, R. A. (1935). "The Design of Experiments." Oliver & Boyd.
- Kohavi, R., Tang, D. & Xu, Y. (2020). "Trustworthy Online Controlled Experiments: A Practical Guide to A/B Testing." Cambridge University Press.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
test_type | string | no | "proportions" | "proportions" (value binario 0/1, z-test) o "means" (value continuo, t-test de Welch). |
confidence_level | number | no | 0.95 | Nivel de confianza del test y del IC; estrictamente entre 0.5 y 1.0. |
alternative | string | no | "two-sided" | Hipótesis alternativa: "two-sided", "greater" o "less". |
value_column | string | no | Nombre de una columna numérica para correr un segundo test, continuo, sobre las mismas filas (ingresos, tiempo en página), reportado en full.means_test. Es el formato que usaba el engine ab_test_fast; su cola ahora llega a este engine. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
group | string | sí | Etiqueta de la variante. Aliases de control: control, a, 0, baseline (sin distinción de mayúsculas); de lo contrario, la primera etiqueta en orden alfabético se trata como control. Exactamente 2 grupos distintos. |
value | number | sí | Valor de la métrica: 0/1 para test de proporciones, continuo (ej.: ingresos) para test de medias. Cada grupo necesita >= 30 filas. |
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/ab_test/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Test A/B (rápido)
Propósito
Significancia de test A/B: z-test de dos proporciones (t-test continuo opcional).
Atendido por el engine ab_test desde 2026-08-28; la implementación separada fue retirada. La ruta, la cola y el formato de entrada no cambiaron: las filas de data llevan una etiqueta group y un flag binario converted, y value_column nombra una columna numérica para un t-test continuo adicional sobre las mismas filas. Lo que cambió es la aritmética, hoy el mismo código de /api/v1/ab_test/process, porque las dos rutas discrepaban sobre datos idénticos. La implementación retirada reportaba un z-statistic cuyo signo contradecía su propio lift, calculaba el intervalo de confianza y el poder a partir del error estándar combinado (la varianza bajo H0, no la que un intervalo necesita), aceptaba resultados no binarios y dos filas por grupo, descartaba en silencio cualquier tercer grupo según el orden de las filas, y reportaba significancia sin aviso cuando el test estaba subdimensionado. Las respuestas ahora traen la decision de tres estados, el Cohen's h, el alternative y la validación que faltaba.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
confidence_level | number | no | 0.95 | Nivel de confianza del test (alpha = 1 - confidence_level). |
value_column | string | no | Nombre de una columna continua (ej.: ingresos) para el t-test. Omitir para un test solo de proporciones. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
group | string | sí | Etiqueta de la variante. Aliases de control: control, a, 0, baseline; todo lo demás es tratamiento. |
converted | integer | sí | Flag de conversión, 0 o 1. |
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/ab_test_fast/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Scorecard de afiliados
Propósito
Scorecard multidimensional de desempeño de afiliados/socios, con clasificación en tiers.
Puntúa afiliados en cinco dimensiones ponderadas, ingresos, volumen de pedidos, calidad del cliente (tasa de recompra y ticket promedio), eficiencia de comisión y crecimiento, normalizadas por min-max DENTRO DE LA COHORTE de este job: un score no es comparable entre ejecuciones. El bloque scoring_scale entrega esa limitación junto con el resultado, con la escala en uso, el tamaño de la cohorte, la negación explícita de comparabilidad entre ejecuciones, las dimensiones en que toda la cohorte comparte un solo valor y el tier_basis. Los tiers son PERCENTILES DE LA COHORTE, no cortes fijos: un corte fijo sobre un score relativo volvía el tier superior casi inalcanzable en una cohorte grande y gratuito en una pequeña, ya que con dos afiliados el ganador lidera todas las dimensiones por construcción. No se otorga tier superior por debajo de min_cohort_for_top_tier afiliados. Una dimensión sin valor para el afiliado, ingresos con comisión cero, o ningún primer semestre desde donde crecer, sale de su compuesto y los pesos restantes se renormalizan, en vez de imputarse: esas vuelven nulas, con new_in_window marcando a quien es nuevo. Las filas que la agregación no pudo usar se cuentan por motivo en full.data_quality, y los afiliados por debajo de min_orders aparecen en full.excluded_affiliates en vez de desaparecer sin aviso.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
commission_pct | number | no | 5 | Porcentaje de comisión usado cuando la fila no trae valor en la columna commission_pct. Alias: commission_pct_default. |
period_days | integer | no | 90 | Largo de la ventana de análisis en días, terminando en la fecha de referencia. |
reference_date | string | no | Fecha ISO (YYYY-MM-DD) que ancla la ventana de análisis. Por defecto: el mayor order_date de los datos. Debe ser YYYY-MM-DD: un valor malformado se rechaza, en vez de sustituirse en silencio por la fecha más reciente de los datos, lo que desplazaría toda la ventana. | |
min_orders | integer | no | 5 | Mínimo de pedidos en la ventana para que el afiliado sea puntuado. |
weights | object | no | {"revenue":0.25,"conversion":0.2,"customer_quality":0.25,"efficiency":0.15,"growth":0.15} | Pesos por dimensión, renormalizados para sumar 1. Claves: revenue, volume, customer_quality, efficiency, growth. volume cuenta PEDIDOS y se llamaba conversion hasta 2026-08-28, grafía todavía aceptada. Se renombró porque contaba clientes únicos, lo que el engine no puede llamar tasa de conversión (no hay clics ni sesiones) y lo que anulaba el premio de fidelidad: un afiliado con recompra ganaba en customer_quality y perdía lo mismo por tener menos clientes distintos. La concentración ahora se reporta como orders_per_customer y se señala como debilidad, en vez de puntuarse como mal desempeño. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
affiliate_id | string | sí | Identificador del afiliado/socio. |
customer_id | string | sí | Identificador del cliente, usado para calcular clientes únicos y tasa de recompra. |
order_date | string | sí | Fecha del pedido; acepta strings ISO, epoch Unix (s/ms) o YYYYMMDD. |
amount | number | sí | Monto de ingresos del pedido. |
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/affiliate_scorecard/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Atribución por canal
Propósito
Atribución de canales de marketing con modelos last-touch, first-touch, linear o position-based.
Ruta alias de marketing_attribution: el mismo engine, módulo y clase, en una cola separada, de modo que ambas rutas devuelven resultados idénticos por construcción. Agrupa touchpoints por conversion_id, ordena por touchpoint_order y distribuye el crédito según el modelo elegido. Cuando conversion_value está presente, también calcula ROI por canal. Siempre devuelve la comparación entre los cuatro modelos de atribución. Una jornada cuyo conversion_value es nulo queda FUERA de la atribución por valor, en vez de contar como una unidad de moneda, lo que hacía que el total atribuido superara el valor real de conversión exactamente por el número de esas jornadas; se cuentan en conversions_without_value. Esto es distinto de un conjunto de datos SIN columna conversion_value alguna, donde cada conversión vale 1 y la atribución es una participación de conteo, comportamiento documentado e inalterado. El valor se lee del touchpoint que lo lleva, no del primero, porque los logs de evento suelen adjuntarlo a la fila que convirtió. full.channel_attribution_by_count corre el mismo modelo con cada jornada valiendo 1, dando crédito fraccionario por posición sin moneda de por medio, lo que conversions_by_channel no hace, ya que cuenta jornadas en que el canal apenas estuvo presente. share_pct es nulo cuando no hay valor del cual tomar participación. Los valores de conversión negativos y el touchpoint_order duplicado dentro de una misma jornada se rechazan: el primero produce participaciones fuera de 0 a 100, el segundo deja first-touch y last-touch indefinidos.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
model | string | no | "linear" | Modelo principal de atribución: "last_touch", "first_touch", "linear" o "position_based" (40% primero / 40% último / 20% medio). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
conversion_id | string | sí | Identificador único que agrupa touchpoints en una misma jornada de conversión. |
channel | string | sí | Nombre del canal de marketing (ej.: email, organic, paid_search). |
touchpoint_order | integer | sí | Orden (desde 1) del touchpoint dentro de la jornada de conversión. |
conversion_value | number | no | Ingresos o valor de la conversión. Cuando está presente, el crédito se distribuye por valor y se calcula el ROI por canal. |
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/channel_attribution/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Embudo de conversión
Propósito
Embudo de conversión estricto: conversión por etapa, abandono, usuarios perdidos y cuellos de botella.
¿Por qué? Use este engine para descubrir dónde se pierde la conversión en un flujo de etapas ordenadas y priorizar optimizaciones con datos en lugar de intuición. Entrega, por etapa, la conversión total (relativa a la primera etapa), la conversión step-to-step, la tasa de abandono y la conversión general del embudo, además de detectar el cuello de botella, la etapa con mayor abandono. Cuando se proporciona la columna timestamp, mide también el tiempo promedio entre etapas.
¿Cómo? Cuenta usuarios distintos en cada etapa y deriva las tasas: conversión total como razón sobre la primera etapa, conversión step-to-step como razón sobre la etapa anterior y abandono como el complemento de esa razón. El cuello de botella es la etapa (excluyendo la primera) con mayor abandono, ignorando las etapas declaradas sin eventos y las que ellas vaciaron, que abandonarían 100% por construcción y ganarían siempre. El orden de las etapas viene del parámetro step_order, de una columna numérica step_order o del orden de primera aparición en los datos.
Origen El análisis de embudo como instrumento de gestión orientada a datos está consolidado en Croll y Yoskovitz (2013, Lean Analytics).
Literatura de referencia
- Croll, A. & Yoskovitz, B. (2013). "Lean Analytics: Use Data to Build a Better Startup Faster." O'Reilly Media.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
step_order | array | no | Lista ordenada explícita de nombres de etapas. Anula cualquier columna step_order u orden de primera aparición. Una etapa repetida se rechaza: intersecta el embudo consigo mismo y convierte siempre al 100%. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
user_id | string | sí | Identificador único del usuario. |
step_name | string | sí | Etiqueta de la etapa del embudo (ej.: view, cart, purchase). |
step_order | integer | no | Orden numérico opcional de las etapas, usado cuando no se da el param step_order. |
timestamp | string | no | Timestamp opcional del evento (epoch en string, RFC3339 con Z o con offset, "%Y-%m-%dT%H:%M:%S[.f]", "%Y-%m-%d %H:%M:%S[.f]" o "%Y-%m-%d"); habilita métricas de tiempo entre etapas. Se usa la ocurrencia más antigua por usuario/etapa, así que el orden de las filas no cambia el resultado. Un valor que no parsea se cuenta en unparsed_timestamps en vez de volverse epoch 0 en silencio. |
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/funnel/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Jornada (Markov)
Propósito
Análisis de matriz de transición en cadena de Markov sobre secuencias de etapas de jornada.
¿Por qué? Use este engine para entender los flujos reales de los clientes entre puntos de contacto e identificar con precisión los puntos de abandono. Modela el recorrido como proceso estocástico y entrega la matriz de transición entre estados, las frecuencias de estado, las tasas de abandono por estado y la probabilidad de conversión. El resultado cuantifica el peso de cada estado en el camino hacia la conversión, base para decidir qué etapas proteger u optimizar.
¿Cómo? Construye la matriz de probabilidades de transición a partir de las secuencias observadas de estados, usando cadenas de Markov de primer orden, donde la probabilidad del próximo estado depende solo del estado actual. La conversión por estado se cuenta empíricamente sobre las sesiones que pasaron por él, y no se deriva de la absorción de la cadena: es lo que mantiene la identidad de que un estado visitado por toda sesión reporta la tasa de conversión global. Opera con matrices dispersas por eficiencia.
Origen El modelado de recorridos con cadenas de Markov aplicado a la atribución en línea sigue a Anderl, Becker, von Wangenheim y Schumann (2016, International Journal of Research in Marketing).
Literatura de referencia
- Anderl, E., Becker, I., von Wangenheim, F. & Schumann, J. H. (2016). "Mapping the Customer Journey: Lessons Learned from Graph-Based Online Attribution Modeling." International Journal of Research in Marketing, 33(3), 457-474.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
min_sessions | integer | no | 1 | Conteo mínimo de visitas para que un estado permanezca en la salida (>= 1, entero). Los estados por debajo salen de todos los bloques de resultado y se listan en full.data_quality.pruned_states; una transición HACIA un estado podado se redirige a __EXIT__ en vez de descartarse, así que las filas no se renormalizan. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
session_id | string | sí | Identificador único de la sesión. |
steps | array | sí | Lista ordenada de nombres de etapas/estados de la sesión (lista o lista serializada como string). |
converted | integer | sí | 1 si la sesión convirtió, 0 si abandonó. Acepta 0, 1, true, false o nulo; nulo cuenta como no convertida. Cualquier otro valor se rechaza en vez de convertirse, porque convertir texto como "0" invertía la métrica. |
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/journey_markov/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Jornada (Markov, rápido)
Propósito
Análisis rápido de transiciones en cadena de Markov sobre secuencias de etapas de jornada.
Construye conteos/probabilidades de transición entre etapas, tasas de entrada/salida/conversión/abandono por estado, los 20 caminos más frecuentes y los principales estados de abandono. El ranking de abandono cuenta sesiones que terminaron en un estado SIN convertir, así que el estado donde las jornadas tienen éxito nunca se reporta como el mayor punto de abandono; top_drop_off_state es nulo cuando ningún estado tiene abandono. Todo agregado es PRE-poda: min_sessions filtra solo qué aristas aparecen en transition_matrix, así que una fila de la matriz puede sumar menos que 1, y el residuo es el peso de las aristas de ese estado en pruned_edges. steps es la lista ordenada de estados por sesión, limitada a max_path_length.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
min_sessions | integer | no | 1 | Conteo mínimo de transiciones para que un par origen->destino se muestre en la matriz de transición. Es filtro de visualización solamente: total_transitions y los exits por estado permanecen pre-poda, y las aristas removidas se listan en full.pruned_edges. ATENCIÓN: aquí la poda es de ARISTAS. El min_sessions del engine journey_markov poda ESTADOS; mismo nombre, semántica distinta. |
max_path_length | integer | no | 10 | Número máximo de etapas consideradas por sesión; los caminos más largos se truncan. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
session_id | string | sí | Identificador único de la sesión. |
steps | array or string | sí | Lista ordenada de nombres de etapas/estados de la sesión. También se acepta una lista serializada (JSON, entre comillas simples o simplemente separada por comas), igual que el engine journey_markov. Celda vacía o [] es jornada vacía y se salta; cualquier otra cosa que no parsea rechaza el job con un error nombrando los session_ids problemáticos, nunca con un error crudo de tipo de columna. |
converted | number | no | 1 si la sesión convirtió, 0 en caso contrario. Cualquier tipo numérico o booleano se acepta y se convierte. Ausente se trata como no convertida; una columna presente pero de tipo inconvertible es error, en vez de una tasa de conversión de 0% en silencio. |
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/journey_markov_fast/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Secuencias de jornada
Propósito
Minería de caminos frecuentes de jornada vía árbol de prefijos (Trie), con conversión por camino.
¿Por qué? Use este engine para descubrir los trayectos exactos que recorren los clientes: qué rutas llevan a la conversión y cuáles terminan en abandono. Extrae las secuencias de recorrido más frecuentes y entrega los caminos de alta frecuencia y alta conversión, con distribución de longitud de los caminos, etapas de cuello de botella y tasas de abandono. Complementa el análisis de Markov al revelar patrones secuenciales concretos, orientando el diseño del flujo del producto.
¿Cómo? Construye un árbol de prefijos (Trie) a partir de las secuencias de eventos y lo recorre en profundidad (DFS) para extraer todas las subsecuencias con frecuencia por encima del umbral configurado. Cuenta las ocurrencias de cada patrón frecuente y analiza la distribución de longitud de los caminos.
Origen La minería de patrones secuenciales tiene su origen en Agrawal y Srikant (1995, Mining Sequential Patterns, ICDE).
Literatura de referencia
- Agrawal, R. & Srikant, R. (1995). "Mining Sequential Patterns." ICDE.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
min_support | integer | no | 10 | Conteo mínimo de ocurrencias para que un camino sea reportado. |
max_length | integer | no | 10 | Largo máximo de secuencia considerado por sesión. |
top_k | integer | no | 50 | Cantidad de caminos en el tope de cada ranking (por frecuencia y por tasa de conversión). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
session_id | string | sí | Identificador único de la sesión. |
steps | array | sí | Lista ordenada de nombres de etapas/estados de la sesión (lista o lista serializada como string). |
converted | integer | sí | 1 si la sesión convirtió, 0 si abandonó. |
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/journey_sequences/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Atribución de marketing
Propósito
Atribución de canales de marketing con modelos last-touch, first-touch, linear o position-based.
¿Por qué? Use este engine para saber qué canales de marketing merecen crédito por cada conversión y optimizar el presupuesto con base en eso. Calcula la atribución con múltiples modelos, last-touch, first-touch, lineal y position-based (40/40/20), y entrega el crédito por canal, las conversiones asistidas y una comparación lado a lado entre los modelos. Comparar cómo cada modelo redistribuye el crédito evita sobreinvertir en canales que solo cierran conversiones iniciadas por otros.
¿Cómo? Reconstruye la secuencia de touchpoints de cada cliente y aplica modelos de atribución basados en reglas: last-touch da el 100% del crédito al último canal, first-touch al primero, lineal distribuye uniformemente entre todos los canales del recorrido y position-based da 40% al primero, 40% al último y 20% repartido entre los intermedios.
Origen La atribución multi-touch orientada a datos fue formalizada por Shao y Li (2011, Data-Driven Multi-Touch Attribution Models, KDD).
Literatura de referencia
- Shao, X. & Li, L. (2011). "Data-Driven Multi-Touch Attribution Models." KDD.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
model | string | no | "linear" | Modelo principal de atribución: "last_touch", "first_touch", "linear" o "position_based" (40% primero / 40% último / 20% medio). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
conversion_id | string | sí | Identificador único que agrupa touchpoints en una misma jornada de conversión. |
channel | string | sí | Nombre del canal de marketing (ej.: email, organic, paid_search). |
touchpoint_order | integer | sí | Orden (desde 1) del touchpoint dentro de la jornada de conversión. |
conversion_value | number | no | Ingresos o valor de la conversión. Cuando está presente, el crédito se distribuye por valor y se calcula el ROI por canal. |
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/marketing_attribution/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Indicadores móviles
Propósito
Indicadores de media móvil y volatilidad (SMA, EMA, WMA, Bollinger, ROC, YoY/MoM, CAGR) sobre una serie temporal.
¿Por qué? Use este engine para leer rápidamente la dirección y la estabilidad de cualquier métrica a lo largo del tiempo, como ingresos o demanda diaria, sin armar planillas de indicadores a mano. Calcula SMA, EMA, WMA, Bollinger Bands, ROC, crecimiento YoY y MoM y CAGR, y entrega dos diagnósticos listos: la tendencia de la serie (ascendente, descendente o lateral) y la volatilidad clasificada como low, moderate o high.
¿Cómo? Los promedios móviles recorren una ventana deslizante configurable: la SMA es el promedio aritmético de la ventana, la EMA pondera exponencialmente con alpha = 2 / (window + 1) y la WMA usa pesos lineales crecientes para los valores más recientes. Las Bollinger Bands suman y restan k desviaciones estándar a la SMA, y el ROC mide la variación porcentual punto a punto. La tendencia compara el promedio de los valores recientes con el de los antiguos (más de 5% ascendente, menos de -5% descendente) y la volatilidad usa el coeficiente de variación, high por encima de 50% y moderate por encima de 20%.
Origen Los indicadores provienen del análisis técnico de series financieras consolidado por Murphy (1999, Technical Analysis of the Financial Markets); el suavizado exponencial fue introducido por Brown (1956) y las bandas de volatilidad por Bollinger (2001, Bollinger on Bollinger Bands).
Literatura de referencia
- Murphy, J. J. (1999). "Technical Analysis of the Financial Markets." New York Institute of Finance.
- Brown, R. G. (1956). "Exponential Smoothing for Predicting Demand."
- Bollinger, J. (2001). "Bollinger on Bollinger Bands." McGraw-Hill.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
window | integer | no | 7 | Tamaño de la ventana (en puntos) para SMA/EMA/WMA/Bollinger/ROC. |
indicators | array | no | ["sma","ema"] | Indicadores a calcular: cualquiera de "sma", "ema", "wma", "bollinger", "roc", "yoy", "mom". |
bollinger_k | number | no | 2 | Multiplicador de desviación estándar para el ancho de las Bandas de Bollinger. |
aggregate_dates | boolean | no | true | Suma filas con la misma fecha antes de calcular los indicadores. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
date | string | sí | Fecha de la observación; acepta strings ISO, epoch Unix (s/ms) o YYYYMMDD. |
value | number | sí | Métrica numérica a analizar (ej.: ingresos, unidades). |
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/moving_stats/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Pareto & concentración
Propósito
Análisis de Pareto/concentración: coeficiente de Gini, HHI, curva de Lorenz, punto 80/20 y clasificación ABC.
¿Por qué? Use este engine para medir cuánto está concentrado el valor en pocos ítems, productos, clientes o categorías, y fundamentar decisiones de portafolio, inventario y priorización comercial. Entrega el coeficiente de Gini (0 a 1), la curva de Lorenz, el índice HHI de concentración de mercado en la escala 0-10000, la razón 80/20 (cuántos ítems representan el 80% del valor total) y la clasificación ABC (A: top 80%, B: 80-95%, C: 95-100%). Así responde preguntas como cuántos productos sostienen los ingresos o qué tan dependiente es la empresa de pocos clientes.
¿Cómo? Agrupa las filas por item_id sumando los valores y las ordena de forma decreciente. La curva de Lorenz grafica la porción acumulada de la población contra la porción acumulada del valor, y el Gini se deriva del área bajo esa curva por la regla trapezoidal. El HHI suma los cuadrados de las participaciones de cada ítem multiplicados por 10000, la razón 80/20 encuentra el menor conjunto de ítems que alcanza el 80% del total y la clasificación ABC corta el acumulado en 80%, 95% y 100%.
Origen El principio de la concentración de valor se remonta a Pareto (1896, Cours d'Economie Politique); su aplicación gerencial, incluida la clasificación ABC, fue popularizada por Juran (1951, Quality Control Handbook).
Literatura de referencia
- Pareto, V. (1896). "Cours d'Economie Politique."
- Juran, J. M. (1951). "Quality Control Handbook." McGraw-Hill.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
top_n | integer | no | 20 | Cantidad de mayores contribuyentes en top_contributors (omitido si top_n >= total de ítems). |
abc_threshold_a | number | no | 80 | Porcentaje acumulado (0-100) hasta el cual los ítems se clasifican como "A". |
abc_threshold_b | number | no | 95 | Porcentaje acumulado (0-100) hasta el cual los ítems se clasifican como "B" (más allá, "C"). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
item_id | string | sí | Identificador de ítem/SKU/cliente para agregar. |
value | number | sí | Valor numérico de contribución (ej.: ingresos, cantidad); sumado por item_id. |
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/pareto/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Pipeline de engines
Propósito
Meta-engine que encadena varias engines en secuencia sobre el mismo conjunto de datos.
Ejecuta la engine de cada paso contra el mismo data, recolectando resumen/resultado por paso. Acepta el formato preferido steps o el legado engines + engine_params. fail_strategy controla si un paso que falla aborta el pipeline entero o se salta. Cuando join_key está definido, los registros por entidad encontrados en la salida de cada paso (arrays con claves customers/products/affiliates/items/records/entities, o el primer array de objetos encontrado) se fusionan en un único array joined, con campos prefijados por el nombre de la engine. El pipeline en sí no tiene esquema fijo de entrada: las columnas exigidas las determinan por completo las engines listadas en steps.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
steps | array | no | Formato preferido: lista ordenada de pasos {"engine": string, "params": objeto}. Obligatorio si no se da engines. | |
engines | array | no | Formato legado: lista ordenada de nombres de engines, en par con engine_params. Obligatorio si no se da steps. | |
engine_params | object | no | Formato legado: params por engine, indexados por el nombre de la engine; se usa con engines. | |
fail_strategy | string | no | "continue" | "continue" (salta un paso fallido y sigue) o "abort" (detiene el pipeline en el primer fallo). |
join_key | string | no | Campo de id de la entidad (ej.: customer_id) usado para fusionar los registros por entidad de cada paso en un único array joined. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
customer_id | string | sí | Esquema de ejemplo para los pasos rfm + loyalty usados abajo; no es un requisito fijo del pipeline. Identificador del cliente. |
purchase_date | string | sí | Esquema de ejemplo para los pasos rfm + loyalty usados abajo. Fecha de la compra (string ISO, epoch Unix o YYYYMMDD). |
amount | number | sí | Esquema de ejemplo para los pasos rfm + loyalty usados abajo. Monto de la compra. |
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/pipeline/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Estacionalidad (profunda)
Propósito
Detección de estacionalidad por FFT con aceleración dedicada y descomposición tendencia/estacional/residuo.
Ejecuta análisis espectral FFT (con aceleración dedicada y fallback en CPU) sobre la serie temporal nombrada por value_column/date_column, detecta los K mayores picos espectrales (período, potencia e interpretación legible como semanal/mensual/anual) y hace la descomposición por media móvil en tendencia/estacional/residuo con un score de fuerza estacional. Cuando group_column está definido, cada grupo se procesa como serie independiente (mín. 10 observaciones cada una); si no, el conjunto entero es una serie.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
value_column | string | sí | Nombre de la columna que lleva los valores numéricos de la serie temporal. | |
date_column | string | sí | Nombre de la columna con la fecha/datetime usada para ordenar. | |
frequency | string | no | "daily" | Etiqueta de la frecuencia de muestreo: "daily", "weekly", "monthly" u "hourly". Usada para traducir períodos detectados a días de calendario. |
top_k_periods | integer | no | 5 | Cantidad de picos espectrales en el tope del reporte. |
min_power_ratio | number | no | 0.1 | Potencia espectral mínima (relativa al pico más fuerte, 0.0-1.0) para que un pico sea reportado. |
group_column | string | no | Columna opcional para dividir los datos en series independientes (cada una necesita >= 10 observaciones). | |
random_state | integer | no | 42 | Semilla aleatoria, retornada en los parámetros de la salida (entero no negativo). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
date | string | sí | Columna de fecha/timestamp; el nombre real es el que indique date_column. Cualquier fecha/datetime interpretable, al menos 10 filas en total. |
value | number | sí | Métrica numérica a analizar; el nombre real es el que indique value_column. |
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/seasonality_deep/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Estacionalidad (FFT)
Propósito
Detección de estacionalidad por FFT con descomposición en tendencia, estacional y residuo.
¿Por qué? Use este engine para confirmar si una métrica tiene ciclos reales y de qué tamaño, información esencial para planificar inventario, equipo y campañas en torno a la estacionalidad del negocio. Entrega los períodos dominantes con interpretación automática (semanal, quincenal, mensual, trimestral, anual), la fuerza relativa de cada uno, el espectro de potencia y la descomposición de la serie en tendencia, componente estacional y residuo. Requiere al menos 10 observaciones, y con group_column analiza varias series a la vez.
¿Cómo? Quita la tendencia lineal de la serie antes que nada, porque sin eso una serie que solo sube hace que el período dominante se lea como su largo entero. De la señal sin tendencia extrae el espectro de potencia por FFT y toma como picos los máximos locales por encima de la fracción mínima del pico más fuerte. Cada frecuencia se vuelve un período, convertido a días por el intervalo de muestreo indicado e interpretado por rangos: de 6,5 a 7,5 días es semanal, de 13,5 a 14,5 quincenal, de 29 a 32 mensual, de 88 a 93 trimestral y de 360 a 370 anual. La tendencia viene de una media móvil centrada con ventana igual al período dominante, el componente estacional es el patrón medio que queda y el residuo es lo que ninguno de los dos explica; la fuerza estacional es 1 menos la razón entre la varianza del residuo y la de la serie sin tendencia.
Origen El algoritmo de FFT fue publicado por Cooley y Tukey (1965, An Algorithm for the Machine Calculation of Complex Fourier Series, Mathematics of Computation).
Literatura de referencia
- Cooley, J. W. & Tukey, J. W. (1965). "An Algorithm for the Machine Calculation of Complex Fourier Series." Mathematics of Computation, 19(90), 297-301.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
data_frequency | string | no | "daily" | Intervalo de muestreo; la grafía anterior de frequency. Uno entre "daily", "weekly" y "monthly". Los valores "quarterly", "yearly" y un número puro de días se rechazan en vez de leerse como el predeterminado: un intervalo leído mal devuelve un espectro de períodos que parece plausible y no lo es. Omitirlo significa "daily"; ya no se infiere de los intervalos entre las fechas. |
top_k_periods | integer | no | 5 | Cantidad de picos espectrales reportados, ordenados por potencia. Entero positivo. |
min_power_ratio | number | no | 0.1 | Potencia espectral mínima relativa al pico más fuerte, entre 0.0 y 1.0, para que un pico se reporte. |
group_column | string | no | Columna que divide la entrada en series independientes, cada una analizada por sí sola y cada una necesitando al menos 10 observaciones. Omitida, toda la entrada es una sola serie. | |
random_state | integer | no | 42 | Semilla aleatoria, devuelta en los parámetros del resultado. Entero no negativo. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
date | string | sí | Fecha de la observación. La serie se analiza en el orden en que llegan las filas, así que envíelas ya ordenadas por fecha: una fecha en texto, que es lo que producen data[] inline y CSV, no se reinterpreta para reordenar nada. Los valores ausentes se repiten de la fila anterior antes del análisis. Al menos 10 filas. |
value | number | sí | Métrica numérica a analizar. |
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/seasonality_fft/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Atribución de Shapley
Propósito
Atribución de marketing multi-touch con valores de Shapley (teoría de juegos).
Agrupa touchpoints en conjuntos de canales por conversión (ordenados por touchpoint_order) y calcula el valor de Shapley de cada canal, el reparto de crédito matemáticamente justo que satisface los axiomas de eficiencia, simetría, linealidad y jugador nulo. Usa cálculo exacto para <= 12 canales únicos y muestreo de permutaciones Monte Carlo por encima. También devuelve comparaciones con los modelos last-touch/linear y efectos de sinergia/redundancia entre pares de canales.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
approximation_samples | integer | no | 10000 | Muestras de permutación Monte Carlo usadas cuando hay más de 12 canales únicos; entre 100 y 50000. |
normalize | boolean | no | true | Reescala los valores de Shapley para que sumen el valor total de conversión. |
include_interaction_effects | boolean | no | true | Calcula sinergia/redundancia entre pares de los principales canales. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
conversion_id | string | sí | Identificador único que agrupa touchpoints en una misma jornada de conversión. |
channel | string | sí | Nombre del canal de marketing. Al menos 2 canales únicos en el conjunto. |
touchpoint_order | integer | sí | Orden (desde 1) del touchpoint dentro de la jornada. |
converted | integer | sí | 1 si la jornada convirtió, 0 en caso contrario. Al menos una jornada convertida. |
conversion_value | number | no | Ingresos o valor de la conversión; por defecto 1.0 por jornada convertida cuando se omite. |
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/shapley_attribution/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"