Vigilância

A capacidade é compartilhada pela empresa. Um produto canônico presente em duas filiais ocupa uma vaga. Cadastro, seleção, direito ativo e execução da vigilância são dimensões distintas.

A vigilância contínua exige assinatura com direito pago ativo. Suspensão ou expiração preservam a preferência de seleção, mas deixam os produtos sem elegibilidade até a reativação do direito.

Consultar a situação

GET /v1/empresa/vigilancia exige catalogo:ler e devolve a seleção atual com ETag:

• modo: selecao ou todos;
• cadastrados, selecionados, elegiveis, capacidade e vagas;
• direito_ativo, cobertura e exige_selecao;
• versao, usada com o ETag para proteger mudanças concorrentes.

Uma preferência preservada não comprova que a vigilância foi executada com sucesso.

Alterar a seleção

PATCH /v1/empresa/vigilancia exige vigilancia:gerenciar, catalogo:ler, If-Match e Idempotency-Key.

{
  "modo": "selecao",
  "adicionar": ["550e8400-e29b-41d4-a716-446655440000"],
  "remover": ["550e8400-e29b-41d4-a716-446655440001"]
}

A soma das listas aceita até 200 IDs Cotejar por pedido. O mesmo ID não pode aparecer nas duas. modo: "todos" não aceita listas e só é aplicado quando todo o cadastro cabe na capacidade.

Exceder a capacidade retorna 409 e recusa a troca inteira; o servidor não escolhe um subconjunto e não altera assinatura ou cobrança. Para uma seleção maior que 200, aplique lotes e use o novo ETag de cada resposta.

Por exemplo, cadastrar ou importar 1.000 produtos com capacidade 500 preserva os 1.000 no catálogo. A empresa escolhe até 500 para a vigilância; tentar selecionar o 501º recusa a troca inteira, sem descartar produtos cadastrados, escolher produtos automaticamente ou cobrar uma ampliação.

GET /v1/empresa/vigilancia/produtos lista os selecionados. Continue com apos_id=proximo_id e envie a versao retornada na primeira página. Se a seleção mudar, 412 exige reiniciar a paginação.

Histórico e resultados

GET /v1/vigilancias lista execuções mais recentes. GET /v1/vigilancias/{id} separa as fases avaliacao, publicacao e relatorio: um resultado já publicado pode continuar disponível mesmo quando o relatório ainda está pendente ou falhou.

Percorra GET /v1/vigilancias/{id}/resultados até proximo_cursor: null, inclusive se uma página vazia ainda trouxer cursor. Cada achado informa avaliado_em, snapshot_id e reaproveitado; quando há reaproveitamento, a avaliação efetiva pode ser anterior à passagem atual.

O CSV em GET /v1/vigilancias/{id}/resultados.csv segue o mesmo contrato de integridade da análise: valide tamanho, digest, cabeçalho, contagem e conclusao. Ele fica disponível após a publicação, mesmo com relatório pendente. Suspender a assinatura preserva o histórico.