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

Caixa (tipo G, 6 pares)             Variante: caixa x produto
  composição: 37 x2, 38 x4   --->     produto "Chinelo Slim Preto"
  status: A                            preço da caixa: "599.40"
                                       estoque de caixas: 10

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.
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 é o preço da caixa inteira para aquele produto, em string decimal. Se for "0.00", 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 seller) 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. Pela API legada, toda caixa criada é da loja.

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 erro com a mensagem product-boxes: module disabled for tenant (status 500 nas leituras e na alteração, 400 na criação);
• o carrinho e o checkout se comportam como se as caixas não existissem: nenhum produto exige caixa.

Autenticação e permissão

Todas as rotas exigem um administrador autenticado por HTTP Basic (e-mail:chave_de_api) ou por Authorization: Bearer <JWT>. Sem credencial a resposta é 401; um usuário que não é administrador recebe 403.

Identificadores, nomes de rota e formato

• O box_id é um UUID. Se a caixa veio de uma plataforma anterior (tem número legado), o campo box_id traz esse número em string e o UUID vai em uuid.
• As rotas existem em /api/v1.0/... e na forma sem versão /api/.... Na forma sem versão, o box_id sai como número decimal em string e não é aceito de volta no caminho.
• Os textos de listagem e consulta vêm do idioma pt-BR (ou do idioma padrão da loja, se não houver pt-BR).
• Os erros têm o formato {"message":"...","status":404}. A lista tem o formato {"product_boxes":[...],"params":{...}}.

Endpoints

Auth: Admin é o administrador, autenticado por HTTP Basic ou Bearer JWT. Cada rota tem a sua página, linkada na última coluna. Todas existem também com o nome sem sublinhado (productboxes, productboxesvariants, productboxesdescriptions).

Erros comuns

1. Chamar com o módulo desligado. A resposta é erro com product-boxes: module disabled for tenant. 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. Tentar excluir uma caixa. O DELETE sempre responde 404 nesta API.
4. Tentar ligar a caixa a um produto. As variantes são só leitura aqui: a ligação, o preço e o estoque são mantidos no painel da loja.
5. Usar de volta o número decimal do box_id. Na forma /api/... esse número não é aceito no caminho (404). Guarde o UUID.
6. Esperar que a caixa venda sozinha. Sem uma variante ligando a caixa a um produto, ela não aparece para nenhum produto.
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