Medidas

Peso e dimensão são o que a plataforma usa pra cotar o frete: sem essa medida, não dá pra calcular o envio. Este guia cobre as duas camadas de medida que existem (unidade avulsa e embalagem fechada do atacado) e onde cada uma vive.

Conceitos

Frete se calcula por peso e volume. Mas você vende de dois jeitos: unidades avulsas (o cliente compra 1, 2 ou 3 itens soltos) e lotes fechados (caixa, fardo, pallet no atacado). Cada tipo de venda tem peso/volume diferente, então você precisa cadastrar a medida de cada um.

Unidade avulsa

Quando o cliente compra unidades soltas (1, 2, 3...), o frete usa o peso e tamanho de uma unidade. É o que você preenche em /api/products/{id} (campo dimensions). Exemplo: 1 camiseta pesa 150g e mede 10cm × 20cm × 5cm.

Lote fechado (atacado)

Quando o cliente compra em quantidade grande (10, 50, 100...) e você vende embalagens fechadas (caixa com 10 unidades, fardo com 50), o frete usa o peso/tamanho da embalagem inteira, não de 1 unidade. Exemplo: caixa com 10 camisetas pesa 2kg e mede 40cm × 50cm × 30cm.

Você define quantas unidades "disparam" cada embalagem com min_quantity (mínimo 2). Pode ter mais de uma faixa: "caixa a partir de 10 unidades", "fardo a partir de 50 unidades", etc.

Onde cada um vive

• Unidade avulsa: cadastro de produto, campo dimensions em PUT /api/products/{id}
• Lotes fechados: rota separada GET/PUT /api/products/{id}/measures, uma faixa por quantidade mínima

As faixas de preço não carregam medida nenhuma. O que vale para o frete é só o que estiver aqui (unidade) ou em /measures (embalagens fechadas).

Medida da unidade

Cadastrada junto com o produto, não nesta rota:

dimensions.height, dimensions.width, dimensions.length (cm) e dimensions.weight (kg) são opcionais no cadastro, mas sem elas o produto não é cotado no frete até serem preenchidas. Quando informadas, cada valor precisa ser no mínimo 0.001.

{
  "dimensions": {
    "height": 15.5,
    "width": 10.0,
    "length": 20.0,
    "weight": 0.75
  }
}

Restrições de empacotamento

Medida não é a única coisa que entra na cubagem. Dois booleans do produto (opcionais, default false, aceitos no POST e no PUT /api/products/{id}) restringem como o item pode ser acomodado dentro de um volume:

Os dois mudam o resultado do empacotamento e, por consequência, o frete cotado: com keep_flat, o algoritmo perde uma das rotações possíveis e pode precisar de uma caixa maior; com ship_isolated, o pedido passa a ter no mínimo um volume só para esse SKU, em vez de consolidar tudo num volume único.

{
  "keep_flat": true,
  "ship_isolated": false
}

Medidas de embalagem fechada

Toda faixa de atacado representa uma embalagem fechada (caixa/fardo): é com ela que a plataforma calcula o frete da venda fracionada.

Os quatro campos de medida são tudo-ou-nada por faixa: mandar só parte deles — ou mandar 0 em algum — é recusado com 422 e a mensagem "Cada produto de atacado precisa de ao menos uma faixa com peso e dimensões completas da embalagem". Como o PUT roda em transação, uma faixa inválida derruba a requisição inteira: nada é gravado.

Consultar

{
  "success": true,
  "message_code": "SUCCESS",
  "data": [
    { "min_quantity": 10, "weight": 12.5, "height": 30.0, "width": 40.0, "length": 50.0 },
    { "min_quantity": 50, "weight": 60.0, "height": 100.0, "width": 80.0, "length": 100.0 }
  ]
}

Produto sem faixas cadastradas retorna data vazio.

Substituir

O PUT substitui a lista inteira (reconciliação): faixas presentes no corpo são criadas/atualizadas e faixas ausentes são removidas, então envie sempre a lista completa. O campo tiers é obrigatório no corpo, mesmo que vazio. Faixas com min_quantity = 1 são ignoradas (a medida da unidade se edita no produto, não aqui).

{
  "tiers": [
    { "min_quantity": 10, "weight": 12.5, "height": 30.0, "width": 40.0, "length": 50.0 },
    { "min_quantity": 50, "weight": 60.0, "height": 100.0, "width": 80.0, "length": 100.0 }
  ]
}

Para zerar todas as faixas, envie tiers: []: a lista vazia remove todas as faixas >= 2 existentes.