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.

Mesmo na venda em múltiplos (seção abaixo), em que a cubagem usa a embalagem fechada e não a unidade, a medida da unidade continua sendo pré-condição do cálculo de frete e serve de base para a conferência de coerência das embalagens. Mantenha-a preenchida.

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

Produto vendido em múltiplos (faixa obrigatória)

Quando o produto tem quantidade mínima de compra e não permite venda fracionada (min_purchase_quantity >= 2 + allow_fractional_quantity: false no POST/PUT /api/products), o cliente só compra em múltiplos exatos do mínimo (25, 50, 75…). Nesse modelo o que viaja no frete é sempre a embalagem fechada do mínimo, nunca 1 unidade.

Por isso a faixa de medida com min_quantity == min_purchase_quantity passa a ser obrigatória no PUT /api/products/{id}/measures. Um payload sem ela (inclusive tiers: []) é recusado com 422 e message_code dedicado:

{
  "success": false,
  "code": 422,
  "message_code": "MIN_PURCHASE_PACKAGE_MEASURE_REQUIRED",
  "description": "Este produto é vendido em múltiplos de 25 un (quantidade mínima de compra com venda fracionada desligada), então o que viaja no frete é sempre a embalagem fechada de 25, nunca 1 unidade. Cadastre a faixa de medida de 25 un com peso, altura, largura e comprimento. Para dispensar essa faixa, mude a quantidade mínima de compra para 1 ou ligue a venda fracionada no produto."
}

Como o PUT é substitui-lista e roda em transação, a recusa também protege a faixa existente: um payload que "esqueceu" a faixa do mínimo não a apaga.

Para dispensar a exigência (escape hatch): mude min_purchase_quantity para 1 ou ligue allow_fractional_quantity via PUT /api/products/{id}. Aí tiers: [] volta a ser aceito.

Para detectar a pendência antes de salvar: GET /api/products/{id} devolve min_purchase_quantity e allow_fractional_quantity, e GET /api/products/{id}/measures lista todas as faixas. Se a do mínimo não estiver lá, o próximo PUT /measures precisa incluí-la.

Coerência com a medida da unidade

Além do tudo-ou-nada por faixa, cada faixa é conferida contra a medida da unidade (quando ela está completa no produto): a embalagem precisa comportar o volume das min_quantity peças e pesar ao menos o que elas pesam juntas (1% de tolerância). Dado impossível é recusado com 422 e mensagem descritiva: a faixa é repassada como está para a cubagem, então medida impossível viraria frete errado.

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). Produto vendido em múltiplos exige a faixa do mínimo na lista. Ver a seção "Produto vendido em múltiplos".

{
  "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. Exceção: produto vendido em múltiplos (mínimo >= 2 sem venda fracionada) recusa tiers: [] com 422 MIN_PURCHASE_PACKAGE_MEASURE_REQUIRED. Para limpar as faixas, primeiro mude a quantidade mínima para 1 ou ligue a venda fracionada no PUT /api/products/{id}.