Pular para o conteúdo
CotejarCotejarCotejar para desenvolvedores

Análises e resultados

Uma análise compara todos os produtos ativos da empresa com a regra vigente do Portal Único. A seleção da vigilância não reduz esse diagnóstico.

  1. pendentepróxima etapa por fila
  2. executandopróxima etapa por avaliação
  3. concluidaou desvia para falhouLeia codigo_falha. resultado: null não significa zero achados.
Estados de uma análise

Solicitar

Seção intitulada “Solicitar”
POST/v1/analisesanalise:executarReferência
POST /v1/analises
Authorization: Bearer <chave>
Idempotency-Key: 6d3bd2aa-4fe2-47c3-b353-6e3b0ee3ec3e
Content-Type: application/json


{}
202 Accepted · Location: /v1/analises/e0da8bf7-0252-4556-9d52-856cc1349507
{ "id": "e0da8bf7-0252-4556-9d52-856cc1349507", "estado": "pendente" }

O corpo é um objeto vazio, com teto de 2 KiB. O 202 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. O resultado informa catálogos, versões, snapshot regulatório e avaliador efetivamente usados.

Acompanhar

Seção intitulada “Acompanhar”
GET/v1/analises/{id}catalogo:lerReferência

Consulte até concluida ou falhou. Enquanto isso, resultado é null. Prefira o webhook analise.concluida (ou analise.falhou) e mantenha a consulta como plano B, com prazo.

200 OK · concluída
{
  "id": "e0da8bf7-0252-4556-9d52-856cc1349507",
  "estado": "concluida",
  "criada_em": "2026-10-13T16:26:38.706Z",
  "terminada_em": "2026-10-13T16:47:03.109Z",
  "codigo_falha": null,
  "resultado": {
    "snapshot_id": "snap-338",
    "versao_portal": "338",
    "versao_avaliador": "2",
    "executada_em": "2026-10-13T16:47:01.581Z",
    "regras_coletadas_em": "2026-10-12T16:00:00.000Z",
    "ultima_coleta_util_em": "2026-10-13T06:32:54.000Z",
    "regulamento_degradado": false,
    "assinante": true,
    "franquia_consumida": false,
    "produtos_avaliados": 2847,
    "divergencias": { "orfao": 4, "bloqueante": 8911, "deriva": 0, "anvisa": 2787 },
    "catalogos": [{ "id": "7c7b354f-07b6-4461-9240-263418c81cdb", "versao": 1 }],
    "paginas_resultado": 59
  }
}
Campo Leitura
divergencias Contagem por tipo. A soma é o total de achados.
regulamento_degradado true quando o Cotejar não conseguiu confirmar que a regra usada está atualizada. Nessa condição, zero achados não comprova catálogo em dia. Mostre a marcação a quem usa o resultado.
snapshot_id, versao_portal Qual versão das regras do Portal Único foi usada.
catalogos Catálogos e versões avaliados.
franquia_consumida Se esta execução contou na franquia do plano.
paginas_resultado Quantas páginas de achados existem. Use só como informação; percorra pelo cursor.

Falta de catálogo, regulamento ou autorização termina de forma explícita, em falhou.

GET/v1/analisescatalogo:lerReferência

Lista as execuções mais recentes com cursor opaco. Veja paginação e limites.

Percorrer todos os achados

Seção intitulada “Percorrer todos os achados”
GET/v1/analises/{id}/resultadoscatalogo:lerReferência

Use ?pagina=1 e siga proxima_pagina até null. Cada página tem no máximo 200 itens e também é limitada por bytes. Antes da conclusão, a rota devolve 409 ANALISE_NAO_CONCLUIDA.

200 OK
{
  "itens": [
    {
      "produto_id": "0001628c-0c07-48ab-85f7-011db27a16ed",
      "codigo_produto": "0001628c-0c07-48ab-85f7-011db27a16ed",
      "ncm": "30021500",
      "tipo": "bloqueante",
      "codigo_atributo": "ATT_1000",
      "detalhe": "Atributo obrigatório ATT_1000 — Marca comercial não preenchido."
    }
  ],
  "proxima_pagina": 2
}

Cada achado traz o UUID Cotejar do produto, o código preservado na execução, NCM, tipo, código de atributo quando houver e detalhe.

tipo Significado
orfao Produto desativado por ato ou NCM fora da tabela vigente: não há regra contra a qual comparar.
bloqueante Atributo obrigatório não preenchido ou valor que o Portal Único não aceita: a DUIMP seria rejeitada.
deriva A regra mudou: um atributo deixou de ser exigido e o produto ainda o informa, ou passou a constar e o produto não o informa.
anvisa Categoria do produto para a Anvisa ausente ou não aceita: o produto depende de regularização da anuência.

Baixar e validar o CSV

Seção intitulada “Baixar e validar o CSV”
GET/v1/analises/{id}/resultados.csvcatalogo:lerReferência

O CSV lê o resultado imutável: não executa nem consome outra análise. UTF-8 com BOM, ;, células entre aspas e CRLF. Começa com resumo, contém todos os registros achado e termina com conclusao, inclusive quando não há achados.

O validador de CSV faz as cinco conferências em Node.js e Python. 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 numa planilha recebem um apóstrofo protetor. Preserve-o. Quando precisar do texto original, use as páginas JSON.