API atual/Referência completa/Kits, mestres e caixas

Caixas de produto

Lista as caixas ativas da loja, abre uma caixa e consulta as variantes de caixa de um produto, com preço efetivo, para vender por grade ou por caixa fechada.

Em lojas de calçados e moda, o produto é vendido por caixa: uma embalagem com uma quantidade fixa de pares por tamanho. A caixa tem um tipo (box_type) e uma grade (size_qty_info), a lista de tamanhos com a quantidade de cada um. Uma variante de caixa liga a caixa a um produto, com a quantidade e o preço daquela combinação.

As três rotas são públicas e dependem do módulo product-boxes ligado (senão 403 {"error":"module_disabled","module":"product-boxes"}). Só aparecem caixas ativas e da loja; caixas criadas por um seller ficam na página dele e não saem aqui.

Tipos de caixa

`box_type`	Significado
`C`	Caixa fechada: todas as unidades do mesmo tamanho.
`G`	Caixa grade: tamanhos sortidos.
`U`	Sem caixa (variante sintética, só na vitrine).
`V`	Caixa variável, de quantidade aberta (variante sintética, só na vitrine).

GET/api/v1/storefront/product-boxesPública

Listar caixas ativas

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 do intervalo volta a 25.

box_typestring

CGUV

Filtra por tipo de caixa.

searchstring

Busca no título e na descrição da caixa (sem diferenciar maiúsculas).

size_variant_idstring

Filtra pela variante de tamanho ligada à caixa (UUID).

langstringpadrão: pt-BR

Idioma do título e da descrição devolvidos (pt-BR, en).

O parâmetro status é aceito mas ignorado: a vitrine sempre filtra por caixas ativas.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/product-boxes?box_type=C&per_page=10"

Resposta

200Caixas retornadas

json

{
  "items": [
    {
      "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
      "box_type": "C",
      "status": "A",
      "size_qty_info": [{ "size": "46", "amount": 1 }],
      "created_at": "2026-07-20T02:47:14.530555Z",
      "updated_at": "2026-07-21T00:22:16.199821Z",
      "title": "Caixa tamanho 46",
      "total_pairs": 1
    }
  ],
  "total": 15,
  "page": 1,
  "per_page": 10
}

Campos da resposta

itemsarray

Caixas da página.

items[].iduuid

Id da caixa.

items[].box_typestring

CGUV

Tipo da caixa.

items[].statusstring

Sempre A nesta rota.

items[].size_qty_infoarray

Grade: lista de {size, amount}, com o tamanho (texto) e a quantidade.

items[].size_variant_iduuid

Variante de tamanho ligada à caixa. Ausente quando não há.

items[].titlestring

Título no idioma pedido. Ausente se a caixa não tem texto nesse idioma.

items[].descriptionstring

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

items[].total_pairsinteger

Soma das quantidades da grade (total de pares da caixa).

items[].created_atstring

Criação (RFC 3339, UTC).

items[].updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

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

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

A lista não traz total_pages: calcule ceil(total / per_page).

Erros

Status	Quando	Corpo
403	Módulo desligado.	`{"error":"module_disabled","module":"product-boxes"}`
500	Falha interna.	`{"error":"internal error","detail":"..."}`

GET/api/v1/storefront/product-boxes/{id}Pública

Detalhe de uma caixa

Devolve uma caixa ativa e da loja, com o texto em todos os idiomas. Caixa inativa, de seller ou inexistente responde 404.

Parâmetros de caminho

iduuidobrigatório

Id da caixa.

Exemplo de requisição (detalhe)

bash

curl "$BASE_URL/api/v1/storefront/product-boxes/fcbde3cd-a90b-435c-90df-9ee2bb438a5f"

Resposta (detalhe)

200Caixa encontrada

json

{
  "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
  "box_type": "C",
  "status": "A",
  "size_qty_info": [{ "size": "46", "amount": 1 }],
  "created_at": "2026-07-20T02:47:14.530555Z",
  "updated_at": "2026-07-21T00:22:16.199821Z",
  "descriptions": {
    "en": { "lang_code": "en", "title": "", "description": "" },
    "pt-BR": { "lang_code": "pt-BR", "title": "Caixa tamanho 46", "description": "" }
  },
  "title": "Caixa tamanho 46",
  "total_pairs": 1
}

Campos da resposta

descriptionsobject

Texto por idioma, indexado pelo código (pt-BR, en). Cada valor tem lang_code, title e description.

Os demais campos são os de um item da lista. O detalhe pode trazer ainda variants (as variantes da caixa), com os campos descritos adiante.

Erros (detalhe)

Status	Quando	Corpo
403	Módulo desligado.	`{"error":"module_disabled","module":"product-boxes"}`
404	Caixa inexistente, inativa ou de seller.	`{"error":"product box not found"}`
500	`id` que não é UUID, ou falha interna.	`{"error":"internal error","detail":"o valor \"abc\" não é um uuid válido. ..."}` (o `detail` volta em português)

GET/api/v1/storefront/products/{productID}/boxesPública

Variantes de caixa de um produto

Para a página do produto: quais caixas existem para ele, com a quantidade e o preço de cada uma. Só entram variantes de caixas ativas e da loja. Devolve até 200 variantes, sem paginação.

Parâmetros de caminho

productIDuuidobrigatório

Id do produto.

Parâmetros de consulta

box_typestring

CGUV

Filtra pelo tipo de caixa da variante.

Exemplo de requisição (variantes)

bash

curl "$BASE_URL/api/v1/storefront/products/0641c3f0-1e2e-434a-ac50-87b2aca6c71a/boxes"

Resposta (variantes)

200Variantes do produto

json

{
  "variants": [
    {
      "id": "b26c0c55-d0c4-4746-84e2-7e1a246fa568",
      "box_id": "bf446c69-239f-481a-8132-87c27b7e78a9",
      "product_id": "0641c3f0-1e2e-434a-ac50-87b2aca6c71a",
      "price_centavos": 999900,
      "effective_price_centavos": 999900,
      "amount": 5,
      "box_type": "C",
      "title": "Caixa com 5 pares",
      "created_at": "2026-07-20T02:37:56.033544Z",
      "updated_at": "2026-07-20T02:37:56.033544Z"
    }
  ]
}

Campos da resposta

variantsarray

Variantes de caixa do produto. Lista vazia quando não há.

variants[].iduuid

Id da variante.

variants[].box_iduuid

Caixa da variante.

variants[].product_iduuid

Produto.

variants[].price_centavosinteger

Preço cadastrado na variante, em centavos. Omitido para visitante quando a loja esconde preço de quem não está logado.

variants[].effective_price_centavosinteger

Preço que o carrinho cobra pela caixa, em centavos. Use este para exibir. Omitido quando o preço é escondido, e também quando a variante não tem preço efetivo calculável.

variants[].amountinteger

Quantidade de unidades da variante.

variants[].box_typestring

CGUV

Tipo da caixa.

variants[].titlestring

Título da caixa em pt-BR. Ausente se vazio.

variants[].descriptionstring

Descrição da caixa. Ausente se vazia.

variants[].product_namestring

Nome do produto. Ausente se vazio.

variants[].product_skustring

SKU do produto. Ausente se vazio.

variants[].created_atstring

Criação (RFC 3339, UTC).

variants[].updated_atstring

Última alteração (RFC 3339, UTC).

Erros (variantes)

Status	Quando	Corpo
403	Módulo desligado.	`{"error":"module_disabled","module":"product-boxes"}`
500	`productID` que não é UUID, ou falha interna.	`{"error":"internal error","detail":"..."}`

Veja também

Caixas de produto

Lista as caixas ativas da loja, abre uma caixa e consulta as variantes de caixa de um produto, com preço efetivo, para vender por grade ou por caixa fechada.

Tipos de caixa

`box_type`	Significado
`C`	Caixa fechada: todas as unidades do mesmo tamanho.
`G`	Caixa grade: tamanhos sortidos.
`U`	Sem caixa (variante sintética, só na vitrine).
`V`	Caixa variável, de quantidade aberta (variante sintética, só na vitrine).

GET/api/v1/storefront/product-boxesPública

Listar caixas ativas

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 do intervalo volta a 25.

box_typestring

CGUV

Filtra por tipo de caixa.

searchstring

Busca no título e na descrição da caixa (sem diferenciar maiúsculas).

size_variant_idstring

Filtra pela variante de tamanho ligada à caixa (UUID).

langstringpadrão: pt-BR

Idioma do título e da descrição devolvidos (pt-BR, en).

O parâmetro status é aceito mas ignorado: a vitrine sempre filtra por caixas ativas.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/product-boxes?box_type=C&per_page=10"

Resposta

200Caixas retornadas

json

{
  "items": [
    {
      "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
      "box_type": "C",
      "status": "A",
      "size_qty_info": [{ "size": "46", "amount": 1 }],
      "created_at": "2026-07-20T02:47:14.530555Z",
      "updated_at": "2026-07-21T00:22:16.199821Z",
      "title": "Caixa tamanho 46",
      "total_pairs": 1
    }
  ],
  "total": 15,
  "page": 1,
  "per_page": 10
}

Campos da resposta

itemsarray

Caixas da página.

items[].iduuid

Id da caixa.

items[].box_typestring

CGUV

Tipo da caixa.

items[].statusstring

Sempre A nesta rota.

items[].size_qty_infoarray

Grade: lista de {size, amount}, com o tamanho (texto) e a quantidade.

items[].size_variant_iduuid

Variante de tamanho ligada à caixa. Ausente quando não há.

items[].titlestring

Título no idioma pedido. Ausente se a caixa não tem texto nesse idioma.

items[].descriptionstring

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

items[].total_pairsinteger

Soma das quantidades da grade (total de pares da caixa).

items[].created_atstring

Criação (RFC 3339, UTC).

items[].updated_atstring

Última alteração (RFC 3339, UTC).

totalinteger

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

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

A lista não traz total_pages: calcule ceil(total / per_page).

Erros

Status	Quando	Corpo
403	Módulo desligado.	`{"error":"module_disabled","module":"product-boxes"}`
500	Falha interna.	`{"error":"internal error","detail":"..."}`

GET/api/v1/storefront/product-boxes/{id}Pública

Detalhe de uma caixa

Devolve uma caixa ativa e da loja, com o texto em todos os idiomas. Caixa inativa, de seller ou inexistente responde 404.

Parâmetros de caminho

iduuidobrigatório

Id da caixa.

Exemplo de requisição (detalhe)

bash

curl "$BASE_URL/api/v1/storefront/product-boxes/fcbde3cd-a90b-435c-90df-9ee2bb438a5f"

Resposta (detalhe)

200Caixa encontrada

json

{
  "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
  "box_type": "C",
  "status": "A",
  "size_qty_info": [{ "size": "46", "amount": 1 }],
  "created_at": "2026-07-20T02:47:14.530555Z",
  "updated_at": "2026-07-21T00:22:16.199821Z",
  "descriptions": {
    "en": { "lang_code": "en", "title": "", "description": "" },
    "pt-BR": { "lang_code": "pt-BR", "title": "Caixa tamanho 46", "description": "" }
  },
  "title": "Caixa tamanho 46",
  "total_pairs": 1
}

Campos da resposta

descriptionsobject

Texto por idioma, indexado pelo código (pt-BR, en). Cada valor tem lang_code, title e description.

Os demais campos são os de um item da lista. O detalhe pode trazer ainda variants (as variantes da caixa), com os campos descritos adiante.

Erros (detalhe)

Status	Quando	Corpo
403	Módulo desligado.	`{"error":"module_disabled","module":"product-boxes"}`
404	Caixa inexistente, inativa ou de seller.	`{"error":"product box not found"}`
500	`id` que não é UUID, ou falha interna.	`{"error":"internal error","detail":"o valor \"abc\" não é um uuid válido. ..."}` (o `detail` volta em português)

GET/api/v1/storefront/products/{productID}/boxesPública

Variantes de caixa de um produto

Para a página do produto: quais caixas existem para ele, com a quantidade e o preço de cada uma. Só entram variantes de caixas ativas e da loja. Devolve até 200 variantes, sem paginação.

Parâmetros de caminho

productIDuuidobrigatório

Id do produto.

Parâmetros de consulta

box_typestring

CGUV

Filtra pelo tipo de caixa da variante.

Exemplo de requisição (variantes)

bash

curl "$BASE_URL/api/v1/storefront/products/0641c3f0-1e2e-434a-ac50-87b2aca6c71a/boxes"

Resposta (variantes)

200Variantes do produto

json

{
  "variants": [
    {
      "id": "b26c0c55-d0c4-4746-84e2-7e1a246fa568",
      "box_id": "bf446c69-239f-481a-8132-87c27b7e78a9",
      "product_id": "0641c3f0-1e2e-434a-ac50-87b2aca6c71a",
      "price_centavos": 999900,
      "effective_price_centavos": 999900,
      "amount": 5,
      "box_type": "C",
      "title": "Caixa com 5 pares",
      "created_at": "2026-07-20T02:37:56.033544Z",
      "updated_at": "2026-07-20T02:37:56.033544Z"
    }
  ]
}

Campos da resposta

variantsarray

Variantes de caixa do produto. Lista vazia quando não há.

variants[].iduuid

Id da variante.

variants[].box_iduuid

Caixa da variante.

variants[].product_iduuid

Produto.

variants[].price_centavosinteger

Preço cadastrado na variante, em centavos. Omitido para visitante quando a loja esconde preço de quem não está logado.

variants[].effective_price_centavosinteger

Preço que o carrinho cobra pela caixa, em centavos. Use este para exibir. Omitido quando o preço é escondido, e também quando a variante não tem preço efetivo calculável.

variants[].amountinteger

Quantidade de unidades da variante.

variants[].box_typestring

CGUV

Tipo da caixa.

variants[].titlestring

Título da caixa em pt-BR. Ausente se vazio.

variants[].descriptionstring

Descrição da caixa. Ausente se vazia.

variants[].product_namestring

Nome do produto. Ausente se vazio.

variants[].product_skustring

SKU do produto. Ausente se vazio.

variants[].created_atstring

Criação (RFC 3339, UTC).

variants[].updated_atstring

Última alteração (RFC 3339, UTC).

Erros (variantes)

Status	Quando	Corpo
403	Módulo desligado.	`{"error":"module_disabled","module":"product-boxes"}`
500	`productID` que não é UUID, ou falha interna.	`{"error":"internal error","detail":"..."}`