API atual/Guia rápido/Embalagens e caixas

GETConsultar caixa

Retorna uma caixa de produto com a composição, as descrições de todos os idiomas e as variantes (os produtos ligados a ela).

Use esta operação para abrir uma caixa: conferir a composição, ler os textos de cada idioma e ver a quais produtos ela está ligada, com o preço e o estoque de cada um. É a única leitura que traz descriptions e variants juntos.

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

Consulta uma caixa de produto

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_product_boxes ou manage_catalog. Uma caixa excluída responde 404.

Parâmetros de caminho

iduuidobrigatório

Id da caixa.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/product-boxes/959af717-ae72-427b-a497-58d3ff422cc8" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Caixa retornada

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" }
  },
  "variants": [
    {
      "id": "d77cf791-d92e-4be8-828d-23e97e3d8eea",
      "box_id": "959af717-ae72-427b-a497-58d3ff422cc8",
      "product_id": "1d22de37-ab3b-422d-82ef-275b8257691d",
      "price_centavos": 59940,
      "amount": 10,
      "box_type": "G",
      "created_at": "2026-10-11T20:54:29.57382Z",
      "updated_at": "2026-10-11T20:54:29.57382Z",
      "product_name": "Chinelo Slim Preto",
      "product_sku": "SD-004387"
    }
  ],
  "title": "Grade 37 e 38",
  "description": "Grade com 6 pares",
  "total_pairs": 6
}

Os campos da caixa são os de Listar caixas. Os campos extras desta leitura:

Campos da resposta

descriptionsobject

Texto por idioma. A chave é o código do idioma e o valor tem lang_code, title e description.

variantsarray

Produtos ligados à caixa. Ausente quando não há nenhum.

variants[].iduuid

Id da variante (a ligação caixa x produto). É o id usado para alterar ou remover a variante.

variants[].product_iduuid

Produto ligado.

variants[].price_centavosinteger

Preço da caixa para este produto, em centavos. 0 significa "preço do produto vezes os pares".

variants[].amountinteger

Caixas disponíveis. 0 significa "sem contador por caixa" (vale o estoque do produto).

variants[].box_typestring

CG

Tipo da caixa, repetido na variante.

variants[].product_namestring

Nome do produto.

variants[].product_skustring

SKU do produto.

Erros

Status	Quando	Corpo
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":"product box not found"}`
500	`id` que não é UUID	`{"error":"internal error","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`

Veja também

GETConsultar caixa

Retorna uma caixa de produto com a composição, as descrições de todos os idiomas e as variantes (os produtos ligados a ela).

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

Consulta uma caixa de produto

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_product_boxes ou manage_catalog. Uma caixa excluída responde 404.

Parâmetros de caminho

iduuidobrigatório

Id da caixa.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/product-boxes/959af717-ae72-427b-a497-58d3ff422cc8" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Caixa retornada

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" }
  },
  "variants": [
    {
      "id": "d77cf791-d92e-4be8-828d-23e97e3d8eea",
      "box_id": "959af717-ae72-427b-a497-58d3ff422cc8",
      "product_id": "1d22de37-ab3b-422d-82ef-275b8257691d",
      "price_centavos": 59940,
      "amount": 10,
      "box_type": "G",
      "created_at": "2026-10-11T20:54:29.57382Z",
      "updated_at": "2026-10-11T20:54:29.57382Z",
      "product_name": "Chinelo Slim Preto",
      "product_sku": "SD-004387"
    }
  ],
  "title": "Grade 37 e 38",
  "description": "Grade com 6 pares",
  "total_pairs": 6
}

Os campos da caixa são os de Listar caixas. Os campos extras desta leitura:

Campos da resposta

descriptionsobject

Texto por idioma. A chave é o código do idioma e o valor tem lang_code, title e description.

variantsarray

Produtos ligados à caixa. Ausente quando não há nenhum.

variants[].iduuid

Id da variante (a ligação caixa x produto). É o id usado para alterar ou remover a variante.

variants[].product_iduuid

Produto ligado.

variants[].price_centavosinteger

Preço da caixa para este produto, em centavos. 0 significa "preço do produto vezes os pares".

variants[].amountinteger

Caixas disponíveis. 0 significa "sem contador por caixa" (vale o estoque do produto).

variants[].box_typestring

CG

Tipo da caixa, repetido na variante.

variants[].product_namestring

Nome do produto.

variants[].product_skustring

SKU do produto.

Erros

Status	Quando	Corpo
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":"product box not found"}`
500	`id` que não é UUID	`{"error":"internal error","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}`