# Produtos

Os produtos são o núcleo do catálogo da sua loja. No painel de administração, você pode criar, editar e organizar produtos — cada um com título, descrição, preços, imagens e características personalizadas. Tudo o que você configura aqui é refletido na loja visível para os clientes.

## Navegando pelos seus produtos

Abra **Products** na barra lateral do painel de administração para ver a lista completa de produtos. A tabela exibe o título, slug, SKU, status, preço e estoque de cada produto.

![Lista de produtos](/features/products/products-list.png)

| Coluna | Descrição                                          |
| ------ | -------------------------------------------------- |
| Title  | Nome do produto com miniatura (clique para editar) |
| Slug   | Caminho da URL usado na loja                       |
| SKU    | Unidade de manutenção de estoque para rastreamento |
| Status | **Active** (visível para clientes) ou **Inactive** |
| Price  | Preço de venda atual na moeda da loja              |
| Stock  | Quantidade disponível em estoque                   |

Você pode **ordenar** clicando no cabeçalho de qualquer coluna e **pesquisar** digitando na barra de busca. Use o botão **Filter** para filtrar por faixa de preço ou status.

## Ações em massa

Selecione um ou mais produtos usando as caixas de seleção à esquerda e use a barra de ações em massa que aparece na parte inferior:

- **Activate** — torna os produtos selecionados visíveis na loja
- **Deactivate** — oculta os produtos selecionados dos clientes
- **Delete** — remove permanentemente os produtos selecionados (uma confirmação será exibida)

## Criando um produto

Clique em **New Product** na página da lista de produtos para abrir o formulário de criação.

![Formulário de criação de produto](/features/products/create-product-top.png)

### Detalhes do produto

| Campo             | Obrigatório | Descrição                                                                                                         |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| Title             | Sim         | Nome do produto exibido para os clientes. Gera automaticamente um slug de URL.                                    |
| Slug              | Sim         | Identificador amigável para URL (minúsculas com hífens). Gerado automaticamente a partir do título, mas editável. |
| Short Description | Não         | Resumo breve exibido nos cards de produto em coleções e resultados de busca.                                      |
| Description       | Sim         | Descrição completa exibida na página de detalhes do produto. Pode ser gerada com IA se habilitada.                |
| Base Price        | Sim         | Preço de venda atual (sem imposto). Exibido com destaque na loja, recalculado para incluir o imposto na exibição B2C. |
| Show Previous Price Reduction | Não | Habilita a exibição de uma redução de preço. O valor riscado na loja usa o menor preço dos últimos 30 dias, conforme a Diretiva Omnibus da UE (veja [Reduções de preço](#reducoes-de-preco-diretiva-omnibus-da-ue) abaixo). |
| Measure Value & Measure Unit | Não | Par opcional de campos para [preço unitário](#preco-unitario) (ex.: €/kg, €/L). Ambos devem ser preenchidos juntos. |
| Stock             | Sim         | Estoque disponível. Quando chega a zero, o botão **Add to Basket** é substituído por **Out of Stock**.            |
| SKU               | Não         | Unidade de manutenção de estoque para rastreamento interno. Deve ser único se informado.                          |
| Collection        | Não         | Atribui o produto a uma coleção (categoria). Afeta a navegação breadcrumb na loja.                                |
| Tax Rule          | Não         | Regra de cálculo de impostos. Definida automaticamente para a regra padrão, se existir.                           |
| Active            | Não         | Controla a visibilidade na loja. Produtos são inativos por padrão.                                                |

> **Dica:** Se sua loja tem integrações de IA habilitadas, você pode clicar no botão de geração com IA ao lado do campo Description para criar automaticamente uma descrição do produto a partir do título.

### Prévia de imposto no formulário

Abaixo do campo Base Price o formulário exibe o **price with tax** que o cliente verá (preços na loja sempre incluem imposto para conformidade B2C na UE). Quando a regra de imposto atribuída tem sobreposições por país, um botão **View per-country prices** abre um detalhamento do preço final que cada país pagará, para que você possa conferir os valores antes de salvar.

### Características

Características são atributos personalizados de chave-valor que descrevem seu produto (ex.: Material, Tamanho, Cor). Clique em **Add Characteristic** para adicionar uma nova linha.

![Criação de produto — características e mídia](/features/products/create-product-bottom.png)

- **Key** — selecione uma chave existente ou digite uma nova para criá-la
- **Value** — texto livre (ex.: "100% Algodão Orgânico", "Grande", "Vermelho")

Você pode adicionar quantas características precisar. Elas aparecem em um acordeão **Product Characteristics** retrátil na loja.

### Mídia

Faça upload de imagens e vídeos do produto usando a área de upload de arquivos. Você pode enviar vários arquivos de uma vez.

- A **primeira imagem** é usada como miniatura do produto na lista e nos cards de produto
- As imagens aparecem em um **carrossel** na página de detalhes do produto, na ordem em que foram enviadas

## Editando um produto

Clique no título de qualquer produto na lista (ou na ação de edição no menu da linha) para abrir o formulário de edição. Ele contém os mesmos campos do formulário de criação, preenchidos com os dados atuais do produto.

![Editar produto](/features/products/edit-product.png)

Clique em **Save Changes** quando terminar. Você também pode excluir o produto na seção de zona de perigo na parte inferior da página de edição.

## Como os produtos aparecem na loja

Cada campo que você configura no painel de administração corresponde a um elemento específico na página do produto visível para os clientes.

![Página do produto na loja](/features/products/storefront-product.png)

| Campo admin       | Exibição na loja                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| Title             | Título grande no topo da página e na trilha de navegação (breadcrumb)                                 |
| Description       | Parágrafo de texto abaixo do botão de adicionar ao carrinho                                           |
| Short Description | Subtítulo nos cards de produto (coleções, resultados de busca, página inicial)                        |
| Base Price        | Preço atual exibido com destaque, sempre incluindo imposto                                            |
| Show Previous Price Reduction | Quando habilitado e o preço atual está abaixo do mínimo de 30 dias, o mínimo de 30 dias é exibido riscado ao lado do preço atual (estilo de promoção em vermelho) |
| Measure Value / Unit | Renderiza uma linha "por kg" / "por L" / etc. abaixo do preço nos cards, na página do produto, na coleção e na busca |
| Stock > 0         | Botão **Add to Basket** está habilitado                                                               |
| Stock = 0         | Botão muda para **Out of Stock** e fica desabilitado                                                  |
| Active            | Apenas produtos ativos são visíveis para os clientes                                                  |
| Media             | Carrossel de imagens com miniaturas laterais (desktop) e carrossel deslizante (mobile), mais lightbox |
| Collection        | Aparece no breadcrumb (Home > Coleção > Produto) e como rótulo de marca acima do título               |
| Characteristics   | Acordeão retrátil **Product Characteristics** com lista de chave-valor                                |
| Slug              | Determina a URL do produto (ex.: `/product/organic-cotton-t-shirt`)                                   |

### Reduções de preço (Diretiva Omnibus da UE)

Capyshop segue a Diretiva Omnibus da UE para reduções de preço. Para anunciar uma promoção, baixe o **Base Price** do produto abaixo do que ele esteve nos últimos 30 dias e ative **Show Previous Price Reduction**. A loja então exibirá riscado o **menor preço dos últimos 30 dias** (não um valor anterior digitado manualmente) — esse é o preço de referência exigido por lei.

O formulário dá feedback em tempo real enquanto você edita:

- **Redução será exibida** — o formulário confirma o riscado que o cliente verá, ex.: "Customers will see €18.00 with €24.00 struck through (the 30-day lowest price)".
- **Nenhuma redução será exibida** — se o Base Price atual não estiver abaixo do mínimo de 30 dias, o formulário avisa que nenhuma badge de promoção aparecerá, mesmo com o toggle ativo.

As alterações de preço são registradas automaticamente sempre que um produto ou variante é salvo. Um cron de limpeza semanal remove o histórico com mais de 90 dias, mantendo o armazenamento controlado enquanto a janela de 30 dias permanece intacta.

### Preço unitário

O preço unitário mostra ao cliente uma taxa normalizada "por kg" / "por L" / "por m" / "por m²" abaixo do preço nos cards, na página do produto, na coleção e nos resultados de busca. É exigido pelas regras da UE para muitas categorias de produtos e também é exportado para o [feed do Google Merchant Center](https://support.google.com/merchants/answer/6324509) como `unit_pricing_measure` e `unit_pricing_base_measure`.

Defina **Measure Value** e **Measure Unit** no produto:

- **Measure Value** — a quantidade mensurável do produto (ex.: `750`).
- **Measure Unit** — a unidade de medida (kg, g, L, ml, m, cm, m²).

O Capyshop converte para a unidade base apropriada (kg, L, m, m²) ao exibir a taxa por unidade. Produtos vendidos por item — produtos contáveis — estão isentos do preço unitário pela diretiva e devem deixar esses campos vazios.

### Experiência mobile

Em dispositivos móveis, a página do produto se adapta com um carrossel de imagens em largura total (com navegação por deslizar e barra de progresso) e um **botão fixo Add to Basket** na parte inferior da tela para fácil acesso durante a rolagem.

![Produto na loja em mobile](/features/products/storefront-product-mobile.png)

## Páginas legíveis por máquina para LLMs

Cada página de produto tem uma versão `.md` que retorna markdown puro, projetada para ferramentas de IA e LLMs consumirem facilmente:

- `/product/{slug}.md` — detalhes completos do produto incluindo descrição, preço, estoque, características e imagens

Esses endpoints retornam conteúdo `text/markdown` com URLs absolutas para imagens e links.