Skip to main content
Uma exportação do resumo gerencial é um arquivo CSV com o mesmo resumo que 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 escopo analytics: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
Guarde o 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

Chame GET /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 downloadUrl funciona 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.csv ou management-briefing-weekly.csv.
  • Compare o SHA-256 dos bytes recebidos com checksum, e o tamanho com byteSize. 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)
Os números são os mesmos que 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 404 com o código common.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.

Erros

Páginas relacionadas