Análises gerenciais

O muveya calcula um conjunto fechado de métricas gerenciais a partir dos seus registros operacionais: alertas de estoque, entregas, pedidos, aprovações, custódia e consumo. Esta página define cada uma em palavras simples e indica onde você pode lê-la. Todas seguem as mesmas regras:

• Somente leitura e ao vivo. Uma métrica é calculada quando você a solicita, com os registros atuais. Nada fica em cache nem é armazenado, exceto o arquivo CSV de uma exportação.
• Determinísticas. Os mesmos registros geram o mesmo número. Nenhuma IA calcula ou reescreve um número.
• Apenas contagens, quantidades e durações. Nenhuma métrica traz custos, valores de pedidos ou referências de pacientes.
• O mesmo número em todo lugar. O console, a API pública e o MCP executam o mesmo cálculo, então a mesma pergunta recebe o mesmo número em cada superfície.
• UTC. Toda data, janela e agrupamento está em UTC.

​

Onde fica cada capacidade

Hoje, o console tem uma única tela de análises: Relatório de consumo. Todo o resto é lido pela API pública com uma chave de API ou pelo MCP com OAuth. Não há tela no console para as demais métricas, para as exportações nem para criar chaves de API; para obter uma chave, escreva para team@muveya.com. Para os detalhes técnicos de cada superfície, veja Exportações do resumo gerencial e Ferramentas MCP.

​

Quem pode ler

reports.read é suficiente: uma métrica lê os pedidos, entregas e estoque subjacentes em seu nome apenas para contá-los, e nunca retorna um campo que você não poderia ler de outra forma. Uma chave de API cobre todas as unidades e depósitos da sua conta de clínica odontológica. Um membro do console limitado a alguns depósitos vê o consumo apenas desses depósitos.

​

Campos que os resultados compartilham

A maioria dos resultados traz estes campos. O formato exato de cada operação está na referência da API. Um value igual a null significa que não houve amostra para calcular uma porcentagem, mediana ou média. Nunca é substituído por zero.

​

Limites de leitura

​

Métricas operacionais

GET /v1/analytics/metrics/{metric} retorna um único número. {metric} precisa ser um destes oito ids; qualquer outro valor é recusado com 400 e common.invalid_request.

​

Contagens instantâneas

Descrevem a situação atual. catalogItemId limita as duas contagens de estoque a um insumo.

​

Sinais piloto

Estas três acrescentam numerator, denominator e sampleCount quando se aplicam, uma definition e ressalvas legíveis por máquina em caveats. Uma janela cujo from não é anterior a to, ou uma data que não pode ser lida, é recusada com 400. O resultado inclui period apenas quando você envia from e to.

​

Exceções operacionais

GET /v1/analytics/exceptions lista os problemas sobre os quais um gestor deve agir, do mais urgente ao menos urgente. catalogItemId limita as exceções de estoque a um insumo. Cada entrada também tem priority, um evidenceId próprio e, nos alertas de estoque, detectedAt. As entradas são ordenadas por prioridade e depois pelo id de detalhamento. O relatório acrescenta total. Para seguir um detalhamento com a mesma chave:

• order: GET /v1/orders/{orderId} e GET /v1/fulfillments/{orderId}.
• movement: o movimento aparece em GET /v1/inventory/boxes/{boxId}/movements, usando o boxId de reference.
• item: GET /v1/catalog/items/{itemId}.

Cada uma dessas operações precisa do seu próprio escopo. Veja Escopos.

​

Comparação de unidades

GET /v1/analytics/clinics/comparison (métrica ORDERS_BY_CLINIC, unidade orders) classifica as unidades da sua conta pelo volume de pedidos. As unidades são ordenadas por totalOrders, da maior para a menor, e depois pelo id. Valores de pedidos nunca são incluídos.

​

Tendência de consumo

GET /v1/analytics/consumption-trend (métrica CONSUMPTION_TREND) é o cálculo por trás do Relatório de consumo do console. A janela precisa ter from antes de to e cobrir no máximo 366 dias; caso contrário, 400. O resultado tem uma entrada em series por insumo e unidade de medida (seriesKey é catalogItemId:unitOfMeasure), com totalConsumed, usedQuantity (uso observado), issuedQuantity (o que foi entregue a salas ou áreas que não contam seu estoque, um consumo estimado) e movementCount, além de buckets por dia ou semana. usedQuantity + issuedQuantity = totalConsumed. Nunca há um total entre insumos ou unidades de medida. coverage informa o que os números representam: measuredMovementCount, unverifiedMovementCount (registros anteriores à unidade verificada, contados mas não quantificados, listados por insumo em unverifiedItems), warehouseScope (all ou restricted) e coveredFrom quando a leitura foi cortada. Uma narration é incluída apenas se passar na conferência de que cada número coincide com a tabela.

​

Fila de aprovação

GET /v1/analytics/approval-backlog (métrica APPROVAL_BACKLOG, unidade orders) conta os pedidos que aguardam aprovação em toda a conta, agrupados pelo tempo de espera desde a solicitação. Também retorna total e oldestSubmittedAt. Para a caixa de entrada de quem aprova, veja Aprovar ou rejeitar pedidos.

​

Tempo de ciclo do pedido

GET /v1/analytics/cycle-time (métrica ORDER_CYCLE_TIME, unidade hours) informa a duração média de cada etapa da vida de um pedido, sobre os pedidos que chegaram a essa etapa. Cada etapa tem averageHours (duas casas decimais, null quando nenhum pedido chegou a ela) e sampleCount. observedFulfillments é a quantidade de entregas lidas. A média não é limitada a uma janela. Veja Entrega e recebimento.

​

Resumo gerencial

GET /v1/analytics/briefing (métrica MANAGEMENT_BRIEFING) é um resumo reproduzível que reúne as métricas acima em uma lista simples de números. period é daily (padrão) ou weekly; qualquer outro valor é 400. Cada número tem metric (sua origem), dimension (a subchave, ausente em um número único), label, value, unit e o evidenceId da origem. Os números chegam nesta ordem: O que period muda:

• A parte de consumo sempre cobre a janela padrão da métrica de consumo, os últimos 30 dias. daily a agrupa por dia e weekly por semana. Como o resumo lista totais, hoje os números de um resumo diário e de um semanal são os mesmos; só muda o evidenceId do consumo.
• As contagens instantâneas, as faixas de espera e o tempo de ciclo não são limitados a um dia nem a uma semana.

Os rótulos seguem o idioma de quem lê: o cabeçalho Accept-Language na API (en, es ou pt; inglês nos demais casos) e o cabeçalho Accept-Language no MCP, com inglês como alternativa. Ids, dimensões, unidades, valores e evidenceId nunca mudam com o idioma. Um insumo que o catálogo não consegue nomear recebe o rótulo Insumo desconhecido. O evidenceId do próprio resumo é MANAGEMENT_BRIEFING:period=daily ou MANAGEMENT_BRIEFING:period=weekly, e truncated é true se alguma das origens foi truncada. No MCP, management.briefing retorna este resumo junto com as exceções operacionais.

​

Exportações CSV

O resumo pode ser exportado como arquivo CSV. As exportações são solicitadas e obtidas apenas pela API pública. Os formatos completos de solicitação e resposta estão em Exportações do resumo gerencial.

​

Estados da exportação

​

Regras

• Expiração. Um trabalho de exportação é mantido por 7 dias. Depois disso, GET /v1/analytics/exports/{exportId} responde 404. Um link de download dura 5 minutos e nunca é permanente.
• Isolamento. Um exportId só funciona com uma chave da mesma conta de clínica odontológica. Qualquer outro id responde 404, sem dizer se existe em outro lugar.
• Omissão de dados. O arquivo contém apenas contagens, quantidades, durações, rótulos e ids de evidência. Não pode conter custos, valores de pedidos nem referências de pacientes.
• Formato. UTF-8 com marca de ordem de bytes (para que as planilhas leiam os acentos corretamente), quebras de linha CRLF e as colunas metric, dimension, label, value, unit, evidenceId. Um número sem amostra tem a célula value vazia, nunca 0. Uma célula que começa com =, +, -, @, tabulação ou retorno de carro recebe um apóstrofo na frente, para que a planilha nunca a execute como fórmula.
• Auditoria. Cada solicitação grava o evento de auditoria analytics.export. Um arquivo concluído grava analytics.export_built com seu checksum e tamanho, que permanece além dos 7 dias do trabalho. Uma chave sem analytics:read é recusada com 403 antes de a exportação ser solicitada, e essa recusa não grava nenhum evento de auditoria.

​

O que pode dar errado

O formato completo dos erros está em Erros.

​

Páginas relacionadas