# 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.

| Tema | Guia |
|---|---|
| Tabela de preços (`default` / `wholesale`) | [Produtos: preços](/guia/produtos-precos) |
| Movimentação e saldo de estoque | [Produtos: estoque](/guia/produtos-estoque) |

---

## 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](/guia/produtos-precos).

**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:

```jsonc
{
  "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

<div class="api-routes">
  <a class="api-route" href="/reference/produtos#tag/produtos/GET/api/products"><span class="api-method api-method-get">GET</span><span class="api-path">/api/products</span></a>
  <a class="api-route" href="/reference/produtos#tag/produtos/POST/api/products"><span class="api-method api-method-post">POST</span><span class="api-path">/api/products</span></a>
  <a class="api-route" href="/reference/produtos#tag/produtos/GET/api/products/{id}"><span class="api-method api-method-get">GET</span><span class="api-path">/api/products/{id}</span></a>
  <a class="api-route" href="/reference/produtos#tag/produtos/PUT/api/products/{id}"><span class="api-method api-method-put">PUT</span><span class="api-path">/api/products/{id}</span></a>
</div>

| Campo | Descrição |
|-------|-----------|
| `id` | ULID, gerado automaticamente. |
| `name` | Nome (máx. 255 caracteres). |
| `sku` | Código único por loja (máx. 50 caracteres). |
| `base_unit` | Unidade de medida. |
| `price_type` | `default` ou `wholesale`. |
| `is_available_for_sale` | Visível no catálogo. |
| `is_industrializable` | Fabricado sob demanda. |
| `allow_sale_without_stock` | Permite venda sem saldo em estoque (sob encomenda). |
| `auto_wholesale_pricing` | Faixas de atacado derivadas automaticamente do % de desconto. Detalhes em [Preços](/guia/produtos-precos). |
| `dimensions` | Altura, largura, comprimento (cm) e peso (kg). |

> 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](/guia/midia). Ele retorna o `image_id`.
2. Vincule à galeria com `POST /api/products/{id}/gallery`.

### Endpoints

<div class="api-routes">
  <a class="api-route" href="/reference/produtos#tag/galeria-de-imagens/GET/api/products/{id}/gallery"><span class="api-method api-method-get">GET</span><span class="api-path">/api/products/{id}/gallery</span></a>
  <a class="api-route" href="/reference/produtos#tag/galeria-de-imagens/POST/api/products/{id}/gallery"><span class="api-method api-method-post">POST</span><span class="api-path">/api/products/{id}/gallery</span></a>
  <a class="api-route" href="/reference/produtos#tag/galeria-de-imagens/DELETE/api/products/{id}/gallery/{image_id}"><span class="api-method api-method-delete">DELETE</span><span class="api-path">/api/products/{id}/gallery/{image_id}</span></a>
  <a class="api-route" href="/reference/produtos#tag/galeria-de-imagens/PUT/api/products/{id}/gallery/thumbnail"><span class="api-method api-method-put">PUT</span><span class="api-path">/api/products/{id}/gallery/thumbnail</span></a>
  <a class="api-route" href="/reference/produtos#tag/galeria-de-imagens/PUT/api/products/{id}/gallery/reorder"><span class="api-method api-method-put">PUT</span><span class="api-path">/api/products/{id}/gallery/reorder</span></a>
</div>

---

## Dados auxiliares

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

<div class="api-routes">
  <a class="api-route" href="/reference/produtos#tag/dados-auxiliares/GET/api/global/enums/product/units"><span class="api-method api-method-get">GET</span><span class="api-path">/api/global/enums/product/units</span></a>
  <a class="api-route" href="/reference/produtos#tag/dados-auxiliares/GET/api/global/enums/product/price-types"><span class="api-method api-method-get">GET</span><span class="api-path">/api/global/enums/product/price-types</span></a>
</div>

---

## Fluxo: cadastro completo

| Etapa | Ação | Onde |
|-------|------|------|
| 1 | Consultar enums | `GET /api/global/enums/product/units` |
| 2 | Criar produto | `POST /api/products` |
| 3 | Definir preço (`default` ou `wholesale`) | [Produtos: preços](/guia/produtos-precos) |
| 4 | Definir estoque inicial | [Produtos: estoque](/guia/produtos-estoque) |
| 5 | Upload de imagens | `POST /api/media/upload` ([Mídia](/guia/midia)) |
| 6 | Vincular à galeria | `POST /api/products/{id}/gallery` |

Depois disso, o produto está pronto para virar **[anúncio](/guia/anuncios)** e ir ao marketplace.