VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Preço e estoque do produto

Embalagem de envio do produto

Lê e grava a caixa externa medida de um produto (dimensões, capacidade e tara) usada no cálculo de frete, com controle de versão por updated_at.

A embalagem de envio descreve a caixa externa em que o produto viaja: as três dimensões da caixa, quantas unidades do produto cabem nela (mínimo e máximo) e o peso da caixa vazia (a tara). A transportadora cota o frete com base nessas medidas, e não só nas medidas do item. Não confunda com as dimensões do próprio produto (peso, largura, altura, comprimento), que ficam no cadastro dele.

Ao gravar, a plataforma descarta o cache de cotações de frete, então a próxima cotação já usa a embalagem nova.

Pontos-chave
  • Exige o recurso de frete pelos Correios ligado na loja. Desligado, as duas rotas respondem 403 {"error":"module_disabled","module":"correios-shipping"}.
  • Leitura exige view_catalog ou manage_catalog; gravação exige manage_catalog.
  • O PUT exige todos os sete campos, e updated_at deve ser o valor da última leitura. Se alguém mudou a embalagem nesse meio-tempo, a resposta é 409 e você precisa reler.
  • Dimensões em centímetros (até 2 casas decimais) e tara em gramas (inteiro).
  • Para desativar a embalagem medida, zere as três dimensões, as capacidades e a tara.

Como funciona

A embalagem tem três estados:

EstadoComo éO que significa
Sem embalagemAs três dimensões em 0, e capacidades e tara em 0.O frete usa só as medidas do item. É o estado de um produto sem configuração.
Embalagem medidaAs três dimensões maiores que 0, e ao menos um entre min_items_in_box e max_items_in_box maior que 0.O frete considera a caixa externa.
InválidoQualquer mistura (por exemplo, só duas dimensões preenchidas).O PUT é recusado com 400.

Regras de validação

  • box_length, box_width e box_height: números de 0 a 99999999,99 em centímetros, com no máximo 2 casas decimais.
  • min_items_in_box e max_items_in_box: inteiros de 0 a 1000000. Se max_items_in_box for maior que 0, min_items_in_box não pode ser maior que ele.
  • box_tare_grams: inteiro de 0 a 2147483647.
  • Embalagem medida (dimensões maiores que 0) exige capacidade mínima ou máxima.
  • Para zerar, as três dimensões e também capacidades e tara precisam ir a 0.

Controle de versão com updated_at

Todo GET devolve updated_at. Para gravar, você devolve esse mesmo valor no PUT. Se a embalagem mudou depois da sua leitura, o updated_at não confere e a gravação é recusada com 409 product_packaging_changed, para que você não apague a alteração de outra pessoa. A resposta do PUT traz o updated_at novo.

Consultar a embalagem

GET/api/v1/admin/products/{id}/shipping-packagingAdmin

Consulta a embalagem de envio de um produto

Devolve a embalagem atual do produto e a versão (updated_at) para a próxima gravação. A resposta não é guardada em cache (Cache-Control: no-store).

Path parameters

iduuidobrigatório
Id do produto.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/shipping-packaging" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Embalagem do produto
json
{
  "box_length": 30,
  "box_width": 20,
  "box_height": 15.5,
  "min_items_in_box": 1,
  "max_items_in_box": 12,
  "box_tare_grams": 250,
  "updated_at": "2026-10-11T20:54:44.466233Z"
}

Response fields

box_lengthnumber
Comprimento da caixa externa em centímetros. 0 se não houver embalagem.
box_widthnumber
Largura da caixa externa em centímetros.
box_heightnumber
Altura da caixa externa em centímetros.
min_items_in_boxinteger
Quantidade mínima de unidades do produto na caixa. 0 se não definida.
max_items_in_boxinteger
Quantidade máxima de unidades do produto na caixa. 0 se não definida.
box_tare_gramsinteger
Peso da caixa vazia em gramas.
updated_atstring
Versão da embalagem (RFC 3339 em UTC). Devolva este valor ao gravar. Muda quando o produto é alterado.

Erros

StatusQuandoCorpo
400O {id} não é um UUID.{"error":"invalid product id"}
401Sem token.{"error":"missing authorization header"}
403O recurso de frete pelos Correios está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403Sem view_catalog nem manage_catalog.{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}
404Produto inexistente ou na lixeira.{"error":"product not found"}

Gravar a embalagem

PUT/api/v1/admin/products/{id}/shipping-packagingAdmin

Salva a embalagem de envio de um produto

Exige manage_catalog. Grava a embalagem e devolve o estado novo no mesmo formato do GET. Não é uma atualização parcial: os sete campos são obrigatórios, nenhum pode ser null, e não pode haver campos extras.

Path parameters

iduuidobrigatório
Id do produto.

Corpo da requisição

box_lengthnumberobrigatório
Comprimento da caixa em centímetros, até 2 casas decimais.
box_widthnumberobrigatório
Largura da caixa em centímetros.
box_heightnumberobrigatório
Altura da caixa em centímetros.
min_items_in_boxintegerobrigatório
Quantidade mínima de unidades por caixa (0 a 1000000).
max_items_in_boxintegerobrigatório
Quantidade máxima de unidades por caixa (0 a 1000000). Com valor maior que 0, não pode ser menor que o mínimo.
box_tare_gramsintegerobrigatório
Peso da caixa vazia em gramas.
updated_atstringobrigatório
O updated_at recebido na última leitura, sem alterar.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/shipping-packaging" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "box_length": 30,
  "box_width": 20,
  "box_height": 15.5,
  "min_items_in_box": 1,
  "max_items_in_box": 12,
  "box_tare_grams": 250,
  "updated_at": "2026-10-11T20:54:44.466233Z"
}'

Para remover a embalagem medida:

bash
curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/shipping-packaging" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "box_length": 0,
  "box_width": 0,
  "box_height": 0,
  "min_items_in_box": 0,
  "max_items_in_box": 0,
  "box_tare_grams": 0,
  "updated_at": "2026-10-11T21:02:10.381907Z"
}'

Resposta

200Embalagem gravada
json
{
  "box_length": 30,
  "box_width": 20,
  "box_height": 15.5,
  "min_items_in_box": 1,
  "max_items_in_box": 12,
  "box_tare_grams": 250,
  "updated_at": "2026-10-11T21:02:10.381907Z"
}

Use o updated_at desta resposta na próxima gravação.

Erros

StatusQuandoCorpo
400Corpo que não é um JSON único, ou maior que 4 KB.{"error":"invalid request body"}
400Falta algum dos sete campos, algum é null, ou há campo extra.{"error":"all packaging fields are required"}
400Um valor não tem o tipo certo (por exemplo, texto no lugar de número).{"error":"invalid packaging values"}
400Valores fora das regras: dimensão negativa ou com mais de 2 casas, só algumas dimensões preenchidas, capacidade ausente, mínimo maior que máximo, tara fora do limite, ou zerar as dimensões sem zerar capacidade e tara.{"error":"invalid packaging values","detail":"all three outer packaging dimensions are required"}
400updated_at com a data zero (0001-01-01T00:00:00Z).{"error":"updated_at from the last read is required"}
400O {id} não é um UUID.{"error":"invalid product id"}
404Produto inexistente ou na lixeira.{"error":"product not found"}
409O updated_at não é o atual: a embalagem foi alterada desde a sua leitura.{"error":"product_packaging_changed"}
403Recurso de frete pelos Correios desligado, ou sem manage_catalog.{"error":"module_disabled","module":"correios-shipping"} / {"error":"insufficient privileges","required":"manage_catalog"}

As mensagens de detail do 400 de validação vêm em inglês, como o servidor as devolve:

detailCausa
packaging dimensions must be finite, nonnegative centimetresDimensão negativa ou fora do intervalo.
packaging dimensions allow at most two decimal placesMais de 2 casas decimais.
packaging quantities and tare must be nonnegative whole numbers within storage limitsCapacidade ou tara negativa, fracionada ou acima do limite.
all three outer packaging dimensions are requiredSó uma ou duas dimensões maiores que 0.
measured packaging requires a minimum or maximum item capacityDimensões preenchidas e mínimo e máximo ambos em 0.
minimum item capacity cannot exceed maximummin_items_in_box maior que max_items_in_box.
clear capacity and tare when disabling product packagingAs três dimensões em 0, mas capacidade ou tara diferentes de 0.
Reler antes de gravar

Como o updated_at do produto também muda quando outro dado do produto é editado (preço, estoque, imagens), o 409 pode aparecer mesmo sem ninguém ter mexido na embalagem. Trate o 409 como "releia e tente de novo": faça um GET, aplique sua alteração sobre o resultado e grave com o updated_at novo.

Veja também

  • Preço e estoque do produto: visão geral e o mapa das rotas.
  • Recorrência do produto
  • Atualizar produto: peso e dimensões do item.
  • Produtos
Anterior
Recorrência do produto
Próxima
Conteúdo e características do produto
Nesta página
  • Como funciona
  • Regras de validação
  • Controle de versão com updatedat
  • Consultar a embalagem
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar a embalagem
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também