Skip to main content
Una exportación del resumen gerencial es un archivo CSV con el mismo resumen que devuelve 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 scope analytics: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
Guarda el 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 a GET /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 downloadUrl funciona 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.csv o management-briefing-weekly.csv.
  • Compara el SHA-256 de los bytes recibidos con checksum, y su tamaño con byteSize. 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)
Las cifras son las mismas que devuelve 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 404 con el código common.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.

Errores

Páginas relacionadas