Estabelecimentos

Um estabelecimento representa a matriz ou uma filial. Seu ID Cotejar permanece estável, e o catálogo é um recurso separado. Criar um estabelecimento não cria um catálogo nem seleciona produtos para vigilância.

Leituras exigem catalogo:ler. Escritas e o fluxo de correção exigem estabelecimento:gerenciar junto de leitura.

Consultar, cadastrar, editar e arquivar estabelecimentos da própria empresa não exige assinatura ativa. As permissões e os limites técnicos continuam obrigatórios.

Cadastrar

POST /v1/estabelecimentos
Authorization: Bearer <chave>
Idempotency-Key: 8f74c739-ea5d-4568-b58a-4a55f13ac920
Content-Type: application/json

{
  "cnpj": "12345678000195",
  "nome": "Matriz",
  "id_externo": "FILIAL-001"
}

O CNPJ é completo, sem pontuação, com dígitos verificadores válidos e a mesma raiz da empresa autenticada. Essa validação estrutural não comprova existência ou titularidade cadastral. A resposta 201 devolve Location, ETag e o recurso criado.

Consultar e editar

GET /v1/estabelecimentos aceita paginação por limite e apos_id, além dos filtros estado, cnpj e id_externo. Por padrão, inclui ativos e arquivados. catalogo_id é nulo quando não existe catálogo ativo.

Para editar, consulte GET /v1/estabelecimentos/{id}, guarde o ETag completo e envie somente nome e/ou id_externo:

PATCH /v1/estabelecimentos/{id}
If-Match: "estabelecimento-<versao>-<resumo>"
Idempotency-Key: 3eb26857-6836-4264-a851-c659415b78f0

Campos omitidos são preservados; id_externo: null limpa a referência. Trate o ETag como opaco.

Corrigir CNPJ

O CNPJ não pode ser alterado pelo PATCH. A correção usa uma solicitação separada, com o ETag do estabelecimento, motivo e idempotência:

POST /v1/estabelecimentos/{id}/correcoes-cnpj

O 202 confirma a persistência da solicitação, sem aplicar a mudança. Consulte a URL de Location, sob GET /v1/operacoes/{id}, até aprovada ou rejeitada. Uma mudança de raiz exige procedimento humano fora da API de catálogo.

Arquivar

DELETE /v1/estabelecimentos/{id} usa If-Match e Idempotency-Key e aceita corpo ausente ou {}. Um catálogo ativo vinculado impede o arquivamento com 409. O histórico e a identidade permanecem preservados.