# Guia de Anúncios

Cadastrar um produto não o coloca à venda — quem aparece na vitrine é o **anúncio**. Este guia mostra os dois caminhos para vender no marketplace:

1. **Publicar um anúncio próprio** — você cria a página do produto do zero: categoria, atributos, imagens, descrição.
2. **Ofertar em um anúncio de catálogo** — o anúncio já existe na plataforma; você só pluga o seu SKU como uma oferta.

---

## Pré-requisitos

- **[Produtos cadastrados](/guia/produtos)** com SKUs válidos.
- **Preços** configurados (base e/ou atacado).
- **Estoque** disponível nos locais de venda.
- **Imagens** já enviadas via [Mídia](/guia/midia) (`POST /api/media/upload`).

---

## Conceitos

Os três pilares de um anúncio têm guias próprios — vale ler antes da primeira publicação:

- **[Categorias](/guia/anuncios-categorias)** — todo anúncio nasce numa categoria folha da árvore (departamento → níveis → folha). É a categoria que define quais atributos se aplicam.
- **[Atributos e variações](/guia/anuncios-atributos)** — características do produto (marca, material) e o que diferencia cada variação (cor, tamanho, voltagem), incluindo os tipos de valor e a cor customizada.
- **[Imagens](/guia/anuncios-imagens)** — como vincular as imagens enviadas pela Mídia ao anúncio e a cada variação.

O objeto do anúncio, de relance (resposta de `POST /items/create` — recorte; a resposta completa traz mais campos, como `slug`, `price_range` e `short_description`):

```jsonc
{
  "item_id": "SAM-0000000000007", // ID do anúncio (prefixo da plataforma + 13 dígitos)
  "title": "Caixa de Som JBL Go!",
  "type":   {…},                  // { value, label } — "default" = anúncio próprio
  "status": {…},                  // { value, label } — status do anúncio
  "gtin":   {…},                  // código de barras (type, value)
  "store":  {…},                  // loja (store_id, store_name, store_code, …)
  "department": {…},              // departamento (id, name, icon_svg)
  "category":   {…},              // categoria (id, parent_id, name, hierarchy)
  "score":  {…},                  // qualidade do anúncio
  "rejection_reason": null        // preenchido quando a revisão devolve pra draft
}
```

## Status do anúncio

`draft`, `pending_review`, `active`, `paused`, `inactive`.

```mermaid
stateDiagram-v2
    direction LR
    [*] --> draft: POST /items/create
    draft --> pending_review: PUT /publish
    pending_review --> active: aprovado<br/>(operador)
    pending_review --> draft: rejeitado<br/>(volta pra ajuste<br/>com rejection_reason)
```

> Você não vai achar um endpoint pra mandar o anúncio para `paused` ou `inactive` — e isso é proposital. Esses dois são estados administrativos: quem os aciona é a plataforma (por exemplo, ao suspender um anúncio que violou alguma regra). Do seu lado, você conduz o anúncio pelo caminho que controla — `draft` → `pending_review` → `active` — e deixa os estados administrativos por conta de quem cuida da moderação.

---

## Fluxo 1 — Publicar um anúncio próprio

A etapa 3 só roda se o produto tiver variações; sem variações, da 2 você vai direto pra 4.

```mermaid
flowchart TD
    E1[1. Buscar categoria<br/>GET /categories/search] --> E2[2. Consultar atributos<br/>GET /categories/id/attributes]
    E2 --> Q{Tem atributos<br/>com is_combinable?}
    Q -->|não| E4
    Q -->|sim| E3[3. Gerar combinações<br/>POST /categories/id/combine-attributes]
    E3 --> E4[4. Validar<br/>POST /items/simulate]
    E4 --> E5[5. Criar rascunho<br/>POST /items/create]
    E5 --> E6[6. Checklist + publicar<br/>PUT /items/id/publish]
```

| Etapa | Ação | Endpoint |
|-------|------|----------|
| 1 | Buscar categoria | `GET /api/categories/search` |
| 2 | Consultar atributos | `GET /api/categories/{id}/attributes` |
| 3 | Gerar combinações (se houver variações) | `POST /api/categories/{id}/combine-attributes` |
| 4 | Validar anúncio | `POST /api/items/simulate` |
| 5 | Criar rascunho | `POST /api/items/create` |
| 6 | Conferir checklist e publicar | `PUT /api/items/{id}/publish` |

### Etapa 1. Buscar categoria

<a class="api-route" href="/reference/anuncios#tag/categorias/GET/api/categories/search"><span class="api-method api-method-get">GET</span><span class="api-path">/api/categories/search</span></a>

Retorna apenas categorias folhas (último nível). Parâmetros:

| Parâmetro | Para quê |
|-----------|----------|
| `search` | Termo de busca (obrigatório). |
| `departament_id` | Filtrar por departamento. |

Para navegar pela hierarquia nível a nível, use `GET /api/categories/browse`; para listar departamentos, `GET /api/categories/departaments`. Os três endpoints — e a receita de quando usar cada um — estão no guia de [Categorias](/guia/anuncios-categorias).

### Etapa 2. Consultar atributos

<a class="api-route" href="/reference/anuncios#tag/publicacao/GET/api/categories/{category_id}/attributes"><span class="api-method api-method-get">GET</span><span class="api-path">/api/categories/{id}/attributes</span></a>

| Parâmetro | Para quê |
|-----------|----------|
| `matrix=true` | Agrupa atributos por seção (Identificação, Técnico, ...). Sem ele, a resposta é uma lista plana. |
| `only_features=1` | Apenas características do produto. |
| `only_variations=1` | Apenas atributos de variação. |

> `only_features` e `only_variations` juntos retornam **422** — escolha um.

Cada atributo vem com flags (`is_required`, `is_variant`, `is_combinable`, ...) e uma definição de valor autodescritiva. Como interpretar tudo isso — e como montar o payload de cada tipo — está no guia de [Atributos e variações](/guia/anuncios-atributos).

### Etapa 3. Gerar combinações

<a class="api-route" href="/reference/anuncios#tag/publicacao/POST/api/categories/{category_id}/combine-attributes"><span class="api-method api-method-post">POST</span><span class="api-path">/api/categories/{id}/combine-attributes</span></a>

Se a etapa 2 retornou atributos com `is_combinable: true`, o produto pode ter variações (cor + tamanho, voltagem + cor...). Esse endpoint recebe os valores escolhidos e devolve o produto cartesiano pronto para virar o array `variations[]` do create:

```json
{
  "attributes": {
    "1": ["110 V", "220 V"],
    "3": ["Azul", "Verde"]
  },
  "primary_attribute_id": 1
}
```

Resultado: 4 combinações (110 V/Azul, 110 V/Verde, 220 V/Azul, 220 V/Verde), em `data.combinations`, acompanhadas de `data.primary_attribute`. O `primary_attribute_id` define o atributo principal usado para **organizar as fotos por variação** (default: o primeiro atributo).

> Produto sem variações? Pule direto para a etapa 4.

### Etapa 4. Validar anúncio

<a class="api-route" href="/reference/anuncios#tag/publicacao/POST/api/items/simulate"><span class="api-method api-method-post">POST</span><span class="api-path">/api/items/simulate</span></a>

Mesmo body da criação. Verifica:

- Atributos obrigatórios da categoria preenchidos.
- GTIN válido, quando informado (8, 12, 13 ou 14 dígitos).
- Formato dos dados (`description.layout`, `description.raw_content`, `technical_sheets[]`).
- Estrutura das variações.
- SKUs existentes na loja, com preço e estoque ativos.
- IDs de imagem existentes na plataforma.

Resposta **200** = pronto para criar. Erros de negócio (ex.: SKU sem estoque) voltam **422** com o motivo em `data.reason` e detalhes em `data.details`.

### Etapa 5. Criar anúncio

<a class="api-route" href="/reference/anuncios#tag/publicacao/POST/api/items/create"><span class="api-method api-method-post">POST</span><span class="api-path">/api/items/create</span></a>

```json
{
  "title": "Caixa de Som JBL Go!",
  "category_id": 121,
  "gtin": { "type": 13, "value": "6925281995583" },
  "attributes": [
    { "id": 1, "value_id": 3, "value": "HyperX" }
  ],
  "variations": [
    {
      "seller_sku": "FK-JBL-2000-AZUL",
      "attributes": [
        { "attribute_id": 1, "attribute_name": "Voltagem", "value": "110 V" }
      ],
      "images": [{ "id": "{{image_id}}" }]
    }
  ],
  "images": [{ "id": "{{image_id}}" }],
  "description": {
    "layout": "markdown",
    "raw_content": "## Caixa de Som JBL Go!\n\nSom potente, bateria de longa duração e resistência à água."
  },
  "technical_sheets": [
    {
      "type": "technical_specification",
      "title": "Especificações Técnicas",
      "items": [
        { "item_key": "Potência", "item_value": "4,2W RMS", "display_order": 0 },
        { "item_key": "Bateria",  "item_value": "5 horas",  "display_order": 1 }
      ]
    }
  ]
}
```

#### Campos

| Campo | Obrigatório | Descrição |
|-------|-------------|-----------|
| `title` | Sim | Título do anúncio (máx. 100 caracteres). |
| `category_id` | Sim | ID da categoria (etapa 1). |
| `seller_sku` | Quando não há `variations` | SKU do produto vendido no anúncio sem variações. |
| `variations` | Quando não há `seller_sku` | Variações com SKU, atributos e imagens próprias (etapa 3). |
| `images` | Não* | IDs das imagens enviadas via [Mídia](/guia/anuncios-imagens). *Opcional no create, mas o checklist exige pelo menos 1 pra publicar. |
| `gtin` | Não | Código de barras (`type`: 8, 12, 13 ou 14). |
| `attributes` | Não | Características do produto (etapa 2). |
| `description` | Não | `{ layout, raw_content }`. Aceita também string (legado, equivale a `layout=markdown`). |
| `technical_sheets` | Não | Lista de fichas (`type`, `title`, `items[]`). |

> Os SKUs informados precisam **existir previamente** na loja, com preço e estoque configurados — o create não cria SKU.

> Preenchendo `description` e `technical_sheets` no `create` você dispensa chamadas a `PUT /description` e `POST /technical-sheets`. Esses endpoints continuam disponíveis para edição posterior.

O anúncio nasce como **`draft`**. Nesse status você pode editar tudo livremente.

### Etapa 6. Checklist e publicação

<a class="api-route" href="/reference/anuncios#tag/publicacao/GET/api/items/{publication_id}/review-checklist"><span class="api-method api-method-get">GET</span><span class="api-path">/api/items/{id}/review-checklist</span></a>

Antes de publicar, confira o que falta:

```json
{
  "data": {
    "ready": false,
    "issues": [
      { "code": "required_attributes", "severity": "error", "message": "Preencha os atributos obrigatórios da categoria.", "field": "attributes" },
      { "code": "short_description", "severity": "warning", "message": "Uma descrição curta melhora a conversão.", "field": "short_description" }
    ],
    "checks": [
      { "code": "image",               "label": "Pelo menos 1 imagem",      "ok": true },
      { "code": "title",               "label": "Título preenchido",        "ok": true },
      { "code": "short_description",   "label": "Descrição curta",          "ok": false },
      { "code": "description",         "label": "Descrição preenchida",     "ok": true },
      { "code": "required_attributes", "label": "Atributos obrigatórios",   "ok": false },
      { "code": "sku",                 "label": "SKU vinculado",            "ok": true }
    ]
  }
}
```

Issues com `severity: "error"` bloqueiam a publicação; `warning` (como a descrição curta) é só recomendação.

<a class="api-route" href="/reference/anuncios#tag/publicacao/PUT/api/items/{publication_id}/publish"><span class="api-method api-method-put">PUT</span><span class="api-path">/api/items/{id}/publish</span></a>

O `publication_id` é o `item_id` retornado no `create` (ex.: `SAM-0000000000007`). Status muda para `pending_review`.

> Se chamar `publish` com pendências bloqueantes, vem **422** com o campo `checklist` no topo da resposta indicando o que falta.

Após a aprovação pela plataforma, o anúncio fica **`active`** e disponível para compra. Se for rejeitado, ele volta para `draft` com o motivo em `rejection_reason` — ajuste e publique de novo.

---

## Fluxo 2 — Ofertar em anúncio de catálogo

Quando o produto que você vende já tem um anúncio de catálogo na plataforma (criado pela operação), você não cria outra página: **anexa o seu SKU como oferta** em uma variação do anúncio existente. As ofertas das lojas competem pela melhor posição (buybox).

O caminho em três passos — localize o anúncio de catálogo, escolha a variação e anexe o SKU:

<a class="api-route" href="/reference/anuncios#tag/catálogo-e-ofertas/GET/api/items/catalog/publications"><span class="api-method api-method-get">GET</span><span class="api-path">/api/items/catalog/publications</span></a>

<a class="api-route" href="/reference/anuncios#tag/catálogo-e-ofertas/GET/api/items/catalog/{itemId}/options"><span class="api-method api-method-get">GET</span><span class="api-path">/api/items/catalog/{itemId}/options</span></a>

<a class="api-route" href="/reference/anuncios#tag/catálogo-e-ofertas/POST/api/items/catalog/options/{optionId}/attach-sku"><span class="api-method api-method-post">POST</span><span class="api-path">/api/items/catalog/options/{optionId}/attach-sku</span></a>

```json
{
  "seller_sku": "FK-JBL-2000-AZUL",
  "status": "active"
}
```

- O anúncio de catálogo precisa estar **ativo**; o SKU precisa existir na sua loja com preço e estoque.
- `status` é opcional (default `active`).
- A resposta traz a oferta criada (`offer_id`) com snapshot de preço e estoque. A posição na buybox é recalculada em segundo plano — logo após o attach, `is_buybox_winner` costuma vir `false`.
- Mesma variação + mesmo SKU duplicado → **409**.

Depois, acompanhe e gerencie suas ofertas em `GET /api/items/catalog/my-offers` e `PUT`/`DELETE /api/items/catalog/offers/{offerId}` — tudo na seção **Catálogo e Ofertas** da [referência](/reference/anuncios).

---

## Depois de publicado

A gestão do anúncio também é toda por API — listagem com filtros (`GET /api/items`), detalhe, edição de título/descrição/atributos, variações, fichas técnicas e o score de qualidade. Está documentada na seção **Gestão de Anúncios** da [referência](/reference/anuncios).

> Upload de imagens é compartilhado entre produtos e anúncios — está documentado em [Mídia](/guia/midia) e no guia de [Imagens](/guia/anuncios-imagens).