Catálogo mestre e visibilidade

Em um marketplace, muitos sellers (lojistas) vendem o mesmo item: a mesma cafeteira, o mesmo tênis. Para não ter dez cadastros diferentes do mesmo produto, o administrador mantém um catálogo mestre: o cadastro oficial de cada item (nome, descrição, fotos, características, EAN). O seller clona o mestre para a própria loja e informa só o que é dele: preço, estoque, SKU e situação. A vitrine passa a comparar as ofertas dos sellers sob o mesmo mestre.

Esta seção também cobre dois controles do próprio seller: o modo catálogo (a loja mostra o produto mas não vende no carrinho) e a visibilidade (quais clientes enxergam o seller).

Como funciona

1. Procure no catálogo mestre
   GET /api/v1/vendor/master-catalog?search=cafeteira lista os mestres ativos. Use GET /api/v1/vendor/master-catalog/{id} para ver um.
2. Clone
   POST /api/v1/vendor/master-catalog/{id}/clone cria o seu produto. Para vários, use bulk-clone.
3. Ajuste preço e estoque
   Envie price e quantity no corpo do clone, ou altere depois pelas rotas de produtos do seller.
4. Opcional: modo catálogo e visibilidade
   Ligue o modo catálogo para vender fora da plataforma e restrinja quem vê o seu seller.

Conceitos-chave

Mestre, clone e oferta

O mestre é o cadastro oficial. O clone é o produto do seller criado a partir dele; mantém o vínculo (master_product_id). Cada clone é uma oferta; o offer_count do mestre conta as ofertas ativas.

Lote com simulação

bulk-clone aceita uma lista de ids ou um filtro (marca, categoria, faixa de preço...). Com filtro, a rota exige uma simulação antes: você manda simulate: true, recebe a contagem e um confirm_token, e só então executa. Com 50 registros ou mais a execução vira uma tarefa que você acompanha em Tarefas em lote.

Modo catálogo

No modo catálogo o produto aparece, mas o botão "Adicionar ao carrinho" some. No lugar, a vitrine mostra um link externo "Comprar agora" (por produto) ou um pedido de cotação. Serve a quem fecha a venda fora da plataforma.

Visibilidade

Cada seller tem regras de quem o enxerga. O administrador controla se o seller está oculto e para quais grupos de clientes. O seller controla uma lista de clientes: só estes (allowlist) ou todos menos estes (denylist).

Endpoints

Erros comuns

• Clonar o mesmo mestre de novo. A segunda tentativa responde 500 com a frase you already have a product linked to this master product. Na rota em lote, o repetido é só contado em skipped.
• Esperar estoque pronto. O clone nasce com quantity: 0; sem estoque o produto não vende. Envie quantity no clone.
• Achar que bulk-clone com skipped > 0 falhou por inteiro. A resposta é 200 com partial_failure: true: os demais foram criados.
• Executar um lote por filtro sem simular. Responde 428 simulate_required.
• Mandar customer_mode: "all" com ids. A lista precisa estar vazia no modo all.
• Esquecer que o mestre inativo some. Só mestres ativos aparecem; os ocultos ou pendentes respondem 404.

Próximos passos