Catálogo de produtos

O catálogo transforma identificadores transacionais em contexto comercial. Para a integração, cada produto é representado no nível de SKU ou variante. O registro combina a variante vendável com os dados herdados do produto, da marca, da categoria principal e da política comercial.

Os campos formam uma referência para o onboarding. A origem não precisa renomear sua estrutura de dados. A Audt confirma o mapeamento com o cliente e preserva os identificadores e significados originais.

Grain recomendado

Publique uma linha por SKU × política comercial × instante do snapshot quando preço ou sortimento variarem por contexto comercial. Se houver uma única política, publique uma linha por SKU em cada snapshot_at.

Mantenha a relação product_id → sku_id estável. Os dados do produto agrupador devem acompanhar cada SKU derivado.

Campos do produto no nível de SKU

Mapeie os campos equivalentes disponíveis na fonte:

Conceito lógico	Obrigatório	Descrição
`product_id`	Sim	Identificador estável do produto agrupador
`product_ref_id`	Recomendado	Código de referência comercial do produto
`sku_id`	Sim	Identificador estável da variante vendável
`sku_ref_id`	Recomendado	Código de referência comercial do SKU
`product_name`	Sim	Nome comercial do produto agrupador
`sku_name`	Sim	Nome comercial específico da variante vendável
`brand_id`	Sim	Identificador estável da marca
`brand_name`	Sim	Nome da marca apresentado aos usuários
`primary_category_id`	Sim	Identificador da categoria principal
`primary_category_name`	Sim	Nome da categoria principal
`primary_category_slug`	Recomendado	Slug da categoria principal, quando exposto pela origem
`category_path_ids`	Sim	Caminho hierárquico ordenado por identificadores
`category_path_names`	Sim	Caminho hierárquico ordenado por nomes
`ean`	Recomendado	Código comercial quando disponível e validado
`is_active`	Sim	Indica se o SKU participa do sortimento atual
`is_kit`	Sim	Indica se o SKU representa um kit ou conjunto comercial
`measurement_unit`	Sim	Unidade usada para interpretar quantidade e preço
`unit_multiplier`	Sim	Multiplicador aplicado à unidade de medida
`variant_attributes`	Recomendado	Pares de atributo e valor, como cor e tamanho
`release_date`	Sim	Data de lançamento herdada do produto
`trade_policy_id`	Recomendado	Política comercial que define o contexto de sortimento e preço
`price_table_id`	Recomendado	Tabela de preços associada quando exposta separadamente
`list_price`	Sim	Preço DE da tabela ou política comercial, antes dos descontos
`selling_price`	Sim	Preço POR vigente no catálogo para o contexto comercial
`image_url`	Sim	URL estável da imagem principal, sem credencial embutida
`snapshot_at`	Sim	Data e hora em que o estado do registro foi observado
`partition_date`	Recomendado para cargas	Data operacional da partição ou do arquivo entregue
`updated_at`	Recomendado para incrementais	Data e hora da última alteração informada pela origem

O selling_price do catálogo não representa o valor líquido de uma venda. O item de pedido preserva o preço efetivamente praticado e os descontos aplicados.

Árvore de categorias (taxonomia)

Publique a hierarquia de categorias em um conjunto próprio:

Campo	Finalidade
`category_id`	ID estável da categoria
`category_name`	Nome apresentado aos usuários
`category_slug`	Slug apresentado nas rotas, quando disponível
`parent_category_id`	Relação com o nível imediatamente superior
`category_path_ids`	Caminho completo e ordenado por identificadores
`category_path_names`	Caminho completo e ordenado por nomes
`category_level`	Profundidade na hierarquia
`is_active`	Estado atual sem apagar o histórico
`snapshot_at`	Data e hora em que o estado da árvore foi observado

Um SKU pode participar de várias categorias. Identifique a categoria principal no registro do produto. Quando outras associações forem relevantes, preserve sku_id, category_id, is_primary e snapshot_at.

Atualizações e histórico

Para snapshots completos, inclua snapshot_at em todas as linhas.
Use partition_date apenas para organizar a entrega ou o armazenamento.
Preserve mudanças relevantes de marca, categoria, atributos e status quando análises históricas precisarem refletir o contexto da época.
Não substitua silenciosamente uma categoria antiga. Preserve o snapshot da árvore correspondente.

Controles de qualidade

Controle	Aceite recomendado
Unicidade	Um `sku_id` por política comercial e `snapshot_at`
Integridade	Todo SKU referencia um `product_id` e uma categoria válidos
Completude	Nomes, marca, categoria, unidade e preços preenchidos nos SKUs em escopo
Temporalidade	Snapshots e incrementais preservam o instante informado pela origem
Relação com pedidos	SKUs vendidos no período são encontrados no catálogo ou registrados como exceção conhecida
Relação com estoque	A mesma chave de SKU é usada em catálogo e disponibilidade

Casos que precisam de decisão

kits, combos e brindes;
produtos de marketplace com seller externo;
variações sem estoque próprio;
reclassificação de categoria;
múltiplas listas de preço por canal, região ou cluster;
atributos livres, unidades de medida e conversões de embalagem.

Registre a decisão no dicionário de dados antes da primeira carga recorrente. Quando houver dúvida, preserve o valor original e publique uma normalização separada.