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. A primeira imagem tende a virar a thumbnail.
  • 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.

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