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 abaixo; 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) — a chave só aparece quando preenchido
  "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, blocked.

Você não vai achar um endpoint pra mandar o anúncio para paused, inactive ou blocked. Os três são estados administrativos: quem os aciona é a plataforma (por exemplo, ao suspender um anúncio que violou alguma regra ou bloqueá-lo em moderação). 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

Cada atributo vem com flags (is_required, is_variant, is_combinable, ...) e uma definição de valor autodescritiva. Parâmetros de filtro (matrix, only_features, only_variations), como interpretar as flags e como montar o payload de cada tipo estão 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 (default: o primeiro atributo); veja o que ele faz com as fotos em Imagens.

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: só dígitos, quantidade igual ao type (8, 12, 13 ou 14) e dígito verificador GS1 correto. Espaços, pontos e hífens são removidos antes da validação.
• 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

GTIN no anúncio de catálogo. Nos anúncios do catálogo central o GTIN é obrigatório e não pode ser alterado depois da criação: ele é a identidade do produto e compõe o slug da página pública. No anúncio próprio (default) é opcional e editável via PUT /api/items/{item_id} — omita a chave para manter, envie null para limpar.

Os type aceitos numa ficha técnica: technical_specification, characteristics, materials, installation, maintenance, safety, environmental e custom.

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": "missing_required_attribute", "severity": "error", "message": "Atributo obrigatório não preenchido: Marca", "field": "attributes" },
      { "code": "missing_short_description", "severity": "warning", "message": "Recomendamos preencher a descrição curta para melhor exibição em listagens.", "field": "short_description" }
    ],
    "checks": [
      { "code": "image",               "label": "Pelo menos uma imagem",             "ok": true },
      { "code": "title",               "label": "Título preenchido",                 "ok": true },
      { "code": "short_description",   "label": "Descrição curta preenchida",        "ok": false },
      { "code": "description",         "label": "Descrição detalhada preenchida",    "ok": true },
      { "code": "required_attributes", "label": "Atributos obrigatórios da categoria","ok": false },
      { "code": "sku",                 "label": "SKU vinculado",                     "ok": true }
    ]
  }
}

São duas listas com papéis diferentes: checks é o placar fixo dos seis itens avaliados, sempre completo; issues traz só o que está pendente, com a mensagem e o field correspondente. Repare que os códigos não se repetem entre as duas — o check image vira a issue missing_image, e um atributo obrigatório faltando gera uma issue missing_required_attributepor atributo.

Issues com severity: "error" bloqueiam a publicação e derrubam o ready para false; warning (como a descrição curta) é só recomendação e não impede publicar.

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.

Quantidade mínima e escala de preço

As ofertas (e as variações) do anúncio devolvem três campos somente leitura, herdados da configuração do SKU. Você não os envia no create nem no publish: eles descrevem como aquela oferta pode ser comprada.

Regra de compra

Com allow_fractional_quantity: false (padrão) e mínimo maior que 1, só são aceitos múltiplos exatos do mínimo. Um mínimo de 25 aceita 25, 50 e 75, e rejeita 30. Com allow_fractional_quantity: true, basta atingir o mínimo: 25, 30 e 41 passam.

Unidades físicas, não packs

O mínimo é sempre contado em unidades físicas, nunca em packs. A conta é a quantidade do item multiplicada pelo multiplicador da variação (caixa com 6, fardo com 12). Uma variação "caixa com 6" com 3 caixas no carrinho equivale a 18 unidades físicas, e é esse 18 que é comparado ao min_purchase_quantity.

Conflito na publicação (422)

O min_purchase_quantity do SKU precisa ser divisível pelo multiplicador da variação. Se não for, a publicação do anúncio é reprovada com 422 e a resposta traz um mínimo alcançável sugerido (o múltiplo válido mais próximo).

Exemplo do conflito: mínimo 25 numa variação "caixa com 6". Não existe número de caixas que resulte em 25 unidades (4 caixas dão 24, 5 caixas dão 30), então o anúncio não publica.

Há duas saídas:

• Ajustar o mínimo no SKU para um múltiplo do multiplicador (no exemplo, 24 ou 30, conforme a sugestão devolvida no 422) e publicar de novo.
• Ligar allow_fractional_quantity no SKU, o que dispensa a exigência de múltiplo exato e libera a publicação.

A escala e o mínimo são configurados no SKU (guia de Produtos). O anúncio apenas os expõe para que o comprador e o integrador saibam como montar a quantidade.

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, score de qualidade, conteúdo, atributos, variações e fichas técnicas. Na referência de anúncios, cada assunto aparece em uma seção própria: Gestão de Anúncios, Conteúdo do Anúncio, Atributos e Variações e Fichas Técnicas.

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