> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Análises gerenciais
> Cada métrica gerencial que o muveya calcula, o que significa e onde lê-la: console, API pública, MCP ou exportação CSV.
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](/docs/pt/reports/consumption). 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](mailto:team@muveya.com).
| Capacidade | Console | API pública | Ferramenta MCP |
| - | - | - | - |
| Métricas operacionais (8 ids) | Não | `GET /v1/analytics/metrics/{metric}` | Não como ferramenta. As cinco contagens instantâneas estão dentro de `management.briefing`. |
| Exceções operacionais | Não | `GET /v1/analytics/exceptions` | Dentro de `management.briefing` |
| Comparação de unidades | Não | `GET /v1/analytics/clinics/comparison` | `management.compare_clinics` |
| Tendência de consumo | **Relatórios** | `GET /v1/analytics/consumption-trend` | `analytics.consumption` |
| Fila de aprovação | Não | `GET /v1/analytics/approval-backlog` | Não como ferramenta. Suas faixas estão dentro de `management.briefing`. |
| Tempo de ciclo do pedido | Não | `GET /v1/analytics/cycle-time` | Não como ferramenta. Suas etapas estão dentro de `management.briefing`. |
| Resumo gerencial | Não | `GET /v1/analytics/briefing` | `management.briefing` |
| Exportação CSV do resumo | Não | `POST /v1/analytics/exports`, `GET /v1/analytics/exports/{exportId}` | Não |
Para os detalhes técnicos de cada superfície, veja [Exportações do resumo gerencial](/docs/pt/api-reference/exports) e [Ferramentas MCP](/docs/pt/mcp/tools).
## Quem pode ler
| Superfície | O que você precisa |
| - | - |
| Console | A permissão de membro `reports.read` (**Ver relatórios**). Nenhuma função a inclui; ela é concedida em **Equipe**. |
| API pública | Uma chave de API com o escopo `analytics:read`. O muveya o traduz para `reports.read`. Veja [Escopos](/docs/pt/api-reference/scopes). |
| MCP | Uma conexão OAuth com `analytics:read`, sujeita à permissão `reports.read` do membro. Veja [Conectar um cliente](/docs/pt/mcp/connect). |
`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.
| Campo | Significado |
| - | - |
| `metric` | O id da métrica, por exemplo `LOW_STOCK` ou `ORDER_CYCLE_TIME`. |
| `definition` | A definição em palavras, sempre em inglês. Aparece em todos os relatórios, exceto na lista de exceções, e nas três métricas piloto. |
| `unit` | `count`, `percent`, `hours`, `orders` ou uma unidade de medida no consumo. |
| `asOf` | Quando o número foi calculado. |
| `freshness` | Sempre `live`. |
| `timezone` | Sempre `UTC`. |
| `evidenceId` | Uma descrição estável da métrica e dos seus filtros, por exemplo `CONSUMPTION_TREND:catalogItemId=...,granularity=week`. A mesma solicitação sempre cita o mesmo `evidenceId`, então você pode reproduzir e citar um número. Nunca contém o horário em que o número foi calculado (`asOf`), mas inclui o `from` ou `to` que você enviar. |
| `truncated` | `true` quando uma leitura atingiu seu limite. O número é então um mínimo, nunca um resultado completo silencioso. |
| `filters` | Os filtros aplicados. |
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
| O que é lido | Limite | Ao atingir o limite |
| - | - | - |
| Alertas de estoque abertos | 500 alertas | `truncated: true` |
| Pedidos e entregas | 10.000 registros (200 por página, 50 páginas), do mais antigo ao mais recente | `truncated: true`; os registros mais recentes ficam de fora |
| Pedidos pendentes para as faixas de aprovação | 1.000 pedidos, do mais antigo ao mais recente | `truncated: true`; os pendentes mais recentes ficam de fora |
| Movimentos de consumo | 5.000 movimentos, do mais recente ao mais antigo | `truncated: true` e `coverage.coveredFrom` |
## 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.
| Id | Definição | Unidade |
| - | - | - |
| `LOW_STOCK` | Quantidade de alertas de estoque baixo abertos neste momento (um insumo abaixo do mínimo). | `count` |
| `EXPIRING_STOCK` | Quantidade de alertas de validade abertos neste momento (caixas perto da data de validade). | `count` |
| `DELIVERY_EXCEPTIONS` | Quantidade de entregas no status `exception` (uma entrega confirmada como falha). | `count` |
| `RECEIPT_DISCREPANCIES` | Quantidade de entregas no status `partially_fulfilled` (pelo menos uma caixa foi contestada no recebimento e a entrega ainda não foi encerrada). | `count` |
| `PENDING_ORDERS` | Quantidade de pedidos no status `pending_approval`. | `count` |
### Sinais piloto
Estas três acrescentam `numerator`, `denominator` e `sampleCount` quando se aplicam, uma `definition` e ressalvas legíveis por máquina em `caveats`.
| Id | Definição | Unidade | Janela | Ressalvas |
| - | - | - | - | - |
| `BOX_TRACEABILITY` | A proporção de caixas ativas cuja localização é identificável: um depósito conhecido, um status e um último movimento no registro. `numerator` são as caixas rastreáveis e `denominator` as caixas ativas. | `percent` | Nenhuma. É uma foto do momento; semanas passadas não são reconstruídas. `catalogItemId` é ignorado. | `snapshot_of_now_not_reconstructed_for_past_windows` |
| `APPROVAL_DECISION_MEDIAN_HOURS` | A mediana do tempo entre a solicitação de um pedido e a sua primeira decisão de aprovação, sobre os pedidos solicitados na janela que receberam uma decisão humana. Pedidos ainda aguardando e pedidos aprovados automaticamente não entram na amostra. | `hours` | `from` (incluído) e `to` (excluído), ambos opcionais, em ISO 8601 | `wall_clock_hours_no_business_calendar`, `orders_without_a_human_decision_excluded` |
| `DISTINCT_CUSTODY_ACTORS` | A proporção de repasses recebidos na janela cuja entrega e cujo recebimento foram confirmados por duas pessoas diferentes. Uma entrega sem as duas confirmações não entra na amostra. | `percent` | `from` e `to`, como acima, aplicados ao horário do recebimento | `handoffs_without_both_confirmations_excluded` |
`wall_clock_hours_no_business_calendar` significa que noites, fins de semana e feriados contam como horas. O muveya ainda não aplica um calendário de horário comercial.
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.
| Prioridade | Categoria (`metric`) | Uma entrada por | Detalhamento (`drillDownType`, `drillDownId`) | Campos de `reference` |
| - | - | - | - | - |
| 0 | `EXPIRING_STOCK` | alerta de validade aberto | `movement` e o id do movimento, ou `item` e o id do insumo quando nenhum movimento originou o alerta | `alertId`, `catalogItemId`, e `boxId`, `warehouseId` quando conhecidos |
| 1 | `DELIVERY_EXCEPTIONS` | entrega em `exception` | `order` e o id do pedido | `orderId` |
| 2 | `LOW_STOCK` | alerta de estoque baixo aberto | igual a `EXPIRING_STOCK` | igual a `EXPIRING_STOCK` |
| 3 | `RECEIPT_DISCREPANCIES` | entrega em `partially_fulfilled` | `order` e o id do pedido | `orderId` |
| 4 | `PENDING_ORDERS` | pedido em `pending_approval` | `order` e o id do pedido | `orderId`, `clinicId` |
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](/docs/pt/api-reference/scopes).
## 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.
| Campo por unidade | Significado |
| - | - |
| `clinicId`, `clinicName`, `clinicStatus` | A unidade. Todas aparecem, mesmo com zero pedidos. |
| `totalOrders` | Todos os pedidos da unidade, em qualquer status, rascunhos incluídos. |
| `pendingApprovalOrders` | A parte desses pedidos em `pending_approval`. |
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](/docs/pt/reports/consumption) do console.
| Parâmetro | Padrão | Regra |
| - | - | - |
| `from` | 30 dias antes de `to` | ISO 8601, incluído |
| `to` | agora | ISO 8601, excluído |
| `granularity` | `day` | `day` ou `week` (as semanas começam na segunda-feira) |
| `catalogItemId` | todos os insumos | um insumo |
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.
| Faixa (`label`) | Tempo de espera | `maxAgeHours` |
| - | - | - |
| `within_24h` | menos de 24 horas | `24` |
| `h24_to_72h` | de 24 horas a menos de 72 horas | `72` |
| `d3_to_7d` | de 72 horas a menos de 7 dias | `168` |
| `over_7d` | 7 dias ou mais | `null` |
Também retorna `total` e `oldestSubmittedAt`. Para a caixa de entrada de quem aprova, veja [Aprovar ou rejeitar pedidos](/docs/pt/orders/approvals).
## 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.
| Etapa | De | Até |
| - | - | - |
| `submit_to_dispatch` | pedido solicitado | entrega despachada |
| `dispatch_to_deliver` | despachada | entrega confirmada |
| `deliver_to_receive` | entrega confirmada | recebimento confirmado |
| `receive_to_close` | recebimento confirmado | entrega encerrada |
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](/docs/pt/deliveries/delivery-and-receipt).
## 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:
| Números | `metric` | `dimension` | Rótulo (português) | `unit` |
| - | - | - | - | - |
| Cinco contagens instantâneas | `LOW_STOCK`, `EXPIRING_STOCK`, `DELIVERY_EXCEPTIONS`, `RECEIPT_DISCREPANCIES`, `PENDING_ORDERS` | nenhuma | Alertas abaixo do mínimo, Alertas de caixas perto do vencimento, Exceções de entrega, Divergências de recebimento, Aprovações pendentes | `count` |
| Quatro faixas de espera | `APPROVAL_BACKLOG` | a faixa | Aprovações pendentes: menos de 24 horas, de 24 a 72 horas, de 3 a 7 dias, mais de 7 dias | `orders` |
| Registros de consumo | `CONSUMPTION_TREND` | `movements` | Movimentos de consumo | `movements` |
| Registros sem unidade verificada | `CONSUMPTION_TREND` | `unverified_movements` | Movimentos de consumo sem unidade verificada | `movements` |
| Até cinco insumos, três números cada | `CONSUMPTION_TREND` | `seriesKey`, `seriesKey:use`, `seriesKey:issue` | o nome do insumo; `nome: uso observado`; `nome: entregue às salas (consumo estimado)` | a unidade de medida do insumo (por exemplo `box`) |
| Quatro etapas do ciclo | `ORDER_CYCLE_TIME` | a etapa | Tempo de ciclo: da solicitação ao despacho, do despacho à entrega, da entrega ao recebimento, do recebimento ao fechamento | `hours` |
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](/docs/pt/api-reference/exports).
`POST /v1/analytics/exports` com um `period` opcional (`daily` por padrão, ou `weekly`). O cabeçalho `Accept-Language` desta solicitação define o idioma dos rótulos do CSV. A resposta é `202` com um `exportId` e o `status` do trabalho.
`GET /v1/analytics/exports/{exportId}` retorna o estado atual. O arquivo é gerado em segundo plano, então a primeira resposta costuma ser `pending`, embora possa chegar já como `ready`.
Quando `status` é `ready`, a resposta traz `downloadUrl` e `downloadExpiresAt`. O link funciona por 5 minutos. Cada consulta cria um link novo, então consulte de novo se ele expirou. O arquivo se chama `management-briefing-daily.csv` ou `management-briefing-weekly.csv`.
Compare o SHA-256 dos bytes baixados com `checksum`, e o tamanho com `byteSize`.
### Estados da exportação
| `status` | Significado |
| - | - |
| `pending` | Aceita, ainda não gerada. |
| `building` | O arquivo está sendo montado. |
| `ready` | O arquivo está armazenado. `byteSize`, `checksum`, `downloadUrl` e `downloadExpiresAt` estão presentes. |
| `failed` | A geração falhou. `error` traz um código de motivo sem dados sensíveis: `schedule_failed` (o trabalho não pôde entrar na fila; a própria solicitação falha então com `500`, então solicite uma nova exportação), `processing_error` (uma falha temporária; a geração é repetida automaticamente). |
### 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
| HTTP | `code` | Causa | O que fazer |
| - | - | - | - |
| `400` | `common.invalid_request` | Id de métrica desconhecido, janela ilegível ou invertida, janela de consumo maior que 366 dias, `granularity` ou `period` desconhecidos. | Corrija o parâmetro. |
| `401` | `api_keys.invalid` | Chave de API ausente, inválida ou revogada. | Veja [Autenticação](/docs/pt/api-reference/authentication). |
| `403` | `api_keys.scope_missing` | A chave não tem `analytics:read`. | Peça a [team@muveya.com](mailto:team@muveya.com) uma chave com esse escopo. |
| `404` | `common.not_found` | `exportId` desconhecido ou expirado. | Solicite uma nova exportação. |
| `429` | `common.too_many_requests` | Requisições demais com a chave. | Veja [Limites de uso](/docs/pt/api-reference/rate-limits). |
O formato completo dos erros está em [Erros](/docs/pt/api-reference/errors).
## Páginas relacionadas
A tela do console para o consumo por insumo.
Solicite e consulte uma exportação do resumo.
`analytics.consumption`, `management.briefing`, `management.compare_clinics`.
De onde vêm os alertas de estoque baixo e de validade.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.