Produtos mestre

Em um marketplace, vários sellers (lojistas) podem vender o mesmo item, como um mesmo modelo de celular. Cadastrar a foto, a descrição e a ficha técnica uma vez por seller gera páginas repetidas e inconsistentes. O produto mestre resolve isso: é o cadastro-modelo do item, mantido pela loja, e cada seller liga o seu produto (a oferta, com o preço e o estoque dele) a um mestre. O cliente vê uma página do item com a lista de ofertas, no estilo dos grandes marketplaces.

Como funciona

Como um produto de seller vira oferta de um mestre

1. O seller salva um produto

   Se a loja usa a ligação automática, a plataforma procura um mestre com o mesmo SKU (normalizado) ou o mesmo código de barras.

2. Ligar, criar ou pedir revisão

   Conforme a configuração da loja, a plataforma liga o produto ao mestre encontrado, cria um mestre novo a partir do produto, ou enfileira a decisão para um administrador.

3. O administrador decide na fila

   Em Fila de aprovação ele aprova (liga ou cria) ou rejeita (o produto fica solto).

4. A oferta aparece

   A lista de ofertas do mestre passa a incluir o seller.

Status do mestre

Um mestre sem nenhuma oferta nunca aparece para o cliente: ele é um molde, não algo vendável.

Conceitos-chave

O que o mestre controla e o que o seller controla

Cada mestre pode ter uma lista própria de campos que o seller pode editar nas ofertas ligadas (editable_fields_override). Sem ela, vale a lista padrão da loja.

Unicidade de SKU e de código de barras

Um mestre não pode repetir o SKU nem o código de barras de outro mestre ou de qualquer produto de seller. O conflito volta 409 com a mensagem dizendo quem já usa o código (em português). O SKU é gravado em minúsculas.

Dinheiro

base_price é o preço sugerido ao consumidor, em centavos (4990 = R$ 49,90). O preço que o cliente paga é o da oferta.

Exclusão

Excluir um mestre é lógico (status vira D) e só é permitido quando nenhum produto de seller está ligado a ele.

Endpoints

A ligação manual de um produto a um mestre (/products/{id}/link-master) pertence à seção de produtos.

Erros comuns

• Criar um mestre sem categoria: a resposta é 500 com category_required, embora seja um erro seu. Mande category_id.
• Esperar que o mestre tenha preço de venda: base_price é só uma sugestão.
• Mudar o nome do mestre e se surpreender que as ofertas mudaram também: é a propagação.
• Tentar excluir um mestre com ofertas: 409. Desligue os produtos antes.
• Reaproveitar o código de barras de um produto de seller: 409, mesmo que o produto seja da mesma loja.
• Enviar imagem com url em vez de image_url: 400.
• Confundir os dois bloqueios do recurso: 403 module_disabled quer dizer que o módulo está desligado; 404 feature not enabled quer dizer que a configuração de produtos mestre da loja está desligada.

Próximos passos