Produtos & variantes

Quando usar Products

Use products sempre que tiver um catálogo — múltiplos itens vendidos com preço, estoque e potencialmente variações. Casos típicos:

• E-commerce físico — roupas (com variações de tamanho/cor), eletrônicos, livros
• Produtos digitais — e-books, presets, templates, downloads
• SaaS / aplicativos — assinatura mensal/anual de software
• Hospedagem / aluguel temporário — Airbnb-like, hotéis, casas de temporada
• Mídias com autor — livros, audiobooks com referência ao autor

Se você só tem um produto destaque (ou contrato sob medida), considere uma Página ou um Serviço em vez de Products.

Os 4 schemas disponíveis

Diferente de Pages e Publications (que têm 11 schemas comuns), Products usa o conjunto PRODUCT_OPTIONS com apenas 4 — cada um com subtypes específicos:

Wizard estendido (10 etapas)

Diferente das 4 etapas padrão (Tipo, Básico, Metadados, Mídia), Products tem 6 etapas extras de commerce — totalizando 10 etapas. Você pode pular o que não usa, mas elas estão lá:

1. Padrão

   Tipo

   Schema (Product / SoftwareApplication / Book / VacationRental) + subtype.

2. Padrão

   Básico

   Título, slug, descrição, permalink (segue hierarquia da coleção).

3. Padrão

   Metadados

   Status (rascunho / publicado), autor (apenas Book/Audiobook).

4. Padrão

   Mídia

   4 slots (imagem destacada, vídeo, áudio, documento).

5. Commerce

   Comércio

   Tipo de compra, SKU, físico/digital/download, dimensões para frete.

6. Commerce

   Preços

   Múltiplos preços (Stripe-first), one-time ou recorrente, preço de comparação.

7. Commerce

   Variantes

   Shopify-style — lista de SKUs, cada um com preço/estoque/dimensões próprios.

8. Var-scoped

   Atributos (por variante)

   Pares chave/valor livres — cor, tamanho, tier, etc.

9. Commerce

   Estoque

   Depósito, fornecedor, quantidade, ponto de reposição, custo.

10. Commerce

    Templates

    Variantes de layout (versão 1 só com Page Builder; templates de seção em construção).

Etapa Commerce

A primeira etapa específica de Products. Define a natureza do produto (vai ser vendido direto, é digital ou físico, precisa de frete) e o SKU:

Tipos de compra (purchaseType)

Três modos de "como o cliente compra". Cada um muda o comportamento do botão CTA na página do produto:

Apenas direct_sale aciona toggles de estoque e o checkout — os outros dois geram leads em vez de pedidos.

Etapa Prices

Todos os preços são Stripe-first: ao salvar o produto, eles vão pro seu Stripe Connect e ganham um price_id. Um produto pode ter múltiplos preços (planos diferentes) — exatamente 1 marcado como default.

Existem 2 tipos de preço (priceType):

Campos de cada preço

• nickname — apelido interno ("Mensal", "Anual", "Black Friday")
• description — descrição opcional mostrada ao cliente
• amount + currency — valor em centavos + moeda (default BRL)
• priceType — one_time ou recurring
• recurringInterval — só pra recorrente: month ou year
• recurringIntervalCount — a cada N intervalos (ex.: 2 + month = bimestral)
• trialPeriodDays — dias de teste grátis (só recorrente)
• compareAtAmount — preço "de" para mostrar desconto (riscado no card)
• isDefault — exatamente um deve ser default (radio entre todos os preços do produto)
• isActive — desativar sem deletar (preserva histórico Stripe)

Atalhos rápidos

A tela tem 3 botões pra acelerar: Adicionar pontual, Adicionar mensal, Adicionar anual. Eles criam preços com nicknames e configurações pré-preenchidas — você só ajusta o valor.

Etapa Variants (Shopify-style)

Toda Products no UlaNano segue o modelo Shopify: o "produto" é uma casca (título, descrição, imagens) e a lista de variações é onde mora o commerce real (SKU, preço, estoque, dimensões).

1 variante é sempre marcada como default (estrela dourada). É essa que aparece quando o cliente abre a página do produto. Outras viram opções selecionáveis (cor, tamanho, etc.).

Comportamento das variantes

• Adicionar variante abre um side panel com formulário próprio (Atributos + Commerce + Inventário + Mídia)
• Click na linha abre o painel pra editar
• Click na estrela marca como default (radio — só uma por vez)
• X vermelho remove a variante. Se remover a default e ainda houver variantes, a primeira da lista vira default automaticamente
• Variante herda título do pai, mas você pode override por variante (em Attributes)

Etapa Attributes (por variante)

Atributos são pares chave/valor livres que você define por variante. Não há "axes globais" — cada variante traz suas próprias chaves:

O painel de atributos da variante também tem:

• Override de título — texto que substitui o título do pai (ex.: "Camiseta básica preta tamanho M")
• Override de descrição — descrição específica desta variante
• Status próprio — uma variante pode estar publicada e outra em rascunho

Etapa Inventory

Estoque é por warehouse (depósito). Você seleciona um warehouse e preenche os 4 campos básicos:

Campos detalhados

• warehouseId — depósito onde o estoque está armazenado
• quantityAvailable — quantos itens prontos pra venda
• reorderPoint — quando o saldo cai abaixo disso, a plataforma alerta para repor
• reorderQuantity — quantos pedir quando o ponto for atingido
• costPerItem — quanto te custa cada unidade (usado no cálculo de margem)
• supplierId — fornecedor padrão deste produto
• supplierSku — código do produto no fornecedor (diferente do seu SKU)
• costPrice — preço pago no fornecedor
• minimumOrderQuantity — pedido mínimo permitido pelo fornecedor
• leadTimeDays — quantos dias entre pedir e receber
• isPreferred — toggle marcando como fornecedor preferencial

Movimentos de estoque (9 tipos)

Toda mudança no quantityAvailable é registrada como um movimento — auditoria completa de quando e por que o estoque mudou. O sistema reconhece 9 tipos:

Cada movimento traz: tipo, quantidade (positiva ou negativa), data, autor e observação. Você consegue auditar o histórico de qualquer SKU.

Etapa Templates

Templates de produto são variantes de layout da página final — algo como "Hero centralizado + grade de variações + reviews abaixo" vs "Hero lateral + specs em coluna". Cada template muda apenas o visual, não os dados.

Na versão atual, esta etapa serve principalmente para escolher entre layouts pré-feitos quando aplicáveis. Para customização total, use o editor visual (Page Builder) que permite editar tudo livremente.

Suppliers & Warehouses

Warehouses e Suppliers são entidades separadas no workspace, cadastradas em telas próprias antes de criar produtos:

• Warehouses — endereços físicos onde o estoque mora. Pode ter múltiplos (matriz, filial, dropshipping). Cada produto tem estoque por warehouse
• Suppliers — fornecedores que abastecem você. Cada produto pode ter um fornecedor preferencial + alternativos

Cadastre-os em Workspace → Estoque → Depósitos e Workspace → Estoque → Fornecedores antes de iniciar o catálogo. Vamos ter páginas dedicadas para cada um na seção Loja.

Categorias (hierarquia)

Como Publications, Products também aceita coleções aninhadas — categorias e subcategorias do catálogo. O permalink é construído pela árvore:

• /produtos — coleção raiz
• /produtos/eletronicos — categoria
• /produtos/eletronicos/notebooks — subcategoria
• /produtos/eletronicos/notebooks/dell-xps-13 — produto final

Cada coleção vira automaticamente uma CollectionPage listando seus filhos publicados — você ganha página de categoria sem precisar criar manualmente.

Import em massa

Para catálogos grandes, use /documents/products/import. Formatos aceitos:

• CSV — linhas com colunas para título, slug, sku, preço, estoque, fornecedor, etc. O mais comum
• XLSX — mesmas colunas do CSV, mas em planilha. Bom pra quem usa Excel/Google Sheets
• JSON — para migrações de sistemas customizados (Shopify export, WooCommerce export)
• Shopify CSV — formato nativo da Shopify (auto-detectado quando as colunas batem)