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

Variantes da caixa

Liga uma caixa a um produto com preço e estoque próprios, e lista, altera ou remove essas ligações.

A variante é a ligação entre uma caixa e um produto. É ela que coloca a caixa à venda: sem variante, a caixa existe mas nenhum produto a oferece. Cada variante guarda o preço da caixa inteira para aquele produto e quantas caixas há para vender.

Um produto pode ter várias caixas (uma grade e uma fechada, por exemplo), e uma caixa pode servir a vários produtos. O par (caixa, produto) é único: ligar o mesmo produto duas vezes à mesma caixa dá 409.

Esta página reúne as quatro rotas de variante.

Como o preço e o estoque são lidos
  • price_centavos é o preço da caixa, em centavos, não o de um par. Com 0, a plataforma cobra o preço do produto vezes o número de pares da caixa.
  • amount é o número de caixas em estoque. Com 0, não há contador por caixa e vale o estoque do produto. Acima de zero, cada compra reduz o contador, e um pedido por mais caixas do que o contador é recusado.
  • Só aparecem para o comprador as variantes de caixas ativas (A) cujo produto também está ativo. Caixa de seller só vale para produto do mesmo seller.
GET/api/v1/admin/product-boxes/{id}/variantsAdmin

Lista as variantes de uma caixa

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

Parâmetros de caminho

iduuidobrigatório
Id da caixa.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora desse intervalo volta ao padrão (50).
product_iduuid
Somente a variante deste produto.
box_typestring
CG
Filtra pelo tipo da caixa gravado na variante.
langstringpadrão: pt-BR
Idioma de title e description na resposta.
POST/api/v1/admin/product-boxes/{id}/variantsAdmin

Vincula uma caixa a um produto

Cria a variante. Responde 201 com a variante completa.

Parâmetros de caminho

iduuidobrigatório
Id da caixa (UUID).

Corpo da requisição

product_iduuidobrigatório
Produto que vai oferecer a caixa. O servidor valida o formato, mas não confere se o produto existe: um id errado cria uma variante sem produto, que nunca é vendida. Confira o id antes.
price_centavosintegerpadrão: 0
Preço da caixa inteira, em centavos (59940 = R$ 599,40). Não pode ser negativo. 0 usa o preço do produto vezes os pares.
amountintegerpadrão: 0
Caixas em estoque. Não pode ser negativo. 0 usa o estoque do produto.
box_typestring
CG
Tipo gravado na variante. Se omitido, copia o tipo da caixa. O ideal é omitir.
PUT/api/v1/admin/product-boxes/variants/{variantId}Admin

Atualiza o preço e o estoque de uma variante

Altera só price_centavos e amount. A caixa e o produto de uma variante não mudam: para trocá-los, remova a variante e crie outra.

Parâmetros de caminho

variantIduuidobrigatório
Id da variante (o id devolvido na criação ou na lista; não é o id da caixa).

Corpo da requisição

price_centavosintegerobrigatório
Novo preço da caixa, em centavos. Um campo omitido vale 0, e zera o valor gravado. Envie sempre os dois campos.
amountintegerobrigatório
Novo estoque de caixas. Um campo omitido vale 0.
DELETE/api/v1/admin/product-boxes/variants/{variantId}Admin

Remove a variant

Remove a ligação de vez (não é soft delete). A caixa e o produto continuam existindo. Responde 204.

Parâmetros de caminho

variantIduuidobrigatório
Id da variante.

Exemplo de requisição

bash
# ligar a caixa a um produto
curl -X POST "$BASE_URL/api/v1/admin/product-boxes/959af717-ae72-427b-a497-58d3ff422cc8/variants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"1d22de37-ab3b-422d-82ef-275b8257691d","price_centavos":59940,"amount":10}'

# ajustar preço e estoque (use o id da variante)
curl -X PUT "$BASE_URL/api/v1/admin/product-boxes/variants/d77cf791-d92e-4be8-828d-23e97e3d8eea" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_centavos":54900,"amount":8}'

Resposta

201Variante criada
json
{
  "id": "d77cf791-d92e-4be8-828d-23e97e3d8eea",
  "box_id": "959af717-ae72-427b-a497-58d3ff422cc8",
  "product_id": "1d22de37-ab3b-422d-82ef-275b8257691d",
  "price_centavos": 59940,
  "amount": 10,
  "box_type": "G",
  "created_at": "2026-10-11T20:54:29.57382Z",
  "updated_at": "2026-10-11T20:54:29.57382Z",
  "product_name": "Chinelo Slim Preto",
  "product_sku": "SD-004387"
}
200Lista de variantes
json
{
  "items": [
    {
      "id": "d77cf791-d92e-4be8-828d-23e97e3d8eea",
      "box_id": "959af717-ae72-427b-a497-58d3ff422cc8",
      "product_id": "1d22de37-ab3b-422d-82ef-275b8257691d",
      "price_centavos": 59940,
      "amount": 10,
      "box_type": "G",
      "product_name": "Chinelo Slim Preto",
      "product_sku": "SD-004387",
      "title": "Grade 37 e 38",
      "description": "Grade com 6 pares"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Campos da resposta

iduuid
Id da variante.
box_iduuid
Caixa.
product_iduuid
Produto.
price_centavosinteger
Preço da caixa para este produto, em centavos.
amountinteger
Caixas em estoque.
box_typestring
CG
Tipo da caixa.
product_namestring
Nome do produto. Ausente quando o produto não existe.
product_skustring
SKU do produto.
titlestring
Só na lista: título da caixa no idioma pedido.
descriptionstring
Só na lista: descrição da caixa no idioma pedido.
created_atstring
Criação, RFC 3339 em UTC. O updated_at traz a última alteração.
itemsarray
Na lista: as variantes da página. Acompanham total, page e per_page.

Erros

StatusQuandoCorpo
400Corpo não é JSON válido{"error":"invalid request body","detail":"..."}
400product_id ausente{"error":"invalid input","detail":"product-boxes: invalid input: product_id is required"}
400product_id ou id da caixa que não é UUID{"error":"invalid uuid","detail":"product-boxes: invalid uuid: product_id must be a UUID"}
400Preço ou estoque negativo; box_type diferente de C e G{"error":"invalid input","detail":"product-boxes: invalid input: price_centavos must be >= 0"}
401Token ausente ou expirado{"error":"invalid or expired token"}
403Módulo product-boxes desligado, ou sem privilégio{"error":"module_disabled","module":"product-boxes"}
404Caixa excluída ou inexistente (criação sem box_type no corpo), ou variante inexistente (alteração e exclusão){"error":"not found","detail":"product-boxes: not found"}
409O produto já está ligado a esta caixa{"error":"duplicate variant","detail":"product-boxes: duplicate variant for product"}
500Caixa inexistente com box_type informado no corpo, ou falha interna{"error":"internal error","detail":"o registro referenciado não existe (campo relacionado a ...). Crie ou confira esse registro antes de vinculá-lo."}
O PUT zera o que você não enviar

A alteração grava price_centavos e amount exatamente como vieram. Um corpo com só {"amount": 8} coloca o preço em 0, e a plataforma passa a cobrar o preço do produto vezes os pares. Reenvie sempre os dois valores.

Veja também

  • Consultar caixa
  • Criar caixa
  • Excluir caixa
Anterior
Excluir caixa
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também