Analítica de gestión

muveya calcula un conjunto cerrado de métricas de gestión a partir de tus registros operativos: alertas de existencias, entregas, pedidos, aprobaciones, custodia y consumo. Esta página define cada una en palabras simples e indica dónde puedes leerla. Todas comparten las mismas reglas:

• Solo lectura y en vivo. Una métrica se calcula cuando la pides, con los registros actuales. No se guarda ni se almacena en caché, salvo el archivo CSV de una exportación.
• Deterministas. Los mismos registros dan la misma cifra. Ninguna IA calcula ni reescribe una cifra.
• Solo conteos, cantidades y duraciones. Ninguna métrica incluye costos, valores de pedidos ni referencias de pacientes.
• La misma cifra en todas partes. La consola, la API pública y MCP ejecutan el mismo cálculo, así que la misma pregunta obtiene el mismo número en cada superficie.
• UTC. Toda fecha, ventana y agrupación está en UTC.

​

Dónde vive cada capacidad

Hoy, la consola tiene una sola pantalla de analítica: Reporte de consumo. Todo lo demás se lee mediante la API pública con una clave de API o mediante MCP con OAuth. No hay pantalla en la consola para las demás métricas, para las exportaciones ni para crear claves de API; para obtener una clave, escribe a team@muveya.com. Para los detalles técnicos de cada superficie, consulta Exportaciones y Herramientas MCP.

​

Quién puede leerlas

reports.read es suficiente: una métrica lee los pedidos, entregas y existencias subyacentes en tu nombre solo para contarlos, y nunca devuelve un campo que no podrías leer de otra forma. Una clave de API cubre todas las sedes y bodegas de su cuenta de clínica dental. Un miembro de la consola limitado a algunas bodegas ve el consumo solo de esas bodegas.

​

Campos que comparten los resultados

La mayoría de los resultados incluye estos campos. La forma exacta de cada operación está en la referencia de la API. Un value igual a null significa que no hubo muestra para calcular un porcentaje, una mediana o un promedio. Nunca se reemplaza por cero.

​

Límites de lectura

​

Métricas operativas

GET /v1/analytics/metrics/{metric} devuelve una cifra única. {metric} debe ser uno de estos ocho ids; cualquier otro valor se rechaza con 400 y common.invalid_request.

​

Conteos instantáneos

Describen la situación actual. catalogItemId limita los dos conteos de existencias a un insumo.

​

Señales piloto

Estas tres agregan numerator, denominator y sampleCount cuando aplican, una definition y advertencias legibles por máquina en caveats. Una ventana cuyo from no es anterior a to, o una fecha que no se puede leer, se rechaza con 400. El resultado incluye period solo cuando envías from y to.

​

Excepciones operativas

GET /v1/analytics/exceptions lista los problemas sobre los que un gerente debe actuar, del más urgente al menos urgente. catalogItemId limita las excepciones de existencias a un insumo. Cada entrada tiene además priority, un evidenceId propio y, en las alertas de existencias, detectedAt. Las entradas se ordenan por prioridad y luego por id de detalle. El reporte agrega total. Para seguir un detalle con la misma clave:

• order: GET /v1/orders/{orderId} y GET /v1/fulfillments/{orderId}.
• movement: el movimiento aparece en GET /v1/inventory/boxes/{boxId}/movements, con el boxId de reference.
• item: GET /v1/catalog/items/{itemId}.

Cada una de esas operaciones necesita su propio scope. Consulta Scopes.

​

Comparación de sedes

GET /v1/analytics/clinics/comparison (métrica ORDERS_BY_CLINIC, unidad orders) ordena las sedes de tu cuenta por volumen de pedidos. Las sedes se ordenan por totalOrders, de mayor a menor, y luego por id. Nunca se incluyen valores de pedidos.

​

Tendencia de consumo

GET /v1/analytics/consumption-trend (métrica CONSUMPTION_TREND) es el cálculo detrás del Reporte de consumo de la consola. La ventana debe tener from antes de to y abarcar como máximo 366 días; si no, 400. El resultado tiene una entrada en series por insumo y unidad (seriesKey es catalogItemId:unitOfMeasure), con totalConsumed, usedQuantity (uso observado), issuedQuantity (lo entregado a boxes o áreas que no cuentan sus existencias, un consumo estimado) y movementCount, además de buckets por día o semana. usedQuantity + issuedQuantity = totalConsumed. Nunca hay un total entre insumos o unidades. coverage indica qué representan las cifras: measuredMovementCount, unverifiedMovementCount (registros anteriores a la unidad verificada, contados pero no cuantificados, listados por insumo en unverifiedItems), warehouseScope (all o restricted) y coveredFrom cuando la lectura se cortó. Se incluye una narration solo si pasa la verificación de que cada número coincide con la tabla.

​

Pendientes de aprobación

GET /v1/analytics/approval-backlog (métrica APPROVAL_BACKLOG, unidad orders) cuenta los pedidos que esperan aprobación en toda la cuenta, agrupados por el tiempo que llevan esperando desde su solicitud. También devuelve total y oldestSubmittedAt. Para la bandeja propia de quien aprueba, consulta Aprobación de pedidos.

​

Tiempo de ciclo del pedido

GET /v1/analytics/cycle-time (métrica ORDER_CYCLE_TIME, unidad hours) da la duración promedio de cada etapa de la vida de un pedido, sobre los pedidos que llegaron a esa etapa. Cada etapa tiene averageHours (dos decimales, null cuando ningún pedido llegó a ella) y sampleCount. observedFulfillments es la cantidad de entregas leídas. El promedio no se limita a una ventana. Consulta Confirmar la entrega, recibir y cerrar.

​

Resumen gerencial

GET /v1/analytics/briefing (métrica MANAGEMENT_BRIEFING) es un resumen reproducible que reúne las métricas anteriores en una lista plana de cifras. period es daily (por defecto) o weekly; cualquier otro valor es 400. Cada cifra tiene metric (su origen), dimension (la subclave, ausente en una cifra única), label, value, unit y el evidenceId de su origen. Las cifras llegan en este orden: Qué cambia con period:

• La parte de consumo siempre cubre la ventana por defecto de la métrica de consumo, los últimos 30 días. daily la agrupa por día y weekly por semana. Como el resumen lista totales, hoy las cifras de un resumen diario y de uno semanal son las mismas; solo cambia el evidenceId del consumo.
• Los conteos instantáneos, los tramos de espera y el tiempo de ciclo no se limitan a un día ni a una semana.

Las etiquetas siguen el idioma de quien lee: el encabezado Accept-Language en la API (en, es o pt; inglés en otro caso) y el encabezado Accept-Language en MCP, con inglés como alternativa. Los ids, dimensiones, unidades, valores y evidenceId nunca cambian con el idioma. Un insumo que el catálogo no puede nombrar se etiqueta Insumo desconocido. El evidenceId propio del resumen es MANAGEMENT_BRIEFING:period=daily o MANAGEMENT_BRIEFING:period=weekly, y truncated es true si alguno de sus orígenes quedó truncado. En MCP, management.briefing devuelve este resumen junto con las excepciones operativas.

​

Exportaciones CSV

El resumen se puede exportar como archivo CSV. Las exportaciones se solicitan y se recogen solo mediante la API pública. Las formas completas de solicitud y respuesta están en Exportaciones.

​

Estados de la exportación

​

Reglas

• Vencimiento. Un trabajo de exportación se conserva 7 días. Después, GET /v1/analytics/exports/{exportId} responde 404. Un enlace de descarga dura 5 minutos y nunca es permanente.
• Aislamiento. Un exportId solo funciona con una clave de la misma cuenta de clínica dental. Cualquier otro id responde 404, sin decir si existe en otra parte.
• Omisión de datos. El archivo contiene solo conteos, cantidades, duraciones, etiquetas e ids de evidencia. No puede contener costos, valores de pedidos ni referencias de pacientes.
• Formato. UTF-8 con marca de orden de bytes (para que las hojas de cálculo lean bien los acentos), fin de línea CRLF y las columnas metric, dimension, label, value, unit, evidenceId. Una cifra sin muestra tiene la celda value vacía, nunca 0. Una celda que empieza con =, +, -, @, una tabulación o un retorno de carro lleva un apóstrofo delante, para que una hoja de cálculo nunca la ejecute como fórmula.
• Auditoría. Cada solicitud escribe el registro de auditoría analytics.export. Un archivo terminado escribe analytics.export_built con su checksum y tamaño, que perdura más allá de los 7 días del trabajo. Una clave sin analytics:read se rechaza con 403 antes de solicitar la exportación, y ese rechazo no escribe ningún registro de auditoría.

​

Qué puede salir mal

El formato completo de los errores está en Errores.

​

Páginas relacionadas