Análises e resultados

Uma análise considera todos os produtos ativos da empresa. A seleção da vigilância não reduz esse diagnóstico.

Solicitar

POST /v1/analises
Authorization: Bearer <chave>
Idempotency-Key: 6d3bd2aa-4fe2-47c3-b353-6e3b0ee3ec3e
Content-Type: application/json

{}

A operação exige analise:executar junto de catalogo:ler. O corpo é vazio e tem teto de 2 KiB. A resposta 202 contém id, estado e Location; ela confirma o aceite durável e ainda não consome a franquia.

Pode haver uma execução ativa por empresa. Um pedido simultâneo acompanha o mesmo ID, e uma execução concluída ainda atual pode ser reaproveitada com resposta 200. Consulte o resultado para saber catálogos, versões, snapshot regulatório e avaliador efetivamente usados.

Acompanhar

GET /v1/analises/{id} informa pendente, executando, concluida ou falhou. resultado: null durante a espera ou depois de falha não significa zero achados.

Em uma conclusão, o resumo inclui produtos avaliados, contagens de orfao, bloqueante, deriva e anvisa, referência regulatória, degradação e consumo da franquia. Falta de catálogo, regulamento ou autorização termina de forma explícita.

GET /v1/analises lista as execuções mais recentes com cursor opaco. Veja paginação e limites.

Percorrer todos os achados

Use GET /v1/analises/{id}/resultados?pagina=1 e siga proxima_pagina até null. Cada página tem no máximo 200 itens e também é limitada por bytes. Não calcule a última página a partir do total.

Cada achado contém o UUID Cotejar do produto, seu código preservado na execução, NCM, tipo, código de atributo quando houver e detalhe. Antes da conclusão, a rota devolve 409.

Baixar e validar o CSV

GET /v1/analises/{id}/resultados.csv lê o resultado imutável e não executa nem consome outra análise. O CSV usa UTF-8 com BOM, ;, células entre aspas e CRLF. Ele começa com resumo, contém todos os registros achado e termina com conclusao, inclusive quando não há achados.

HTTP 200 não basta

Só aceite o arquivo depois de validar o tamanho em X-Cotejar-Tamanho-Bytes, o SHA-256 em Content-Digest, o cabeçalho, a quantidade de achados e o registro final conclusao. Calcule o hash sobre os bytes recebidos, antes de decodificar, remover BOM ou normalizar linhas.

O formato do digest é sha-256=:<base64>:. Se o corpo terminar antes da conclusão ou qualquer conferência falhar, descarte tudo e repita o download completo. Não há retomada por Range.

Valores que poderiam iniciar fórmula em uma planilha recebem um apóstrofo protetor. Preserve-o ao abrir o CSV. Quando precisar do texto original sem essa transformação, use as páginas JSON.