Página de produto

Consultar produto devolve o produto em si. Tudo o que a página ainda precisa, como as escolhas do comprador (cor, tamanho, gravação personalizada), a ficha técnica, o manual para baixar, os vídeos e os selos, vem de rotas próprias deste grupo. Elas são separadas de propósito: a página carrega o produto primeiro e busca o resto em paralelo, e uma falha em uma parte não derruba a página inteira.

Todas as rotas desta seção são públicas, sob /api/v1/storefront/products/{id}/..., e identificam o produto por UUID. Diferente de GET /products/{id}, elas não aceitam slug e, na maioria, não checam se o produto está ativo: resolva o produto antes e use o id que ele devolveu.

Como funciona

1. Abrir o produto

   GET /products/{id} traz preço, estoque, imagens e as flags has_unified_variations e is_variation, mais o array variations quando as variações são produtos-filhos.

2. Carregar o resto em paralelo

   Opções, variações, características, anexos, vídeos, selos e produtos obrigatórios. Cada uma é independente.

3. Resolver a escolha do comprador

   Com as variações, o comprador escolhe cor e tamanho. Você converte a escolha em um SKU: com variações unificadas, procure em variations[].combination; com produtos-filhos, chame GET /products/{id}/variant?cor=Vermelho&tamanho=M.

4. Comprar

   Ao adicionar ao carrinho, envie o id do produto (ou do produto-filho) e as opções escolhidas. Para os produtos obrigatórios (is_mandatory: true), é a vitrine que deve adicioná-los junto: a API do catálogo só informa a relação.

Conceitos-chave

Opções, variações de produtos-filhos e variações unificadas

Na lista de produtos, has_unified_variations avisa que o comprador precisa escolher cor/tamanho antes de adicionar ao carrinho, sem uma chamada extra por produto.

Preço de variação

Em variações unificadas, o preço da combinação é price do produto mais price_modifier da variação (em centavos; pode ser negativo). Em produtos-filhos, cada filho tem o próprio price. Em opções, some o modificador da opção escolhida: absolute em centavos ou percentage em pontos-base sobre o preço do produto.

Visitante e preço escondido

Quando a loja esconde preços de visitantes, o modificador de preço das opções também sai zerado. As demais rotas desta seção não carregam preço, exceto os produtos obrigatórios e as variações unificadas.

Endpoints

Erros comuns

• Passar o slug em vez do UUID. Estas rotas esperam o UUID. Com um slug, a rota devolve lista vazia ou erro 500 de UUID inválido; resolva o slug com GET /products/{slug} antes.
• Concluir que o produto não tem opções porque options é null. null e [] significam o mesmo: sem opções.
• Chamar /variant sem parâmetros. Retorna 400: mande ao menos um atributo, como ?cor=Vermelho.
• Esperar 404 em produto inexistente. A maioria das rotas devolve 200 com lista vazia. O 404 só vem de /variant (sem correspondência) e do download de anexo (anexo inexistente).
• Somar o modificador de opção em reais. O modificador é inteiro em centavos (ou pontos-base, conforme price_modifier_type).
• Supor que is_mandatory é imposto pelo servidor. O catálogo apenas informa quais produtos acompanham este; adicionar os obrigatórios ao carrinho é responsabilidade da sua vitrine.

Próximos passos