Kits, mestres e caixas

Além do produto simples, a vitrine vende conjuntos: vários produtos vendidos juntos, o mesmo produto oferecido por vários sellers (lojistas), uma lista montada para um cliente específico ou uma caixa fechada com várias unidades. Esta seção reúne as rotas de leitura desses conjuntos, todas usadas pelas páginas de produto, listagens e carrinho.

Como funciona

Os conjuntos e quando usar cada um

1. Montar a vitrine

   Liste os kits em Kits, as caixas em Caixas de produto e, para clientes logados, os mixes em Mixes.

2. Na página do produto

   Consulte as ofertas dos sellers em Produtos mestres, as variantes de caixa do produto e o modo catálogo em Modo catálogo para decidir qual botão de compra mostrar.

3. Adicionar ao carrinho

   Estas rotas só leem; a escrita no carrinho é de outra seção. No caso do mix, Resolver mix calcula como o preço fechado se distribui entre as linhas.

Conceitos-chave

Dinheiro e nomes enganosos

Todo valor monetário é inteiro em centavos. Atenção: nos kits, o campo price_bps (e o espelho price_override) não é basis points, é um preço fixo em centavos; já discount_bps é basis points (1000 = 10%) quando discount_type é percentage, e centavos quando é fixed. Veja Kits.

Quem pode ver o quê

Visitantes e clientes veem somente conjuntos ativos e da loja (sem dono seller). Preços de ofertas de produtos mestres e de variantes de caixa são zerados ou omitidos para visitante quando a loja esconde preço para quem não está logado (veja o campo price_redacted). A listagem de kits não aplica essa regra.

Cache

As leituras públicas voltam com Cache-Control: public, max-age=300, stale-while-revalidate=1800 (5 minutos, com revalidação em segundo plano). A lista de variantes de caixa de um cliente logado e as ofertas filtradas pela região do comprador voltam private, no-store. Mixes e demais respostas autenticadas dependem do cliente: não as guarde em cache compartilhado.

Ids

Todos os ids são UUID em string. Kits também têm slug (texto) usado no detalhe.

Endpoints

Erros comuns

• Esperar o produto mestre na vitrine. A lista de mestres é sempre vazia e o detalhe é sempre 404. Use /master-products/{id}/offers para comparar sellers.
• Tratar price_bps como basis points. É preço fixo em centavos; 0 significa "usar o preço calculado".
• Mandar um id que não é UUID. Várias destas rotas devolvem 500 em vez de 400 quando o id é malformado (veja cada página). Valide o formato antes de chamar.
• Chamar mixes sem login. Resposta 401 {"error":"missing authorization header"}.
• Ignorar a região do comprador nas ofertas. Dependendo da configuração da loja, ofertas de sellers que não entregam na região do cliente não aparecem.
• Usar per_page acima do permitido. O servidor não limita ao máximo: volta ao valor padrão da rota.

Próximos passos