API legada/Guia rápido/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

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/product_boxes?status=A&items_per_page=50"

Resposta

200Caixas retornadas

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
    }
  ]
}

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

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

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

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)

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/product_boxes/959af717-ae72-427b-a497-58d3ff422cc8"

Resposta

200Caixa devolvida

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
}

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

Erros

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

Veja também

API legada/Guia rápido/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

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)

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/product_boxes?status=A&items_per_page=50"

Resposta

200Caixas retornadas

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
    }
  ]
}

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

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

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

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)

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/product_boxes/959af717-ae72-427b-a497-58d3ff422cc8"

Resposta

200Caixa devolvida

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
}

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

Erros

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