API atual/Guia rápido/Embalagens e caixas

POSTCriar caixa

Cria uma caixa de produto (grade ou caixa fechada) com a composição de tamanhos e os títulos por idioma.

Use esta operação para cadastrar uma nova caixa: por exemplo, "Grade 37 e 38" com 2 pares do 37 e 4 pares do 38. Criar a caixa não a coloca à venda: ela só passa a valer para um produto depois de ligada a ele por uma variante, que traz o preço e o estoque.

A caixa nasce ativa (status A) se você não disser outro. Para ela ser aceita é preciso ter um título não vazio em pelo menos um idioma e ao menos uma linha de composição com tamanho e quantidade maior que zero.

POST/api/v1/admin/product-boxesAdmin

Cria uma caixa de produto

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_product_boxes ou manage_catalog.

Corpo da requisição

box_typestringobrigatório

CG

C caixa fechada (todos os pares do mesmo tamanho) ou G grade (tamanhos variados). Outro valor dá 400.

size_qty_infoarrayobrigatório

Composição da caixa. Precisa ter ao menos uma linha com size não vazio e amount maior que zero.

sizestringobrigatório

Tamanho, em texto ("37", "M").

amountintegerobrigatório

Quantidade de pares daquele tamanho dentro da caixa.

descriptionsobjectobrigatório

Textos por idioma. A chave é o código do idioma (pt-BR, en...). Pelo menos um idioma precisa ter title com texto.

{lang}.lang_codestring

Código do idioma, o mesmo da chave.

{lang}.titlestring

Título da caixa naquele idioma.

{lang}.descriptionstring

Descrição da caixa naquele idioma.

statusstringpadrão: A

ADH

Status inicial. Só caixas A aparecem na loja.

size_variant_idstring

Valor de tamanho (id do valor da característica de tamanho) a que a caixa está ligada. String vazia é tratada como ausente.

legacy_box_idinteger

Número da caixa no sistema de origem, usado em migrações. Guarda a correspondência com o cadastro anterior.

vendor_iduuid

Seller dono da caixa. Omita para uma caixa da loja, que vale para qualquer produto. Uma caixa de seller só vale para produtos do mesmo seller.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/product-boxes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "box_type": "G",
    "status": "A",
    "size_qty_info": [
      { "size": "37", "amount": 2 },
      { "size": "38", "amount": 4 }
    ],
    "descriptions": {
      "pt-BR": { "lang_code": "pt-BR", "title": "Grade 37 e 38", "description": "Grade com 6 pares" }
    }
  }'

Resposta

201Caixa criada

json

{
  "id": "959af717-ae72-427b-a497-58d3ff422cc8",
  "box_type": "G",
  "status": "A",
  "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:25.363347Z",
  "descriptions": {
    "pt-BR": { "lang_code": "pt-BR", "title": "Grade 37 e 38", "description": "Grade com 6 pares" }
  },
  "title": "Grade 37 e 38",
  "description": "Grade com 6 pares",
  "total_pairs": 6
}

A resposta é a caixa completa, com os campos de Consultar caixa. Guarde o id: é ele que você usa para criar variantes.

Erros

Status	Quando	Corpo
400	Corpo não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	`box_type` diferente de `C` e `G`	`{"error":"invalid input","detail":"product-boxes: invalid input: box_type must be C or G"}`
400	`status` fora de `A`, `D`, `H`	`{"error":"invalid input","detail":"product-boxes: invalid input: invalid status \"X\""}`
400	Sem título em nenhum idioma	`{"error":"invalid input","detail":"product-boxes: invalid input: title is required"}`
400	Sem nenhuma linha de composição utilizável	`{"error":"invalid input","detail":"product-boxes: invalid input: at least one size_qty_info row (size + amount > 0) is required"}`
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"}`
500	`size_variant_id` ou `vendor_id` que não é UUID, ou falha interna	`{"error":"internal error","detail":"..."}`

Veja também