Visão geral

Cadastro do produto base: especificações, galeria, enums e o fluxo completo de cadastro. Preços e estoque têm guias próprios.

Conceitos

Unidade de medida (base_unit):un, pc, cx, pct, kg, lt, mt, m2, m3.

Tipo de preço (price_type):default (valor único) ou wholesale (até 5 faixas progressivas por quantidade). Detalhes em Preços.

Disponibilidade:is_available_for_sale controla a visibilidade do produto no catálogo. is_industrializable indica produto fabricado sob demanda.

Dimensões (obrigatórias para frete):dimensions.height, dimensions.width, dimensions.length (cm) e dimensions.weight (kg). Todos os valores devem ser no mínimo 0.001.

O objeto que GET /products/{id} devolve — produto, preços e estoque juntos:

{
  "product": {
    "id": "01H8X…",             // ID do produto
    "name": "Produto Exemplo A",
    "sku": "SKU-001",           // único por loja
    "base_unit": "un",          // ← Unidade de medida
    "price_type": "default",    // ← Tipo de preço (default | wholesale)
    "dimensions": {…},          // ← Dimensões (cm) + peso (kg)
    "is_available_for_sale": true, // ← Disponibilidade no catálogo
    "is_industrializable": false,  // fabricado sob demanda
    "auto_wholesale_pricing": false, // atacado por % de desconto (ver Preços)
    "allow_sale_without_stock": false, // venda sem estoque (sob encomenda)
    "quantity": 100,            // estoque físico
    "reserved_quantity": 5,     // reservado em pedidos abertos
    "available_quantity": 95,   // disponível p/ venda
    "thumbnail": {              // imagem principal
      "id": "01JMZ…",           // ID da imagem
      "resources": [{…}]        // variações (name, size, url)
    },
    "price": 50.0               // preço-base (faixa min_quantity=1)
  },
  "prices": [{…}],              // faixas de preço (ver Preços)
  "stock":  [{…}]               // saldo por local (ver Estoque)
}

Produto

O sku é definido na criação e não pode ser alterado: se vier no PUT /api/products/{id}, é simplesmente ignorado.

Sublojas em modo espelho não criam SKU próprio — o catálogo vem da matriz. O POST /api/products responde 422 SUBSTORE_CANNOT_CREATE_SKU.

Galeria

Cada produto suporta até 6 imagens. A primeira é a thumbnail por padrão; se ela for removida, a próxima imagem assume o lugar.

Fluxo de upload

1. Suba o arquivo via Mídia. Ele retorna o image_id.
2. Vincule à galeria com POST /api/products/{id}/gallery.

Endpoints

Dados auxiliares

Rotas públicas (sem autenticação). Use pra popular dropdowns no seu sistema.

Fluxo: cadastro completo

Depois disso, o produto está pronto para virar anúncio e ir ao marketplace.