Embalagens e caixas

Na Venddor existem dois conceitos diferentes que as pessoas chamam de "caixa". Esta seção trata de um deles, e é importante saber qual é qual antes de integrar.

As caixas de produto não influenciam o frete. Elas não têm medidas nem peso: o frete continua sendo calculado pelo peso e dimensões do produto e pelas embalagens de frete cadastradas. Se o seu objetivo é mexer em dimensões e peso para a cotação de frete, esta não é a seção.

Como funciona

O modelo

1. A caixa descreve a composição: uma lista de tamanhos e quantidades (size_qty_info) e um título por idioma. A soma das quantidades é o número de pares da caixa (total_pairs).
2. A variante liga a caixa a um produto e guarda o preço da caixa para aquele produto e quantas caixas há para vender.
3. No carrinho, o comprador escolhe a caixa do produto. O preço, o estoque e a composição são sempre lidos de novo pelo servidor; valores vindos do navegador não são aceitos.

Tipos e status

Preço e estoque da variante

• Preço. price_centavos é o preço da caixa inteira para aquele produto. Se for 0, a plataforma usa o preço do produto multiplicado pelo número de pares da caixa.
• Estoque. amount é a quantidade de caixas disponíveis. 0 significa "sem contador por caixa": nesse caso vale o estoque do próprio produto. Quando é maior que zero, cada compra o reduz, e a compra é recusada se pedir mais caixas do que o contador.

Quem é o dono da caixa

Uma caixa pode ser da loja (marketplace, sem vendor_id) ou de um seller. As caixas da loja valem para qualquer produto. As de um seller só valem para produtos desse mesmo seller. A vitrine principal mostra só as da loja.

Exclusão

Excluir uma caixa a marca como removida (soft delete): ela some de todas as listas e leituras, e as variantes e descrições ficam guardadas. Excluir uma variante apaga a ligação de vez.

Conceitos-chave

O módulo product-boxes

O recurso product-boxes é um módulo por loja, desligado por padrão. Para quem integra, isso significa: antes de qualquer chamada, confirme com o administrador da loja que o módulo está ligado. Com ele desligado:

• as rotas respondem 403 com {"error":"module_disabled","module":"product-boxes"};
• o carrinho e o checkout se comportam como se as caixas não existissem: nenhum produto exige caixa.

Permissões

Administrador com o privilégio manage_product_boxes ou manage_catalog, em Authorization: Bearer <token>. Vale para leitura e escrita.

Endpoints

Auth: Admin é o administrador com o privilégio manage_product_boxes ou manage_catalog.

Erros comuns

1. Chamar com o módulo desligado. 403 module_disabled. Peça ao administrador para ligar o módulo product-boxes.
2. Criar uma caixa sem título ou sem composição. É exigido um título não vazio em pelo menos um idioma e pelo menos uma linha de size_qty_info com tamanho e quantidade maior que zero.
3. Criar uma caixa e esperar que ela venda. Sem uma variante ligando a caixa a um produto, ela não aparece para nenhum produto.
4. Ativar uma caixa em um produto e perder a venda avulsa. Produto com caixa à venda só é aceito em caixa. Se o produto também deve vender solto, não ligue caixa a ele.
5. Esquecer o preço da variante. price_centavos: 0 não significa grátis: significa "preço do produto vezes os pares". Confira o valor cobrado.
6. Ligar o mesmo produto duas vezes à mesma caixa. Dá 409 duplicate variant. Altere a variante existente.
7. Procurar medidas e peso aqui. As caixas de produto não têm; elas não entram na cotação de frete.

Próximos passos