VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Selos, kits, mixes e caixas

Caixas de produto

Lista, cria, consulta, altera e exclui as caixas do seller: embalagens fechadas de várias unidades e tamanhos para venda no atacado.

Uma caixa representa uma embalagem fechada de atacado, típica de calçados: uma "caixa grade" com 3 pares do 37, 4 do 38 e 3 do 39 (10 pares), ou uma "caixa fechada" só do 38. Aqui você cadastra a composição e o título da caixa; a ligação da caixa com produtos específicos, com preço e estoque próprios, não é feita por estas rotas.

Módulo necessário

Funciona em lojas que ligam o módulo product-boxes; sem ele a resposta é 403.

Listar

GET/api/v1/vendor/product-boxesSeller

Listar as caixas

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 25
Itens por página, 1 a 200.
statusstring
ADH
Status.
box_typestring
CG
Tipo.
searchstring
Busca no título.
size_variant_idstring (uuid)
Opção de tamanho.
langstringpadrão: pt-BR
Idioma do título.

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/vendor/product-boxes" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Caixas
json
{
  "items": [
    {
      "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
      "box_type": "G",
      "status": "A",
      "size_qty_info": [
        {
          "size": "37",
          "amount": 3
        },
        {
          "size": "38",
          "amount": 4
        },
        {
          "size": "39",
          "amount": 3
        }
      ],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:00:00Z",
      "title": "Caixa grade 37 ao 39",
      "total_pairs": 10
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 25
}

Campos da resposta

itemsarray

Caixas, com title e total_pairs.

idstring (uuid)
Id da caixa.
box_typestring
CG
C caixa fechada (todas as unidades do mesmo tamanho) ou G grade (tamanhos variados).
statusstring
ADH
A ativa, D desativada, H oculta.
size_qty_infoarray
Composição: lista de {size, amount}.
size_variant_idstring (uuid)
Opção de tamanho de referência, se houver.
vendor_idstring (uuid)
Seu seller.
descriptionsobject
Títulos por idioma (só no detalhe).
titlestring
Título no idioma pedido (só na lista).
total_pairsinteger
Soma dos amount da composição (só na lista).
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).
totalinteger
Total.
pageinteger
Página.
per_pageinteger
Itens por página.

Erros (listar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
403O módulo product-boxes está desligado na loja.{"error":"module disabled","detail":"product-boxes: module disabled for tenant"}

Criar

POST/api/v1/vendor/product-boxesSeller

Criar uma caixa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

box_typestringobrigatório
CG
Tipo da caixa.
statusstringpadrão: A
ADH
Status.
size_qty_infoarrayobrigatório

Composição. Ao menos uma linha com size preenchido e amount maior que zero.

sizestringobrigatório
Tamanho, por exemplo 38.
amountintegerobrigatório
Unidades desse tamanho.
descriptionsobjectobrigatório
Títulos por idioma (pt-BR, en...), cada um com lang_code, title, description. Ao menos um título não vazio.
size_variant_idstring (uuid)
Opção de tamanho de referência. Vazio vira nulo.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/product-boxes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "box_type": "G",
  "status": "A",
  "size_qty_info": [
    {
      "size": "37",
      "amount": 3
    },
    {
      "size": "38",
      "amount": 4
    },
    {
      "size": "39",
      "amount": 3
    }
  ],
  "descriptions": {
    "pt-BR": {
      "lang_code": "pt-BR",
      "title": "Caixa grade 37 ao 39",
      "description": "10 pares"
    }
  }
}'

Resposta (criar)

201Caixa criada
json
{
  "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
  "box_type": "G",
  "status": "A",
  "size_qty_info": [
    {
      "size": "37",
      "amount": 3
    },
    {
      "size": "38",
      "amount": 4
    },
    {
      "size": "39",
      "amount": 3
    }
  ],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "descriptions": {
    "pt-BR": {
      "lang_code": "pt-BR",
      "title": "Caixa grade 37 ao 39",
      "description": "10 pares"
    }
  },
  "title": "Caixa grade 37 ao 39",
  "total_pairs": 10
}

Campos da resposta

idstring (uuid)
Id da caixa.
box_typestring
CG
C caixa fechada (todas as unidades do mesmo tamanho) ou G grade (tamanhos variados).
statusstring
ADH
A ativa, D desativada, H oculta.
size_qty_infoarray
Composição: lista de {size, amount}.
size_variant_idstring (uuid)
Opção de tamanho de referência, se houver.
vendor_idstring (uuid)
Seu seller.
descriptionsobject
Títulos por idioma (só no detalhe).
titlestring
Título no idioma pedido (só na lista).
total_pairsinteger
Soma dos amount da composição (só na lista).
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (criar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
400Tipo fora de C/G, status inválido, sem título, ou sem linha de tamanho válida.{"error":"invalid input","detail":"product-boxes: invalid input: box_type must be C or G"}
403O módulo product-boxes está desligado na loja.{"error":"module disabled","detail":"product-boxes: module disabled for tenant"}

Consultar

GET/api/v1/vendor/product-boxes/{id}Seller

Consultar uma caixa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id da caixa.

Exemplo de requisição (consultar)

bash
curl "$BASE_URL/api/v1/vendor/product-boxes/$BOX_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (consultar)

200Caixa
json
{
  "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
  "box_type": "G",
  "status": "A",
  "size_qty_info": [
    {
      "size": "37",
      "amount": 3
    },
    {
      "size": "38",
      "amount": 4
    },
    {
      "size": "39",
      "amount": 3
    }
  ],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "descriptions": {
    "pt-BR": {
      "lang_code": "pt-BR",
      "title": "Caixa grade 37 ao 39",
      "description": "10 pares"
    }
  },
  "title": "Caixa grade 37 ao 39",
  "total_pairs": 10
}

Campos da resposta

idstring (uuid)
Id da caixa.
box_typestring
CG
C caixa fechada (todas as unidades do mesmo tamanho) ou G grade (tamanhos variados).
statusstring
ADH
A ativa, D desativada, H oculta.
size_qty_infoarray
Composição: lista de {size, amount}.
size_variant_idstring (uuid)
Opção de tamanho de referência, se houver.
vendor_idstring (uuid)
Seu seller.
descriptionsobject
Títulos por idioma (só no detalhe).
titlestring
Título no idioma pedido (só na lista).
total_pairsinteger
Soma dos amount da composição (só na lista).
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (consultar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404A caixa não existe ou não é sua.{"error":"product box not found"}
403O módulo product-boxes está desligado na loja.{"error":"module disabled","detail":"product-boxes: module disabled for tenant"}

Alterar

PUT/api/v1/vendor/product-boxes/{id}Seller

Alterar uma caixa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id da caixa.

Corpo da requisição

box_typestring
CG
Tipo da caixa.
statusstring
ADH
Status.
size_variant_idstring (uuid)
Opção de tamanho de referência. Vazio vira nulo.
size_qty_infoarray
Nova composição (substitui).
descriptionsobject
Títulos por idioma; só os idiomas enviados mudam.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/product-boxes/$BOX_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "H"
}'

Resposta (alterar)

200Caixa alterada
json
{
  "id": "fcbde3cd-a90b-435c-90df-9ee2bb438a5f",
  "box_type": "G",
  "status": "H",
  "size_qty_info": [
    {
      "size": "37",
      "amount": 3
    },
    {
      "size": "38",
      "amount": 4
    },
    {
      "size": "39",
      "amount": 3
    }
  ],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z",
  "descriptions": {
    "pt-BR": {
      "lang_code": "pt-BR",
      "title": "Caixa grade 37 ao 39",
      "description": "10 pares"
    }
  },
  "title": "Caixa grade 37 ao 39",
  "total_pairs": 10
}

Campos da resposta

idstring (uuid)
Id da caixa.
box_typestring
CG
C caixa fechada (todas as unidades do mesmo tamanho) ou G grade (tamanhos variados).
statusstring
ADH
A ativa, D desativada, H oculta.
size_qty_infoarray
Composição: lista de {size, amount}.
size_variant_idstring (uuid)
Opção de tamanho de referência, se houver.
vendor_idstring (uuid)
Seu seller.
descriptionsobject
Títulos por idioma (só no detalhe).
titlestring
Título no idioma pedido (só na lista).
total_pairsinteger
Soma dos amount da composição (só na lista).
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (alterar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404A caixa não existe ou não é sua.{"error":"not found","detail":"product-boxes: not found"}
403O módulo product-boxes está desligado na loja.{"error":"module disabled","detail":"product-boxes: module disabled for tenant"}
400Tipo ou status inválidos.{"error":"invalid input","detail":"..."}

Excluir

DELETE/api/v1/vendor/product-boxes/{id}Seller

Excluir uma caixa

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id da caixa.

Exemplo de requisição (excluir)

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/product-boxes/$BOX_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (excluir)

200Caixa excluída
json
{
  "message": "product box deleted"
}

Campos da resposta

messagestring
Confirmação fixa.

Erros (excluir)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404A caixa não existe ou não é sua.{"error":"not found","detail":"product-boxes: not found"}
403O módulo product-boxes está desligado na loja.{"error":"module disabled","detail":"product-boxes: module disabled for tenant"}
Exclusão

A exclusão é lógica: a caixa some das listas, mas o registro é mantido.

Veja também

  • Vitrine e ofertas: visão geral
Anterior
Mixes de produtos
Próxima
Feeds de produtos
Nesta página
  • Listar
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Consultar
  • Exemplo de requisição (consultar)
  • Resposta (consultar)
  • Erros (consultar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Excluir
  • Exemplo de requisição (excluir)
  • Resposta (excluir)
  • Erros (excluir)
  • Veja também