GET /v1/analytics/briefing: alertas, excepciones de entrega, aprobaciones pendientes, consumo y tiempos de ciclo. muveya genera el archivo en segundo plano, así que el flujo tiene tres pasos: pedirlo, consultar su estado y descargarlo.
POST /v1/analytics/exports es la única operación de /v1 que escribe algo, y lo que escribe es el propio trabajo de exportación. No cambia nada de tu operación.
Quién puede hacerlo
Una clave con el scopeanalytics:read (consulta Scopes). El mismo scope cubre pedir, consultar y descargar.
El flujo
Paso 1: pide la exportación
string
predeterminado:"daily"
La periodicidad del resumen:
daily o weekly. Cualquier otro valor se rechaza con 400 y el código common.invalid_request. El cuerpo es opcional; sin él obtienes un resumen diario. No envíes ningún otro campo.string
predeterminado:"en"
El idioma de la columna
label del CSV: en, es o pt. Queda fijado al pedir la exportación, porque el archivo se genera después. Las claves de métricas, dimensiones, unidades, valores e ids de evidencia son iguales en todos los idiomas.202 Accepted
exportId: es la única referencia al trabajo.
Esta operación no tiene clave de idempotencia. Cada
POST crea un trabajo de exportación nuevo e independiente. Si una solicitud vence antes de que recibas el exportId, envíala de nuevo; el trabajo adicional no causa problemas y se elimina junto con los demás a los 7 días.Paso 2: consulta hasta que esté lista
Llama aGET /v1/analytics/exports/{exportId} cada pocos segundos (por ejemplo, cada 3 segundos). Cada consulta cuenta para tu presupuesto de solicitudes (consulta Límites de uso).
200 OK (building)
200 OK (ready)
string
requerido
El id del trabajo que recibiste al pedir la exportación.
string
requerido
pending, building, ready o failed.string
requerido
El reporte que contiene el archivo. Hoy siempre es
briefing.string
requerido
daily o weekly, según lo pedido.integer
El tamaño del archivo en bytes. Aparece cuando el estado es
ready.string
El SHA-256 del archivo, en 64 caracteres hexadecimales en minúscula. Aparece cuando el estado es
ready.string
Un enlace de descarga firmado. Aparece solo cuando el estado es
ready. Cada consulta emite un enlace nuevo.string
Cuándo deja de funcionar el
downloadUrl actual (UTC).string
Un motivo legible por máquina. Aparece cuando el estado es
failed. Un trabajo que falló una vez y se reintentó automáticamente conserva este campo mientras está en building y después de pasar a ready, así que revisa siempre status primero.Paso 3: descarga y verifica
- El
downloadUrlfunciona durante 5 minutos después de la consulta que lo devolvió. Lleva su propia firma: no agregues tu clave de API ni ningún otro encabezado a la solicitud de descarga. - Descarga de inmediato. No guardes ni compartas el enlace: mientras sea válido, cualquiera que lo tenga puede descargar el archivo. Si venció, vuelve a consultar el trabajo para obtener un enlace nuevo.
- El archivo se llama
management-briefing-daily.csvomanagement-briefing-weekly.csv. - Compara el SHA-256 de los bytes recibidos con
checksum, y su tamaño conbyteSize. Si no coinciden, vuelve a descargar.
Ejemplo completo
El archivo CSV
- Codificación UTF-8 con marca de orden de bytes, para que las hojas de cálculo muestren bien las tildes. Las líneas terminan en CRLF.
- Una fila de encabezado y luego una fila por cada cifra del resumen.
- Las celdas que contienen una coma, una comilla o un salto de línea van entre comillas. Una celda que empieza con
=,+,-,@, una tabulación o un retorno de carro lleva delante una comilla simple ('), para que una hoja de cálculo nunca la ejecute como fórmula.
management-briefing-weekly.csv (extracto, Accept-Language: es)
GET /v1/analytics/briefing para el mismo período en el momento en que se generó el archivo. El nombre de cada insumo aparece tal como está en tu catálogo. Para saber qué significa cada métrica, consulta Analítica de gestión.
Lo que el archivo nunca contiene
La exportación omite datos sensibles por diseño: contiene conteos, cantidades, duraciones, etiquetas e ids de evidencia. Nunca contiene costos, valores de pedidos, referencias de pacientes ni nombres de miembros del equipo. Cubre todas las sedes y bodegas de la clínica dental, como cualquier otra lectura con clave de API.Qué registra muveya
- Cada solicitud queda en la auditoría de tu clínica dental, con la clave de API como autora, el tipo de reporte y el período.
- Cuando se genera el archivo, la auditoría también registra su tamaño y su checksum SHA-256, para que luego puedas comparar el archivo que tienes con el registro.
- Los trabajos de exportación se conservan 7 días desde la solicitud. Después, consultar el trabajo devuelve
404con el códigocommon.not_found: pide una exportación nueva.
Si el archivo no se genera
Si las exportaciones nuevas siguen fallando, escribe a team@muveya.com con el
exportId.