Imagens

Visão geral

A API de imagens permite:

• consultar todas as imagens de um produto específico;
• percorrer o inventário global de imagens do catálogo;
• identificar imagens habilitadas e desabilitadas;
• identificar os papéis image, small_image e thumbnail;
• trabalhar de forma determinística com store_id;
• realizar carga inicial e reconciliação completa utilizando paginação por cursor;
• continuar utilizando os endpoints já existentes para criação, atualização e exclusão de imagens;
• remover todas as imagens de um produto em uma única chamada;
• remover imagens específicas de vários produtos em uma única chamada.

Mapa de métodos

Permissões OAuth2

Leitura e escrita de imagens usam permissões diferentes. Ao configurar o cliente OAuth2 no painel administrativo, conceda apenas o necessário para a integração.

Consultar imagens de um produto Novo

Operação somente leitura: retorna todas as imagens da galeria de um produto, incluindo as desabilitadas, com os papéis e o rótulo no contexto da store consultada.

GET /api2/products/imagem?type=sku&product_id=27.9353&store_id=1&limit=100
Authorization: Bearer {access_token}

Parâmetros

Exemplo de resposta

{
  "success": true,
  "product_id": 115973,
  "sku": "27.9353",
  "store_id": 1,
  "images": [
    {
      "image_id": "690992",
      "file": "/e/s/escova-robinson-taca-soft.jpg_1.jpg",
      "label": "Imagem 1",
      "position": 1,
      "types": [
        "image",
        "small_image",
        "thumbnail"
      ],
      "disabled": false,
      "url": "https://www.exemplo.com.br/media/catalog/product/e/s/escova-robinson-taca-soft.jpg_1.jpg"
    }
  ],
  "has_next": false,
  "next_cursor": null
}

Campos da imagem

Papéis da imagem (types)

types informa os papéis que a imagem exerce no produto. Os valores possíveis são image (imagem base), small_image (imagem pequena) e thumbnail (miniatura).

"types": [
  "image",
  "small_image",
  "thumbnail"
]

Uma imagem pode pertencer à galeria sem exercer nenhum desses papéis:

"types": []

Imagens desabilitadas

As consultas de leitura incluem imagens desabilitadas. Isso é intencional: a integração pode usar disabled para reconciliar corretamente imagens existentes que não devem ser apresentadas como ativas.

{
  "image_id": "653867",
  "file": "/p/o/ponta-diamantada_58.jpg",
  "label": "Imagem 1",
  "position": 1,
  "types": [],
  "disabled": true,
  "url": "https://www.exemplo.com.br/media/catalog/product/p/o/ponta-diamantada_58.jpg"
}

Store e fallback

store_id=0 representa o escopo administrativo/global. Para integrações com a loja frontend, informe explicitamente o ID da store utilizada pelo projeto — por exemplo store_id=1. Em ambientes multiloja podem existir store_id=1, store_id=2, store_id=3 e assim por diante.

• Os campos de galeria (label, position, disabled) usam o contexto da store consultada e podem herdar valores do escopo global quando não houver sobrescrita específica.
• Os papéis em types também respeitam a configuração do contexto solicitado.
• store_id=1 é apenas um exemplo comum — não é um valor universal da Plataforma Yep.

Produto existente sem imagens

Produto existente sem imagens retorna HTTP 200 com a lista vazia:

{
  "success": true,
  "product_id": 116022,
  "sku": "25.5979",
  "store_id": 0,
  "images": [],
  "has_next": false,
  "next_cursor": null
}

Inventário global de imagens Novo

Retorna o inventário de imagens do catálogo de forma paginada por cursor. Indicado para carga inicial e reconciliação completa.

GET /api2/products/imagens?store_id=1&limit=100
Authorization: Bearer {access_token}

Parâmetros

Exemplo de resposta

{
  "success": true,
  "store_id": 1,
  "images": [
    {
      "image_id": "160031",
      "product_id": 98622,
      "sku": "25.0886",
      "file": "/b/r/broca-carbide-fg-36.jpg_10.jpg",
      "label": "Imagem 1",
      "position": 1,
      "types": [],
      "disabled": false,
      "url": "https://www.exemplo.com.br/media/catalog/product/b/r/broca-carbide-fg-36.jpg_10.jpg"
    }
  ],
  "has_next": true,
  "next_cursor": "160115"
}

Semântica do inventário

O endpoint plural é um inventário de imagens, não de produtos. Consequentemente:

• um produto com várias imagens aparece várias vezes — cada registro representa uma imagem;
• produtos sem nenhuma imagem não aparecem no inventário;
• imagens desabilitadas aparecem com disabled=true;
• status e visibilidade do produto não são usados como filtro da galeria.

Paginação por cursor

Toda listagem que pode ultrapassar uma página devolve has_next e next_cursor. A integração avança repassando o cursor recebido, sem calcular nada.

Fluxo recomendado

1. iniciar sem cursor;
2. processar images;
3. se has_next=true, chamar novamente com cursor igual a next_cursor;
4. repetir;
5. encerrar quando has_next=false e next_cursor=null.

Evitar

• Incrementar o cursor manualmente.
• Reutilizar um cursor arbitrário como se fosse número de página.
• Enviar page ou offset.

Recomendações para integração

Respostas HTTP das consultas

Entradas que retornam 400

• limit=0, limit=201 ou limit=abc
• page=2 ou offset=10
• cursor inválido
• store_id inválido

Operações de escrita

Criação, atualização e exclusão individual de imagens continuam disponíveis na rota singular, diferenciadas pelo método HTTP. Exigem a permissão products/images. Os GETs não substituem estas operações. Para remover várias imagens de uma vez, veja exclusão total e exclusão seletiva em lote.

{
  "type": "sku",
  "product_id": "novo_produto",
  "position": 1,
  "label": "Imagem",
  "file_name": "minha_imagem.png",
  "file_mime_type": "image/png",
  "file_content": "iVBORw0KGgoAAAANS...",
  "types": ["image"]
}

{
  "type": "sku",
  "product_id": "produtoteste",
  "image_id": "70449",
  "position": 999,
  "label": "Imagem atualizada",
  "types": ["image"]
}

{
  "type": "sku",
  "product_id": "produtoteste",
  "image_id": "70449"
}

Excluir todas as imagens de um produto Novo

Remove toda a galeria global de um único produto em uma única requisição.

DELETE /api2/products/imagens
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "type": "sku",
  "product_id": "PRODUTO-001",
  "delete_all": true
}

{
  "type": "id",
  "product_id": 12345,
  "delete_all": true
}

Parâmetros

• store_id não é aceito: a limpeza é global para a galeria do produto.
• delete_all e items são modos mutuamente exclusivos na mesma requisição.

Exemplo de resposta

{
  "success": true,
  "product_id": 12345,
  "sku": "PRODUTO-001",
  "deleted_count": 3
}

Produto que já está sem imagens responde 200 com deleted_count: 0:

{
  "success": true,
  "product_id": 12345,
  "sku": "PRODUTO-001",
  "deleted_count": 0
}

Excluir imagens específicas em lote Novo

Remove imagens específicas de um ou vários produtos em uma única chamada. É possível misturar identificação por SKU e por ID no mesmo lote.

{
  "items": [
    {
      "type": "sku",
      "product_id": "PRODUTO-001",
      "image_ids": ["10001", "10002"]
    },
    {
      "type": "id",
      "product_id": 12346,
      "image_ids": ["10003"]
    }
  ]
}

Regras do payload

• items deve ser um array não vazio.
• Cada item exige type, product_id e image_ids.
• type aceita apenas sku ou id.
• image_ids deve ser um array não vazio.
• Cada image_id existente deve pertencer ao produto informado no mesmo item.

• O mesmo produto não pode aparecer duas vezes, mesmo que uma entrada use SKU e outra use ID.
• O mesmo image_id não pode ser repetido no lote.
• store_id não é aceito: a exclusão é global.
• items e delete_all não podem ser enviados juntos.

Exemplo de resposta

{
  "success": true,
  "products_processed": 2,
  "requested_count": 3,
  "deleted_count": 2,
  "already_absent_count": 1,
  "results": [
    {
      "product_id": 12345,
      "sku": "PRODUTO-001",
      "requested_count": 2,
      "deleted_count": 2,
      "already_absent_count": 0
    },
    {
      "product_id": 12346,
      "sku": "PRODUTO-002",
      "requested_count": 1,
      "deleted_count": 0,
      "already_absent_count": 1
    }
  ]
}

Campos da resposta

Garantias da exclusão em lote

Validação antes de excluir

O lote é validado antes da aplicação das exclusões. Erros de produto inexistente, ownership incorreto, duplicidade ou payload inválido não geram exclusão parcial dos demais itens: a requisição inteira é rejeitada e nenhuma imagem é removida.

Imagens duplicadas e papéis

Duas associações da galeria podem apontar para o mesmo arquivo. Se apenas um image_id for removido e outra associação do mesmo produto continuar usando o mesmo file, os papéis image, small_image e thumbnail permanecem válidos.

Os papéis são limpos apenas quando a última associação daquele arquivo deixa de existir no produto.

Recomendações operacionais

Para reconciliação de galerias:

1. consultar as imagens ou o inventário;
2. agrupar as exclusões por produto;
3. montar lotes de até 50 produtos e 500 image_ids;
4. enviar um lote;
5. aguardar a resposta;
6. só então enviar o próximo.

Respostas HTTP da escrita