GET /v1/analytics/briefing retorna: alertas, exceções de entrega, aprovações pendentes, consumo e tempos de ciclo. O muveya gera o arquivo em segundo plano, então o fluxo tem três passos: pedir, acompanhar e baixar.
POST /v1/analytics/exports é a única operação de /v1 que grava algo, e o que ela grava é o próprio trabalho de exportação. Nada muda na sua operação.
Quem pode fazer
Uma chave com o escopoanalytics:read (veja Escopos). O mesmo escopo cobre pedir, acompanhar e baixar.
O fluxo
Passo 1: peça a exportação
string
padrão:"daily"
A periodicidade do resumo:
daily ou weekly. Qualquer outro valor é recusado com 400 e o código common.invalid_request. O corpo é opcional; sem ele você recebe um resumo diário. Não envie nenhum outro campo.string
padrão:"en"
O idioma da coluna
label do CSV: en, es ou pt. Ele fica definido no momento da solicitação, porque o arquivo é gerado depois. As chaves de métricas, dimensões, unidades, valores e ids de evidência são iguais em todos os idiomas.202 Accepted
exportId: ele é a única referência ao trabalho.
Esta operação não tem chave de idempotência. Cada
POST cria um trabalho de exportação novo e independente. Se uma requisição expirar antes de você receber o exportId, envie-a de novo; o trabalho extra não causa problemas e é excluído junto com os demais após 7 dias.Passo 2: acompanhe até ficar pronta
ChameGET /v1/analytics/exports/{exportId} a cada poucos segundos (por exemplo, a cada 3 segundos). Cada consulta conta para o seu limite de uso.
200 OK (building)
200 OK (ready)
string
obrigatório
O id do trabalho que você recebeu ao solicitar a exportação.
string
obrigatório
pending, building, ready ou failed.string
obrigatório
O relatório contido no arquivo. Hoje é sempre
briefing.string
obrigatório
daily ou weekly, conforme a solicitação.integer
O tamanho do arquivo em bytes. Aparece quando o status é
ready.string
O SHA-256 do arquivo, em 64 caracteres hexadecimais minúsculos. Aparece quando o status é
ready.string
Um link de download assinado. Aparece somente quando o status é
ready. Cada consulta emite um link novo.string
Quando o
downloadUrl atual deixa de funcionar (UTC).string
Um motivo legível por máquina. Aparece quando o status é
failed. Um trabalho que falhou uma vez e foi repetido automaticamente mantém este campo enquanto está em building e depois de chegar a ready, então verifique sempre status primeiro.Passo 3: baixe e verifique
- O
downloadUrlfunciona por 5 minutos depois da consulta que o retornou. Ele tem a própria assinatura: não adicione sua chave de API nem outro cabeçalho à requisição de download. - Baixe imediatamente. Não guarde nem compartilhe o link: enquanto ele for válido, qualquer pessoa que o tenha pode baixar o arquivo. Se ele expirou, consulte o trabalho de novo para obter um link novo.
- O arquivo se chama
management-briefing-daily.csvoumanagement-briefing-weekly.csv. - Compare o SHA-256 dos bytes recebidos com
checksum, e o tamanho combyteSize. Se forem diferentes, baixe de novo.
Exemplo completo
O arquivo CSV
- Codificação UTF-8 com marca de ordem de bytes, para que as planilhas mostrem os acentos corretamente. As linhas terminam em CRLF.
- Uma linha de cabeçalho e depois uma linha por número do resumo.
- Células que contêm vírgula, aspas ou quebra de linha ficam entre aspas. Uma célula que começa com
=,+,-,@, tabulação ou retorno de carro recebe uma aspa simples (') na frente, para que uma planilha nunca a execute como fórmula.
management-briefing-weekly.csv (trecho, Accept-Language: pt)
GET /v1/analytics/briefing retorna para o mesmo período no momento em que o arquivo foi gerado. O nome de cada insumo aparece como está no seu catálogo. Para saber o que cada métrica significa, veja Análises gerenciais.
O que o arquivo nunca contém
A exportação omite dados sensíveis por construção: ela contém contagens, quantidades, durações, rótulos e ids de evidência. Nunca contém custos, valores de pedidos, referências de pacientes nem nomes de membros da equipe. Ela cobre todas as unidades e depósitos da clínica odontológica, como qualquer outra leitura com chave de API.O que o muveya registra
- Cada solicitação de exportação fica na auditoria da sua clínica odontológica, com a chave de API como autora, o tipo de relatório e o período.
- Quando o arquivo é gerado, a auditoria também registra o tamanho e o checksum SHA-256, para que depois seja possível comparar o arquivo que você tem com o registro.
- Os trabalhos de exportação são mantidos por 7 dias a partir da solicitação. Depois disso, consultar o trabalho retorna
404com o códigocommon.not_found: peça uma nova exportação.
Quando o trabalho falha
Se as novas exportações continuarem falhando, escreva para team@muveya.com com o
exportId.