Produtos e identidade externa

O produto canônico pertence à empresa e pode estar vinculado a vários catálogos. O UUID Cotejar é a identidade das rotas. origem e id_externo preservam a identidade do sistema que enviou o produto; sku é um campo de busca e não substitui esse par.

O servidor sempre gera o UUID Cotejar. id_externo e sku são opcionais; quando o cliente não os informa, permanecem nulos, e o integrador usa o UUID devolvido para as operações seguintes.

Leituras exigem catalogo:ler; criações, edições e vínculos exigem catalogo:escrever junto de leitura.

Consultar, cadastrar, editar e retirar produtos dos catálogos da própria empresa não exige assinatura ativa. Permissões, isolamento empresarial e limites técnicos continuam obrigatórios.

Cadastrar em um catálogo

POST /v1/catalogos/{catalogo_id}/produtos
Authorization: Bearer <chave>
Idempotency-Key: 0bb0299d-2261-43db-97dd-f7aa91cc0cba
Content-Type: application/json

{
  "origem": "erp",
  "id_externo": "000123",
  "sku": "SKU-000123",
  "descricao": "Produto de exemplo",
  "ncm": "01012100",
  "atributos": [
    { "codigo": "ATT_123", "valores": ["valor informado"] }
  ]
}

ncm tem oito dígitos e atributos é obrigatório, mesmo quando vazio. origem usa api por padrão. Os identificadores são strings: não remova zeros à esquerda, espaços ou caixa por conta própria.

O cadastro confirma estrutura e persistência. Somente uma análise informa exigências ausentes, deriva, enquadramento ANVISA ou produto órfão.

Consultar

GET /v1/produtos e GET /v1/catalogos/{id}/produtos aceitam limite, apos_id, origem, id_externo, sku, ncm e estado. A igualdade de id_externo exige também origem. Por padrão, a consulta empresarial inclui ativos e inativos.

Cada item devolve id, id_externo, origem, sku, descricao, ncm, atributos, versao, ativo e os IDs em catalogos.

Editar sem perder concorrência

Consulte GET /v1/produtos/{id}, copie o ETag completo e faça PATCH /v1/produtos/{id} com uma nova Idempotency-Key. Campos omitidos são preservados. null limpa id_externo, sku ou descricao; enviar atributos substitui a lista completa.

A edição afeta todos os catálogos vinculados. Uma mudança concorrente, inclusive de vínculo, invalida o ETag e retorna 412.

Vincular e retirar

Ação	Rota
Vincular produto existente	PUT /v1/catalogos/{catalogo_id}/produtos/{produto_id}
Retirar daquele catálogo	DELETE /v1/catalogos/{catalogo_id}/produtos/{produto_id}

As duas operações usam o ETag do produto e Idempotency-Key. O corpo pode ser omitido ou ser {}. Retirar o último vínculo deixa o produto inativo e o remove da seleção, preservando ID, conteúdo e histórico. Vinculá-lo novamente reativa a mesma identidade; no modo de seleção explícita, ele não volta à seleção automaticamente.