Catálogos

Cada catálogo pertence a um estabelecimento e recebe um UUID Cotejar estável. Nome, CNPJ e referência externa ajudam a localizar o recurso, mas o integrador usa catalogo_id nas operações.

Leituras exigem catalogo:ler. Criar, editar, conferir impacto e excluir exigem catalogo:gerenciar junto de leitura.

Consultar e gerir catálogos da própria empresa não exige assinatura ativa. As permissões e os limites técnicos continuam obrigatórios.

Criar e localizar

POST /v1/catalogos
Authorization: Bearer <chave>
Idempotency-Key: 8f5a0d04-b83f-4122-8950-86c5dbb6bb3a
Content-Type: application/json

{
  "estabelecimento_id": "11111111-1111-4111-8111-111111111111",
  "nome": "Catálogo da matriz",
  "id_externo": "CAT-ERP-001"
}

O estabelecimento precisa estar ativo e pertencer à empresa da chave. Há um catálogo ativo por estabelecimento. A resposta 201 traz Location, ETag, versão e contagem de produtos.

GET /v1/catalogos aceita limite, apos_id, estabelecimento_id, estado e id_externo. Por padrão, inclui ativos e excluídos. A contagem produtos representa vínculos cadastrados, não a cobertura da vigilância nem um resultado regulatório.

Editar

Consulte GET /v1/catalogos/{id}, guarde o ETag e envie PATCH com uma nova Idempotency-Key. Somente nome e id_externo são graváveis; omissões preservam campos e null limpa a referência externa. A operação não transfere o catálogo para outra empresa ou filial.

Excluir com impacto conhecido

Faça GET /v1/catalogos/{id}/impacto-exclusao.
Revise produtos exclusivos e compartilhados, desativações e efeito projetado na seleção.
Copie o ETag da prévia para If-Match no DELETE /v1/catalogos/{id}.
Envie uma Idempotency-Key própria da exclusão.

Se catálogo, produtos, vínculos, capacidade ou seleção mudarem desde a prévia, o servidor devolve 412 sem exclusão parcial. Produtos compartilhados permanecem nos outros catálogos. Produtos sem vínculo ativo deixam o cadastro vigente e a seleção, mas a identidade e o histórico não são apagados.