VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Correios

Caixas de embalagem

Cadastra as caixas que o empacotamento usa para dividir um pedido em volumes e calcular peso e medidas.

Para cotar e emitir etiquetas, a plataforma precisa saber em que caixas o pedido cabe. Ela enche as caixas da menor para a maior, escolhendo a menor que serve. O catálogo tem as caixas da loja (valem para todos os sellers; você pode usar mas não alterar) e as suas. Requer o módulo correios-shipping.

Listar caixas

Devolve as suas caixas (ativas e desativadas) e as caixas ativas da loja. As apagadas não aparecem.

GET/api/v1/vendor/shipping/packaging-boxesSeller

Lista as caixas de embalagem disponíveis ao seller

Exemplo de requisição: listar

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

Resposta: listar

200Caixas
json
{
  "packaging_boxes": [
    {
      "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
      "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "name": "Caixa M",
      "length_mm": 300,
      "width_mm": 200,
      "height_mm": 100,
      "max_weight_grams": 5000,
      "max_items": 0,
      "tare_weight_grams": 120,
      "dedicated": false,
      "status": "A",
      "position": 0,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 10
    }
  ],
  "total": 1
}

Campos da resposta

packaging_boxesarray

Caixas disponíveis.

iduuid
Id da caixa.
vendor_iduuid
Seller dono. Ausente nas caixas da loja, que servem a todos os sellers.
namestring
Nome da caixa.
length_mm, width_mm, height_mminteger
Medidas internas em milímetros.
length_cm, width_cm, height_cmnumber
As mesmas medidas em centímetros (calculadas).
max_weight_gramsinteger
Carga máxima em gramas, sem contar a caixa.
max_itemsinteger
Máximo de unidades. 0 = sem limite de unidades (só peso e medidas limitam).
tare_weight_gramsinteger
Peso da caixa vazia, em gramas, somado a cada volume.
dedicatedboolean
true = caixa exclusiva dos produtos em product_ids.
product_idsarray
Produtos que usam a caixa dedicada. Ausente quando não há.
statusstring
AD
A ativa ou D desativada.
positioninteger
Ordem de preferência em empate.
totalinteger
Quantidade.

Erros: listar

StatusQuandoCorpo de exemplo
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O módulo correios-shipping está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403O usuário não tem conta de seller.{"error":"no vendor account associated with this user"}
403O usuário não tem o privilégio necessário (vendor_settings ou um privilégio de leitura de configurações).{"error":"insufficient vendor privileges","privilege_required_any":["..."]}
500Falha ao consultar.{"error":"failed to list packaging boxes"}

Criar uma caixa

Cria uma caixa sua. Se vier vendor_id no corpo, ele é ignorado.

POST/api/v1/vendor/shipping/packaging-boxesSeller

Cria uma caixa de embalagem do seller

Corpo da requisição

namestringobrigatório
Nome da caixa.
length_mm, width_mm, height_mmintegerobrigatório
Medidas internas em milímetros, maiores que zero. Você pode enviar length_cm, width_cm e height_cm no lugar (decimais aceitos); se enviar os dois, o milímetro vale.
max_weight_gramsintegerobrigatório
Carga máxima em gramas, no mínimo 1.
max_itemsintegerpadrão: 0
Máximo de unidades, 0 = sem limite.
tare_weight_gramsintegerpadrão: 0
Peso da caixa vazia, em gramas.
dedicatedbooleanpadrão: false
Caixa exclusiva de certos produtos.
product_idsarray
Produtos seus que usam esta caixa. Exige dedicated: true. Em PUT: omitido = mantém; [] = remove todos.
statusstringpadrão: A
AD
A ou D. Vazio = A. Qualquer outra letra é recusada.
positionintegerpadrão: 0
Ordem de preferência.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/vendor/shipping/packaging-boxes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Caixa M",
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 10,
    "max_weight_grams": 5000,
    "tare_weight_grams": 120
  }'

Resposta: criar

201Caixa criada
json
{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "name": "Caixa M",
  "length_mm": 300,
  "width_mm": 200,
  "height_mm": 100,
  "max_weight_grams": 5000,
  "max_items": 0,
  "tare_weight_grams": 120,
  "dedicated": false,
  "status": "A",
  "position": 0,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10
}

Campos da resposta

iduuid
Id da caixa.
vendor_iduuid
Seller dono. Ausente nas caixas da loja, que servem a todos os sellers.
namestring
Nome da caixa.
length_mm, width_mm, height_mminteger
Medidas internas em milímetros.
length_cm, width_cm, height_cmnumber
As mesmas medidas em centímetros (calculadas).
max_weight_gramsinteger
Carga máxima em gramas, sem contar a caixa.
max_itemsinteger
Máximo de unidades. 0 = sem limite de unidades (só peso e medidas limitam).
tare_weight_gramsinteger
Peso da caixa vazia, em gramas, somado a cada volume.
dedicatedboolean
true = caixa exclusiva dos produtos em product_ids.
product_idsarray
Produtos que usam a caixa dedicada. Ausente quando não há.
statusstring
AD
A ativa ou D desativada.
positioninteger
Ordem de preferência em empate.

Erros: criar

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid request body"}
400Regra violada: name is required, medida não positiva, max_weight_grams must be greater than zero, valores negativos, product_ids require a dedicated packaging box ou status fora de A/D. A mensagem cita length_cm/width_cm/height_cm mesmo quando você enviou milímetros.{"error":"failed to create packaging box","detail":"length_cm must be greater than zero"}
404Algum product_ids não é um produto seu.{"error":"packaging box product not found","detail":"packaging box product not found: 1f2e..."}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O módulo correios-shipping está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403O usuário não tem conta de seller.{"error":"no vendor account associated with this user"}
403O usuário não tem o privilégio necessário (vendor_settings).{"error":"insufficient vendor privileges","privilege_required_any":["..."]}

Alterar uma caixa

Substitui os dados da caixa: envie sempre todos os campos obrigatórios, como na criação. Só caixas suas; as da loja respondem 404.

PUT/api/v1/vendor/shipping/packaging-boxes/{id}Seller

Altera uma caixa de embalagem do seller

Parâmetros de caminho

iduuidobrigatório
Id da caixa.

Corpo da requisição

namestringobrigatório
Nome da caixa.
length_mm, width_mm, height_mmintegerobrigatório
Medidas internas em milímetros, maiores que zero. Você pode enviar length_cm, width_cm e height_cm no lugar (decimais aceitos); se enviar os dois, o milímetro vale.
max_weight_gramsintegerobrigatório
Carga máxima em gramas, no mínimo 1.
max_itemsintegerpadrão: 0
Máximo de unidades, 0 = sem limite.
tare_weight_gramsintegerpadrão: 0
Peso da caixa vazia, em gramas.
dedicatedbooleanpadrão: false
Caixa exclusiva de certos produtos.
product_idsarray
Produtos seus que usam esta caixa. Exige dedicated: true. Em PUT: omitido = mantém; [] = remove todos.
statusstringpadrão: A
AD
A ou D. Vazio = A. Qualquer outra letra é recusada.
positionintegerpadrão: 0
Ordem de preferência.

Exemplo de requisição: alterar

bash
curl -X PUT "$BASE_URL/api/v1/vendor/shipping/packaging-boxes/6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Caixa M reforçada",
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 10,
    "max_weight_grams": 8000,
    "tare_weight_grams": 150
  }'

Resposta: alterar

200Caixa atualizada
json
{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "name": "Caixa M reforçada",
  "length_mm": 300,
  "width_mm": 200,
  "height_mm": 100,
  "max_weight_grams": 8000,
  "max_items": 0,
  "tare_weight_grams": 150,
  "dedicated": false,
  "status": "A",
  "position": 0,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10
}

Campos da resposta

iduuid
Id da caixa.
vendor_iduuid
Seller dono. Ausente nas caixas da loja, que servem a todos os sellers.
namestring
Nome da caixa.
length_mm, width_mm, height_mminteger
Medidas internas em milímetros.
length_cm, width_cm, height_cmnumber
As mesmas medidas em centímetros (calculadas).
max_weight_gramsinteger
Carga máxima em gramas, sem contar a caixa.
max_itemsinteger
Máximo de unidades. 0 = sem limite de unidades (só peso e medidas limitam).
tare_weight_gramsinteger
Peso da caixa vazia, em gramas, somado a cada volume.
dedicatedboolean
true = caixa exclusiva dos produtos em product_ids.
product_idsarray
Produtos que usam a caixa dedicada. Ausente quando não há.
statusstring
AD
A ativa ou D desativada.
positioninteger
Ordem de preferência em empate.

Erros: alterar

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid request body"}
400Regra violada: name is required, medida não positiva, max_weight_grams must be greater than zero, valores negativos, product_ids require a dedicated packaging box ou status fora de A/D. A mensagem cita length_cm/width_cm/height_cm mesmo quando você enviou milímetros.{"error":"failed to update packaging box","detail":"length_cm must be greater than zero"}
404A caixa não existe, é da loja ou de outro seller, ou algum produto não é seu.{"error":"packaging box not found","detail":"packaging box not found"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O módulo correios-shipping está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403O usuário não tem conta de seller.{"error":"no vendor account associated with this user"}
403O usuário não tem o privilégio necessário (vendor_settings).{"error":"insufficient vendor privileges","privilege_required_any":["..."]}

Apagar uma caixa

Apaga uma caixa sua. A exclusão é lógica: pedidos que já usaram a caixa continuam podendo citá-la. Se a caixa tem produtos associados, a plataforma recusa com 409, a menos que você confirme com force=true.

DELETE/api/v1/vendor/shipping/packaging-boxes/{id}Seller

Apaga uma caixa de embalagem do seller

Parâmetros de caminho

iduuidobrigatório
Id da caixa.

Parâmetros de consulta

forcebooleanpadrão: false
true, 1 ou yes para apagar mesmo com produtos associados (as associações são removidas).

Exemplo de requisição: apagar

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/shipping/packaging-boxes/6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d" \
  -H "Authorization: Bearer $TOKEN"

Resposta: apagar

200Caixa apagada
json
{
  "associated_products": 0
}

Campos da resposta

associated_productsinteger
Quantos produtos estavam associados e foram desligados da caixa.

Erros: apagar

StatusQuandoCorpo de exemplo
409A caixa tem produtos associados e force não foi enviado.{"error":"packaging box has associated products","associated_products":3}
404A caixa não existe, é da loja, é de outro seller ou já foi apagada.{"error":"packaging box not found"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O módulo correios-shipping está desligado na loja.{"error":"module_disabled","module":"correios-shipping"}
403O usuário não tem conta de seller.{"error":"no vendor account associated with this user"}
403O usuário não tem o privilégio necessário (vendor_settings).{"error":"insufficient vendor privileges","privilege_required_any":["..."]}
Sem caixas, sem cotação certa

Se o seller apagar todas as caixas e a loja não tiver caixas próprias, o empacotamento não consegue montar volumes e a cotação de algumas formas fica indisponível (no_packaging_registered).

Veja também

  • Volumes e emissão
  • Visão geral
Anterior
Rastreio dos volumes
Próxima
Frete e entrega
Nesta página
  • Listar caixas
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Criar uma caixa
  • Exemplo de requisição: criar
  • Resposta: criar
  • Erros: criar
  • Alterar uma caixa
  • Exemplo de requisição: alterar
  • Resposta: alterar
  • Erros: alterar
  • Apagar uma caixa
  • Exemplo de requisição: apagar
  • Resposta: apagar
  • Erros: apagar
  • Veja também