API atual/Guia rápido/Embalagens e caixas

GETListar caixas

Retorna as caixas de produto da loja, com filtros por status, tipo, texto e tamanho, e paginação.

Use esta operação para ver as caixas cadastradas: montar uma tela de gestão, conferir se uma grade já existe antes de criá-la ou sincronizar com o cadastro de um ERP. A lista traz o resumo de cada caixa. Para ver as descrições de todos os idiomas e as variantes (os produtos ligados), abra a caixa com Consultar caixa.

A lista do administrador mostra todas as caixas, as da loja e as de sellers, em qualquer status, menos as excluídas. Exige o módulo product-boxes ligado (veja a home da seção).

GET/api/v1/admin/product-boxesAdmin

Lista as caixas de produto

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

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 200. Fora desse intervalo volta ao padrão (25), não é limitado.

statusstring

ADH

Filtra pelo status. Outro valor não dá erro, só não encontra nada.

box_typestring

CG

C caixa fechada, G grade.

searchstring

Texto contido no título ou na descrição da caixa, em qualquer idioma, sem diferenciar maiúsculas de minúsculas.

size_variant_idstring

Somente caixas ligadas a este valor de tamanho (id do valor da característica de tamanho).

langstringpadrão: pt-BR

Idioma do title e da description devolvidos.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/product-boxes?status=A&box_type=G&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Caixas retornadas

json

{
  "items": [
    {
      "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",
      "title": "Grade 37 e 38",
      "description": "Grade com 6 pares",
      "total_pairs": 6
    }
  ],
  "total": 14,
  "page": 1,
  "per_page": 50
}

Campos da resposta

itemsarray

Caixas da página, da mais nova para a mais antiga.

items[].iduuid

Id da caixa.

items[].box_typestring

CG

C fechada, G grade.

items[].statusstring

ADH

Ativa, desativada ou oculta.

items[].size_qty_infoarray

Composição: cada item tem size (texto) e amount (inteiro, quantidade de pares daquele tamanho).

items[].size_variant_idstring

Valor de tamanho a que a caixa está ligada, quando houver. Ausente quando não há.

items[].legacy_box_idinteger

Número da caixa no sistema de origem, quando ela foi migrada de outro sistema. Ausente nas demais.

items[].vendor_iduuid

Seller dono da caixa. Ausente quando a caixa é da loja.

items[].titlestring

Título no idioma pedido.

items[].descriptionstring

Descrição no idioma pedido. Ausente quando vazia.

items[].total_pairsinteger

Soma das quantidades de size_qty_info: quantos pares a caixa tem.

items[].created_atstring

Criação, RFC 3339 em UTC.

items[].updated_atstring

Última alteração, RFC 3339 em UTC.

totalinteger

Total de caixas que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

Erros

Status	Quando	Corpo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo `product-boxes` desligado	`{"error":"module_disabled","module":"product-boxes"}`
403	Sem o privilégio `manage_product_boxes` ou `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_product_boxes","manage_catalog"]}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna	`{"error":"internal error","detail":"..."}`

Veja também

GETListar caixas

Retorna as caixas de produto da loja, com filtros por status, tipo, texto e tamanho, e paginação.

A lista do administrador mostra todas as caixas, as da loja e as de sellers, em qualquer status, menos as excluídas. Exige o módulo product-boxes ligado (veja a home da seção).

GET/api/v1/admin/product-boxesAdmin

Lista as caixas de produto

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

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 200. Fora desse intervalo volta ao padrão (25), não é limitado.

statusstring

ADH

Filtra pelo status. Outro valor não dá erro, só não encontra nada.

box_typestring

CG

C caixa fechada, G grade.

searchstring

Texto contido no título ou na descrição da caixa, em qualquer idioma, sem diferenciar maiúsculas de minúsculas.

size_variant_idstring

Somente caixas ligadas a este valor de tamanho (id do valor da característica de tamanho).

langstringpadrão: pt-BR

Idioma do title e da description devolvidos.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/product-boxes?status=A&box_type=G&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Caixas retornadas

json

{
  "items": [
    {
      "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",
      "title": "Grade 37 e 38",
      "description": "Grade com 6 pares",
      "total_pairs": 6
    }
  ],
  "total": 14,
  "page": 1,
  "per_page": 50
}

Campos da resposta

itemsarray

Caixas da página, da mais nova para a mais antiga.

items[].iduuid

Id da caixa.

items[].box_typestring

CG

C fechada, G grade.

items[].statusstring

ADH

Ativa, desativada ou oculta.

items[].size_qty_infoarray

Composição: cada item tem size (texto) e amount (inteiro, quantidade de pares daquele tamanho).

items[].size_variant_idstring

Valor de tamanho a que a caixa está ligada, quando houver. Ausente quando não há.

items[].legacy_box_idinteger

Número da caixa no sistema de origem, quando ela foi migrada de outro sistema. Ausente nas demais.

items[].vendor_iduuid

Seller dono da caixa. Ausente quando a caixa é da loja.

items[].titlestring

Título no idioma pedido.

items[].descriptionstring

Descrição no idioma pedido. Ausente quando vazia.

items[].total_pairsinteger

Soma das quantidades de size_qty_info: quantos pares a caixa tem.

items[].created_atstring

Criação, RFC 3339 em UTC.

items[].updated_atstring

Última alteração, RFC 3339 em UTC.

totalinteger

Total de caixas que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

Erros

Status	Quando	Corpo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo `product-boxes` desligado	`{"error":"module_disabled","module":"product-boxes"}`
403	Sem o privilégio `manage_product_boxes` ou `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_product_boxes","manage_catalog"]}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna	`{"error":"internal error","detail":"..."}`