Anúncios · Imagens

As imagens do anúncio seguem o fluxo padrão da plataforma: suba uma vez pela Mídia, receba o ID, vincule onde precisar. Esta página cobre só o lado do anúncio: upload, formatos, limites e ciclo de vida da imagem estão no guia de Mídia.

O fluxo em duas chamadas

  1. Upload: POST/api/media/upload com o arquivo em multipart/form-data. A resposta traz o id da imagem, já processada em todos os tamanhos.
  2. Vínculo: no create/simulate do anúncio, referencie esse id.
{
  "title": "Caixa de Som JBL Go!",
  "images": [                          // galeria do anúncio
    { "id": "01K8PBIMG00001VWXYZ12345678" },
    { "id": "01K8PBIMG00002VWXYZ12345678" }
  ],
  "variations": [
    {
      "seller_sku": "FK-JBL-2000-AZUL",
      "images": [                      // fotos específicas desta variação
        { "id": "01K8PBIMG00003VWXYZ12345678" }
      ]
    }
  ]
}
  • images[] (nível do anúncio): a galeria principal.
  • variations[].images[]: fotos da variação (a foto azul na variação azul). É aqui que o primary_attribute da geração de combinações ajuda: ele agrupa as fotos pelo atributo que muda a aparência.

Quem vira a capa

A capa (thumbnail) é escolhida nesta ordem, na própria criação:

  1. o thumbnail_id que você mandar no corpo — capa explícita, sempre vence;
  2. sem ele, a primeira imagem de images[];
  3. sem galeria e sem capa explícita, a primeira foto de variação — assim o anúncio nunca nasce sem imagem no card.

Depois de criado, dá para trocar a capa mandando outro thumbnail_id na edição do anúncio.

O que volta nas respostas

Imagens do anúncio retornam como { id, resources[] }, onde resources são as variações de tamanho geradas no upload:

{
  "images": [
    {
      "id": "01K8PBIMG00001VWXYZ12345678",
      "resources": [
        { "name": "sm", "size": "200x200",   "url": "https://cdn…/sm_…webp" },
        { "name": "lg", "size": "800x800",   "url": "https://cdn…/lg_…webp" }
      ]
    }
  ],
  "thumbnail": { "id": "01K8PBIMG00001VWXYZ12345678", "resource": { "name": "sm", "url": "…" } }
}

Nas variações, os resources vêm filtrados para os tamanhos sm e lg: suficientes pra listagem e zoom.

Regras práticas

  • Publicação exige imagem. O checklist tem o check image: pelo menos 1 imagem na galeria (ou thumbnail definida) pra sair de draft.
  • O ID precisa existir. O create valida a existência do ID da imagem na plataforma. ID errado derruba a chamada. Suba a imagem antes de criar o anúncio.
  • Imagem em uso fica protegida. Vinculada ao anúncio, a imagem passa a in_use: true na Mídia. Excluir retorna 409 até você remover o vínculo. Detalhes no ciclo de vida da Mídia.
  • Mesma imagem, vários lugares. O mesmo ID pode servir à galeria do produto e ao anúncio (é o ponto do upload compartilhado): não suba o arquivo duas vezes.
  • Imagem solta expira. Imagem sem vínculo é limpa pela rotina da plataforma (~72h). Não acumule uploads "pra usar depois".