API atual/Guia rápido/Embalagens e caixas

PUTAlterar caixa

Altera o tipo, o status, a composição, os textos e o dono de uma caixa de produto, enviando só os campos que mudam.

Use esta operação para corrigir uma caixa: trocar a composição, ocultá-la da loja, traduzir o título ou passá-la para outro seller. A alteração é parcial: o que você não enviar fica como está.

Para tirar uma caixa da loja sem apagá-la, mude o status para D (desativada) ou H (oculta). Ela deixa de aparecer para os compradores e de ser aceita no carrinho, mas continua cadastrada com as variantes.

PUT/api/v1/admin/product-boxes/{id}Admin

Atualiza uma caixa de produto

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_product_boxes ou manage_catalog. Devolve a caixa completa já alterada.

Parâmetros de caminho

iduuidobrigatório

Id da caixa.

Corpo da requisição

box_typestring

CG

Novo tipo. Outro valor dá 400.

statusstring

ADH

Novo status. Outro valor dá 400.

size_qty_infoarray

Substitui a composição inteira. Cada item tem size e amount. Diferente da criação, a alteração não confere se há ao menos uma linha utilizável: não envie uma lista vazia.

size_variant_idstring

Novo valor de tamanho. Envie string vazia ("") para desligar a ligação.

descriptionsobject

Textos por idioma, no mesmo formato da criação. Só os idiomas enviados são regravados; os outros ficam intactos.

vendor_idstring

Passa a caixa para este seller (UUID). Envie string vazia ("") para torná-la uma caixa da loja.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/product-boxes/959af717-ae72-427b-a497-58d3ff422cc8" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"D"}'

Resposta

200Caixa alterada

json

{
  "id": "959af717-ae72-427b-a497-58d3ff422cc8",
  "box_type": "G",
  "status": "D",
  "size_qty_info": [
    { "size": "37", "amount": 2 },
    { "size": "38", "amount": 4 }
  ],
  "created_at": "2026-10-11T20:54:25.363347Z",
  "updated_at": "2026-10-11T20:54:29.638022Z",
  "descriptions": {
    "pt-BR": { "lang_code": "pt-BR", "title": "Grade 37 e 38", "description": "Grade com 6 pares" }
  },
  "variants": [],
  "title": "Grade 37 e 38",
  "description": "Grade com 6 pares",
  "total_pairs": 6
}

A resposta é a caixa completa, com os campos de Consultar caixa.

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	`box_type` ou `status` inválido	`{"error":"invalid input","detail":"product-boxes: invalid input: invalid status \"X\""}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo `product-boxes` desligado, ou sem privilégio	`{"error":"module_disabled","module":"product-boxes"}`
404	Caixa não existe ou foi excluída	`{"error":"not found","detail":"product-boxes: not found"}`
500	`id`, `size_variant_id` ou `vendor_id` que não é UUID, ou falha interna	`{"error":"internal error","detail":"..."}`

Veja também