VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Métodos de envio

Caixas de embalagem

Mantém o catálogo de caixas que a plataforma usa para dividir um carrinho em volumes ao cotar frete em tempo real.

Para cotar frete numa transportadora, a plataforma precisa saber quantos pacotes o pedido vira e que tamanho cada um tem. As caixas cadastradas aqui são o que o empacotador preenche: ele distribui os itens do carrinho nas caixas, da menor para a maior, e cota cada volume. Sem nenhuma caixa, o carrinho inteiro é cotado como um único pacote do tamanho dos itens somados.

Uma caixa pode ser da loja (qualquer seller usa) ou de um seller. Uma caixa dedicada é exclusiva de uma lista de produtos: só esses produtos vão nela, até max_items unidades.

As quatro rotas só existem quando o módulo correios-shipping está ligado na loja. Com o módulo desligado, respondem 403 {"error":"module_disabled","module":"correios-shipping"}.

Não testado ao vivo

O módulo estava desligado no ambiente de verificação. Os formatos desta página vêm do código das rotas.

Listar caixas

Com vendor_id, devolve as caixas desse seller mais as da loja. As desativadas (D) aparecem; as apagadas não.

GET/api/v1/admin/shipping/packaging-boxesAdmin

Lista as caixas de embalagem

Exige view_shipping ou manage_shipping.

Parâmetros de consulta

vendor_iduuid
Restringe a um seller (mais as caixas da loja).

Exemplo de requisição

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

Resposta

200Caixas retornadas
json
{
  "packaging_boxes": [
    {
      "id": "9f1c2b7e-3d58-4f0a-8a3e-5b6f1d2c7a10",
      "name": "Caixa 3 garrafas",
      "length_mm": 330,
      "width_mm": 120,
      "height_mm": 340,
      "max_weight_grams": 5000,
      "max_items": 3,
      "tare_weight_grams": 250,
      "dedicated": false,
      "status": "A",
      "position": 0,
      "length_cm": 33,
      "width_cm": 12,
      "height_cm": 34
    }
  ],
  "total": 1
}

Campos da resposta

packaging_boxesarray
Caixas.
totalinteger
Quantidade de caixas.
packaging_boxes[].iduuid
Id da caixa.
packaging_boxes[].vendor_iduuid
Seller dono da caixa. Ausente = caixa da loja, que qualquer seller pode usar.
packaging_boxes[].namestring
Nome da caixa.
packaging_boxes[].length_mminteger
Comprimento interno, em milímetros.
packaging_boxes[].width_mminteger
Largura interna, em milímetros.
packaging_boxes[].height_mminteger
Altura interna, em milímetros.
packaging_boxes[].length_cmnumber
Mesmo comprimento em centímetros (calculado, só na resposta).
packaging_boxes[].width_cmnumber
Mesma largura em centímetros (calculado).
packaging_boxes[].height_cmnumber
Mesma altura em centímetros (calculado).
packaging_boxes[].max_weight_gramsinteger
Carga máxima da caixa em gramas, sem contar a própria caixa.
packaging_boxes[].max_itemsinteger
Máximo de unidades. 0 = sem limite de unidades.
packaging_boxes[].tare_weight_gramsinteger
Peso da caixa vazia em gramas, somado a cada volume.
packaging_boxes[].dedicatedboolean
Se a caixa é exclusiva de uma lista de produtos (product_ids).
packaging_boxes[].product_idsarray
Produtos que usam a caixa dedicada. Ausente quando não há.
packaging_boxes[].statusstring
AD
A ativa ou D desativada.
packaging_boxes[].positioninteger
Ordem de uso.

Criar uma caixa

POST/api/v1/admin/shipping/packaging-boxesAdmin

Cria uma caixa de embalagem

Exige manage_shipping. As medidas podem vir em mm (length_mm) ou em cm (length_cm), cada dimensão por conta própria.

Corpo da requisição

namestringobrigatório
Nome da caixa.
length_mmintegerobrigatório
Comprimento interno em mm. Alternativa: length_cm. Se os dois vierem, vale o de mm.
width_mmintegerobrigatório
Largura interna em mm (ou width_cm).
height_mmintegerobrigatório
Altura interna em mm (ou height_cm).
max_weight_gramsintegerobrigatório
Carga máxima em gramas, no mínimo 1.
max_itemsinteger
Máximo de unidades. 0 = sem limite. Não pode ser negativo.
tare_weight_gramsinteger
Peso da caixa vazia em gramas. Não pode ser negativo.
dedicatedboolean
Torna a caixa exclusiva dos product_ids.
product_idsarray
Produtos da caixa dedicada. Só aceito com dedicated: true.
vendor_iduuid
Seller dono. Omita para uma caixa da loja. Só vale na criação.
statusstring
AD
A ou D. Vazio = A. Outra letra é recusada.
positioninteger
Ordem de uso.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/shipping/packaging-boxes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Caixa 3 garrafas",
    "length_cm": 33,
    "width_cm": 12,
    "height_cm": 34,
    "max_weight_grams": 5000,
    "max_items": 3,
    "tare_weight_grams": 250
  }'

Resposta

201Caixa criada
json
{
  "id": "9f1c2b7e-3d58-4f0a-8a3e-5b6f1d2c7a10",
  "name": "Caixa 3 garrafas",
  "length_mm": 330,
  "width_mm": 120,
  "height_mm": 340,
  "max_weight_grams": 5000,
  "max_items": 3,
  "tare_weight_grams": 250,
  "dedicated": false,
  "status": "A",
  "position": 0,
  "length_cm": 33,
  "width_cm": 12,
  "height_cm": 34
}

Alterar uma caixa

Esta rota regrava a caixa inteira: envie todos os campos, não só os que mudam, ou os ausentes viram zero e a validação recusa. O seller dono não muda.

PUT/api/v1/admin/shipping/packaging-boxes/{id}Admin

Altera uma caixa de embalagem

Exige manage_shipping. Uma caixa apagada responde 404.

Parâmetros de caminho

iduuidobrigatório
Id da caixa.

Corpo da requisição

namestringobrigatório
Nome da caixa.
length_mmintegerobrigatório
Comprimento interno em mm. Alternativa: length_cm. Se os dois vierem, vale o de mm.
width_mmintegerobrigatório
Largura interna em mm (ou width_cm).
height_mmintegerobrigatório
Altura interna em mm (ou height_cm).
max_weight_gramsintegerobrigatório
Carga máxima em gramas, no mínimo 1.
max_itemsinteger
Máximo de unidades. 0 = sem limite. Não pode ser negativo.
tare_weight_gramsinteger
Peso da caixa vazia em gramas. Não pode ser negativo.
dedicatedboolean
Torna a caixa exclusiva dos product_ids.
product_idsarray
Produtos da caixa dedicada. Só aceito com dedicated: true.
vendor_iduuid
Seller dono. Omita para uma caixa da loja. Só vale na criação.
statusstring
AD
A ou D. Vazio = A. Outra letra é recusada.
positioninteger
Ordem de uso.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/shipping/packaging-boxes/$BOX_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Caixa 3 garrafas",
    "length_cm": 33,
    "width_cm": 12,
    "height_cm": 34,
    "max_weight_grams": 5000,
    "max_items": 3,
    "tare_weight_grams": 250,
    "status": "D"
  }'

Resposta

200Caixa alterada
json
{
  "id": "9f1c2b7e-3d58-4f0a-8a3e-5b6f1d2c7a10",
  "name": "Caixa 3 garrafas",
  "length_mm": 330,
  "width_mm": 120,
  "height_mm": 340,
  "max_weight_grams": 5000,
  "max_items": 3,
  "tare_weight_grams": 250,
  "dedicated": false,
  "status": "D",
  "position": 0,
  "length_cm": 33,
  "width_cm": 12,
  "height_cm": 34
}

Apagar uma caixa

É uma exclusão lógica: a caixa deixa de aparecer e de ser usada, mas pedidos antigos continuam podendo referenciá-la. Se a caixa dedicada tem produtos associados, a rota recusa com 409 e informa quantos; repita com force=true para apagar e desfazer as associações.

DELETE/api/v1/admin/shipping/packaging-boxes/{id}Admin

Apaga uma caixa de embalagem

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório
Id da caixa.

Parâmetros de consulta

forcebooleanpadrão: false
true (ou 1, yes) apaga mesmo com produtos associados.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/shipping/packaging-boxes/$BOX_ID?force=true" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Caixa apagada
json
{
  "message": "packaging box deleted",
  "associated_products": 0
}

Campos da resposta

messagestring
Confirmação.
associated_productsinteger
Quantas associações com produtos foram desfeitas.

Erros

StatusQuandoCorpo
401Sem token, token inválido ou expirado{"error":"invalid or expired token"}
403Usuário sem o privilégio manage_shipping{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}
400Corpo que não é JSON, nome vazio, medida menor ou igual a zero, max_weight_grams menor que 1, valores negativos, product_ids sem dedicated, ou status diferente de A/D{"error":"failed to create packaging box","detail":"length_cm must be greater than zero"}
403Módulo correios-shipping desligado{"error":"module_disabled","module":"correios-shipping"}
404Caixa inexistente ou já apagada; ou product_ids com produto que não é do seller da caixa{"error":"packaging box not found","detail":"..."} / {"error":"packaging box product not found","detail":"..."}
409Apagar caixa com produtos associados, sem force=true{"error":"packaging box has associated products","associated_products":3}
Cadastre caixas do menor para o maior volume

O empacotador usa a primeira caixa em que o grupo de itens cabe, da menor para a maior. Caixas que não existem no catálogo nunca são sugeridas: se o seu produto mais comprido não cabe em nenhuma, cadastre uma caixa grande o bastante.

Apagar é final

Pela API não há como reativar uma caixa apagada: ela responde 404 até em PUT. Para só pausar, envie status: "D".

Veja também

  • Políticas de frete
  • Criar um método
Anterior
Áreas do método
Próxima
Políticas de frete
Nesta página
  • Listar caixas
  • Exemplo de requisição
  • Resposta
  • Criar uma caixa
  • Exemplo de requisição
  • Resposta
  • Alterar uma caixa
  • Exemplo de requisição
  • Resposta
  • Apagar uma caixa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também