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 com SKUs válidos.
• Preços configurados (base e/ou atacado).
• Estoque disponível nos locais de venda.
• Imagens já enviadas via Mídia (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 — 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 — 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 — 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):

{
  "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.

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.

Etapa 1. Buscar categoria

GET/api/categories/search

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

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.

Etapa 2. Consultar atributos

GET/api/categories/{id}/attributes

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.

Etapa 3. Gerar combinações

POST/api/categories/{id}/combine-attributes

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:

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

POST/api/items/simulate

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

POST/api/items/create

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

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

GET/api/items/{id}/review-checklist

Antes de publicar, confira o que falta:

{
  "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.

PUT/api/items/{id}/publish

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:

GET/api/items/catalog/publications

GET/api/items/catalog/{itemId}/options

POST/api/items/catalog/options/{optionId}/attach-sku

{
  "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.

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.

Upload de imagens é compartilhado entre produtos e anúncios — está documentado em Mídia e no guia de Imagens.