Ventas & Tendencias Documentación
Visión general
Matriz BCG, distribución por categoría, demografía y preferencias de compra.
Esta referencia cubre 5 engines. Cada endpoint trae ruta, permiso, parámetros, respuesta y los errores posibles.
Matriz BCG
Propósito
Clasificación en matriz BCG de crecimiento-participación: Stars/Cash Cows/Opportunities/Problems.
¿Por qué? Clasifica productos o categorías en los cuadrantes de la matriz BCG (Stars, Cash Cows, Opportunities, Problems), orientando decisiones de asignación de recursos y gestión de portafolio. El resultado muestra dónde invertir, cosechar o replantear, con base en el desempeño reciente de cada ítem.
¿Cómo? Selecciona los dos períodos más recientes y agrega el ingreso por ítem. Calcula el crecimiento de ventas (((ingreso_actual - ingreso_anterior) / ingreso_anterior) * 100) y el market share porcentual, y combina crecimiento y variación de share para posicionar cada ítem en un cuadrante.
Origen La matriz de portafolio fue creada por Henderson (1970) en "The Product Portfolio", publicado por el Boston Consulting Group.
Literatura de referencia
- Henderson, B. D. (1970). "The Product Portfolio." Boston Consulting Group.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
growth_threshold | string | no | "auto" | Modo del umbral de crecimiento: "auto" (crecimiento general del mercado), "median" (mediana del crecimiento de los ítems) o un porcentaje numérico fijo. |
share_threshold | string | no | "average" | Modo del umbral de participación: "average" (participación promedio de los ítems), "median" (mediana) o un porcentaje numérico fijo. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
item_id | string | sí | Identificador del producto/ítem/categoría. |
item_name | string | sí | Nombre legible del ítem mostrado en los resultados. |
period | string | sí | Etiqueta del período (ej.: trimestre o mes). Al menos 2 valores distintos; los dos más recientes (lexicográficamente) se comparan. |
revenue | number | sí | Ingresos del ítem en el período. |
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/bcg_matrix/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Distribución por categoría
Propósito
Detalle categórico genérico con conteos, porcentajes y tabulación cruzada opcional.
Agrupa las filas por la columna group_by y reporta conteo/porcentaje por categoría, agrupando las categorías de baja participación o cola larga en un balde "Others". Opcionalmente suma/promedia una value_column por categoría y construye una matriz de tabulación cruzada cross_by. Los nombres de las columnas agrupadas son configurables vía params, no fijos por la engine.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
group_by | string | sí | Nombre de la columna para agrupar y contar. Debe existir en las filas. | |
cross_by | string | no | Nombre de una segunda columna a cruzar contra group_by (produce una matriz de conteos group_by x cross_by). Omitir para saltarse la tabulación cruzada. | |
value_column | string | no | Nombre de una columna numérica a sumar/promediar por categoría, además de los conteos. Omitir para solo conteos. | |
top_n | integer | no | 50 | Máximo de categorías reportadas individualmente; el resto va a "Others". |
min_pct | number | no | 0 | Participación porcentual mínima para que una categoría se reporte individualmente; por debajo va a "Others". |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
category | string | no | Columna de agrupamiento de ejemplo, referenciada por el param group_by en este ejemplo. El nombre real es el que nombre group_by; la engine falla con MissingColumn si está ausente. |
region | string | no | Columna secundaria de ejemplo, referenciada por el param cross_by. Necesaria solo cuando cross_by está definido. |
revenue | number | no | Columna numérica de ejemplo, referenciada por el param value_column. Necesaria solo cuando value_column está definido. |
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/category_distribution/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Análisis demográfico
Propósito
Detalle demográfico de clientes por edad, género y afinidad género-categoría.
¿Por qué? Traza el perfil demográfico de la base de clientes, revelando quién compra qué. Entrega la distribución etaria en seis rangos (18-24 hasta 65+), la distribución por género con ingreso y ticket promedio, el índice de afinidad género-categoría y los datos de flujo listos para un diagrama Sankey, sustentando la segmentación de campañas y las decisiones de surtido.
¿Cómo? Agrega conteo, ingreso y ticket promedio por rango etario y la distribución por género con clientes únicos. El índice de afinidad es el porcentaje del género en la categoría dividido por el porcentaje del género en la base, y el flujo género-categoría alimenta la visualización Sankey.
Origen La segmentación de mercado fue formalizada por Smith (1956) en "Product Differentiation and Market Segmentation as Alternative Marketing Strategies" (Journal of Marketing), y el índice de afinidad es un estándar consolidado de la planificación de medios.
Literatura de referencia
- Smith, W. R. (1956). "Product Differentiation and Market Segmentation as Alternative Marketing Strategies." Journal of Marketing.
- Affinity Index - media planning standard.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
level | string | no | "category" | Nivel de agrupamiento de la matriz de afinidad y del flujo: "category" (por defecto) o "product" (usa product_name si está presente, si no product_id, si no cae en category). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
customer_id | string | sí | Identificador del cliente, usado para contar clientes únicos por balde. |
gender | string | sí | Etiqueta de género del cliente. |
category | string | sí | Categoría del producto/compra. Usada directamente cuando level="category"; también el fallback cuando level="product" y no hay columna de producto. |
amount | number | sí | Monto de la transacción, sumado en las métricas de ingresos por balde. |
age | integer | no | Edad del cliente. Cuando está presente, habilita la distribución por rangos etarios (18-24, 25-34, 35-44, 45-54, 55-64, 65+); omitida por completo en caso contrario. |
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/demographic_analysis/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Preferencias de compra
Propósito
Análisis de preferencias de compra por categoría: horario, método de pago y día de la semana.
¿Por qué? Analiza patrones temporales de compra por categoría y preferencias de medio de pago, identificando la hora pico de cada categoría y el método de pago dominante. Es ideal para marketing dirigido por franja horaria, optimización de planograma y negociación con proveedores de pago.
¿Cómo? Realiza binning temporal por categoría con intensidad en slots de 2 horas y calcula el porcentaje por slot, generando un heatmap categoría x horario. Detecta la hora pico de cada categoría y determina la distribución de métodos de pago con conteo y porcentaje.
Origen El método sigue la metodología consolidada de retail analytics, con heatmaps como visualización estándar de patrones temporales.
Literatura de referencia
- Retail analytics methodology. Heatmap visualization for temporal patterns.
Parámetros (params)
Esta engine no recibe params: envía solo data[].
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
category | string | sí | Categoría del producto/compra. |
purchase_datetime | string | sí | Timestamp de la compra: string datetime (YYYY-MM-DD HH:MM:SS), ISO 8601/RFC 3339 o epoch Unix (s/ms). Los valores solo-fecha quedan fuera de los rangos horarios pero cuentan en la distribución semanal. |
payment_method | string | sí | Método de pago de la transacción (ej.: Credit Card, PIX). |
amount | number | no | Monto de la transacción. Cuando está ausente, las métricas de ingresos se reportan como 0. |
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/purchase_preferences/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Distribución horaria
Propósito
Distribución horaria de transacciones en rangos configurables, con detección de horas pico.
¿Por qué? Analiza la distribución de transacciones a lo largo del día, identificando las horas pico primaria y secundaria. Es fundamental para dimensionar el equipo por turno, planificar inventario y programar promociones en los horarios de mayor movimiento.
¿Cómo? Extrae la hora de cada transacción y aplica un binning temporal configurable (bin_index = floor(hora / bin_size), por defecto de 2 horas). Produce la distribución porcentual por bin y detecta los picos ordenando los conteos de forma descendente.
Origen El histograma como representación de distribuciones se remonta a Pearson (1895) en "Contributions to the Mathematical Theory of Evolution", y la aplicación sigue la metodología consolidada de retail analytics.
Literatura de referencia
- Pearson, K. (1895). Contributions to the Mathematical Theory of Evolution.
- Retail analytics methodology.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
bin_size_hours | integer | no | 2 | Tamaño de cada rango horario en horas; ajustado al divisor válido de 24 más cercano (1, 2, 3, 4, 6, 8, 12). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
purchase_datetime | string | no | Timestamp de la compra: string datetime, ISO 8601/RFC 3339 o epoch Unix (s/ms). Obligatorio si purchase_hour está ausente. Los valores solo-fecha quedan fuera de la distribución. |
purchase_hour | integer | no | Hora del día (0-23) de la compra. Obligatoria si purchase_datetime está ausente; tiene precedencia cuando ambas están presentes. |
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/time_distribution/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"