VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/Embalagens e caixas

Listar e consultar caixas

Lista as caixas de produto (grades e caixas fechadas) e consulta uma caixa pelo id, na API legada.

Esta página reúne as duas leituras de caixas. Para o conceito de caixa, variante, preço e estoque, leia primeiro a home da seção.

Listar caixas

Devolve as caixas de produto da loja, com paginação e filtros. É a primeira chamada de quem sincroniza o cadastro de grades e caixas fechadas.

GET/api/v1.0/product_boxesAdmin

Listar caixas

A rota exige o módulo product-boxes ligado na loja; sem ele responde erro com a mensagem product-boxes: module disabled for tenant. Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 250. Fora desse intervalo vale 10.
statusstring
ADH
Filtra pelo status.
box_typestring
CG
C fechada, G grade.
searchstring
Texto no título ou na descrição.
GET/api/v1.0/productboxesAdmin

Listar caixas (nome sem sublinhado)

Esta é a grafia sem sublinhado (productboxes), que o aplicativo do seller usa. É o mesmo código, com a mesma resposta. Como as demais rotas desta família, ela também responde sem o prefixo de versão (/api/productboxes), com os ids em número decimal dentro de uma string.

Exemplo de requisição

Resposta

200Caixas retornadas

Campos da resposta

product_boxesarray
Lista de caixas. Cada item tem os campos abaixo.
product_boxes[].box_idstring
UUID da caixa. Se a caixa veio de uma plataforma anterior (tem número legado), este campo traz o número legado em string e o UUID vai em uuid.
product_boxes[].uuidstring
UUID da caixa. Só aparece quando box_id é o número legado.
product_boxes[].box_typestring
CG
Tipo da caixa: C fechada, G grade.
product_boxes[].statusstring
ADH
A ativa, D desativada, H oculta.
product_boxes[].size_qty_infoarray
Composição: size e amount de cada linha.
product_boxes[].size_variant_idstring
Valor de tamanho ligado, ou string vazia.
product_boxes[].titlestring
Título em pt-BR (ou o do idioma padrão, se não houver pt-BR).
product_boxes[].descriptionstring
Descrição, no mesmo idioma do título.
product_boxes[].lang_codestring
pt-BR, quando o título veio desse idioma.
product_boxes[].timestampinteger
Criação, Unix timestamp em segundos.
paramsobject
Paginação: page, items_per_page, total_items.

Erros

StatusQuandoCorpo
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha interna, ou módulo product-boxes desligado{"message":"product-boxes: module disabled for tenant","status":500}
Pontos de atenção

As caixas de produto não têm medidas nem peso e não entram na cotação de frete. Os textos vêm do idioma pt-BR (ou do padrão da loja).

Consultar uma caixa

Devolve uma caixa pelo id. Aceita o UUID ou o número legado.

GET/api/v1.0/product_boxes/{boxID}Admin

Consultar uma caixa

A rota exige o módulo product-boxes ligado na loja; sem ele responde erro com a mensagem product-boxes: module disabled for tenant. Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

boxIDstringobrigatório
Id da caixa: o UUID ou, se a caixa veio de uma plataforma anterior, o número legado.
GET/api/v1.0/productboxes/{boxID}Admin

Consultar uma caixa (nome sem sublinhado)

Esta é a grafia sem sublinhado (productboxes), que o aplicativo do seller usa. É o mesmo código, com a mesma resposta. Como as demais rotas desta família, ela também responde sem o prefixo de versão (/api/productboxes), com os ids em número decimal dentro de uma string.

Exemplo de requisição

Resposta

200Caixa devolvida

Os campos são os mesmos de cada item da listagem.

Erros

StatusQuandoCorpo
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
404A caixa não existe{"message":"product box not found","status":404}
500Falha interna, ou módulo product-boxes desligado{"message":"product-boxes: module disabled for tenant","status":500}
Ids na forma sem versão

Na forma /api/... o box_id sai como número decimal em string e esse número não é aceito de volta no caminho (responde 404). Use o UUID.

Veja também

  • Embalagens e caixas
  • Listar e consultar caixas
  • Variantes
Anterior
Embalagens e caixas
Próxima
Criar caixa
Nesta página
  • Listar caixas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma caixa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/product_boxes?status=A&items_per_page=50"
bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/product_boxes/959af717-ae72-427b-a497-58d3ff422cc8"
json
{
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 18
  },
  "product_boxes": [
    {
      "box_id": "959af717-ae72-427b-a497-58d3ff422cc8",
      "box_type": "G",
      "status": "A",
      "size_qty_info": [
        {
          "size": "37",
          "amount": 2
        },
        {
          "size": "38",
          "amount": 4
        }
      ],
      "size_variant_id": "",
      "title": "Grade 37 e 38",
      "description": "Grade com 6 pares",
      "lang_code": "pt-BR",
      "timestamp": 1791752065
    }
  ]
}
json
{
  "box_id": "959af717-ae72-427b-a497-58d3ff422cc8",
  "box_type": "G",
  "status": "A",
  "size_qty_info": [
    {
      "size": "37",
      "amount": 2
    },
    {
      "size": "38",
      "amount": 4
    }
  ],
  "size_variant_id": "",
  "title": "Grade 37 e 38",
  "description": "Grade com 6 pares",
  "lang_code": "pt-BR",
  "timestamp": 1791752065
}