Imagens do produto

Lista, adiciona, reordena, define o giro 360 e remove as imagens de um produto.

As imagens de um produto formam a galeria da página dele na loja. Cada imagem tem uma posição (a ordem de exibição) e pode ser a imagem principal, a que aparece nas listagens e no carrinho. Esta página cobre a leitura da galeria e o cadastro de imagens. Reordenar, montar o giro 360 e remover estão em Ordem, giro 360 e remoção.

Toda imagem é referenciada por URL: a API não recebe o arquivo, ela guarda o endereço. Hospede a imagem onde preferir (um CDN, o armazenamento da loja) e envie o endereço público. Ao alterar a galeria, a plataforma atualiza a vitrine e o índice de busca sozinha; você não precisa chamar mais nada.

Listar as imagens

GET/api/v1/admin/products/{id}/imagesAdmin

Lista as imagens de um produto

Exige o privilégio view_catalog ou manage_catalog. Devolve a galeria já na ordem de exibição.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Imagens do produto

json

{
  "images": [
    {
      "id": "5d1c2a64-0b0e-4c7a-8f41-6a0f7c9e1b21",
      "image_url": "https://cdn.minhaloja.com.br/p/mochila-frente.jpg",
      "alt_text": "Frente",
      "position": 0,
      "is_primary": true,
      "image_path": "https://cdn.minhaloja.com.br/p/mochila-frente.jpg",
      "alt": "Frente"
    },
    {
      "id": "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55",
      "image_url": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
      "alt_text": "",
      "position": 1,
      "is_primary": false,
      "image_path": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg"
    }
  ],
  "total": 2
}

Response fields

imagesarray

Imagens em ordem de position. Duas imagens com a mesma posição não têm ordem garantida entre si.

iduuid

Id da imagem.

image_urlstring

URL da imagem.

alt_textstring

Texto alternativo. Vazio quando não informado.

positioninteger

Posição de exibição, a partir de 0.

is_primaryboolean

true na imagem principal. Há no máximo uma.

image_pathstring

Cópia de image_url, com o nome usado pelas telas antigas.

altstring

Cópia de alt_text. Só aparece quando o texto não é vazio.

totalinteger

Quantidade de imagens.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	O usuário não tem `view_catalog` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
500	O id não é um UUID válido.	`{"error":"failed to get product images","detail":"o valor \"abc\" não é um uuid válido..."}`

Um UUID de produto que não existe devolve 200 com lista vazia.

Adicionar uma imagem

POST/api/v1/admin/products/{id}/imagesAdmin

Adiciona uma imagem a um produto

Exige o privilégio manage_catalog. Cria a imagem e devolve o registro criado.

Path parameters

iduuidobrigatório

Id do produto. Um SKU não serve: a API recusa com 400.

Corpo da requisição

urlstringobrigatório

Endereço da imagem. Aceita uma URL http ou https; um caminho do próprio armazenamento da loja que comece com /uploads/; ou uma URL data: com a imagem embutida (até 5 MB depois de decodificada). Os formatos aceitos são JPEG, PNG, GIF, WebP, AVIF e SVG. Outros esquemas (ftp:, javascript:, file:) são recusados. A API não baixa a imagem para conferir: ela valida só o endereço.

alt_textstringpadrão:

Texto alternativo, para acessibilidade e SEO.

positioninteger

Posição de exibição, a partir de 0. Se omitido, a imagem vai para o fim da galeria. Informar uma posição não empurra as outras: se já existir uma imagem nessa posição, as duas ficam com o mesmo número. Para uma ordem exata, use a rota de reordenar.

is_primarybooleanpadrão: false

true torna esta a imagem principal e tira a marca das outras. A primeira imagem do produto é sempre principal, mesmo que você envie false.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
  "alt_text": "Lado"
}'

Resposta

201Imagem criada

json

{
  "id": "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55",
  "image_url": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
  "alt_text": "Lado",
  "position": 1,
  "is_primary": false,
  "image_path": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
  "alt": "Lado"
}

Os campos são os mesmos da listagem. Guarde o id: é ele que você usa para reordenar, montar o giro 360 e remover (próxima página).

Erros

Status	Quando	Corpo
400	O corpo não é um JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	`url` ausente ou vazia.	`{"error":"url is required"}`
400	Endereço ou imagem inválidos.	`{"error":"invalid image url","detail":"invalid_image_url: unsupported scheme \"ftp\""}`
400	O `{id}` não é um UUID (por exemplo, um SKU).	`{"error":"invalid product id","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Nenhum produto ativo com esse id.	`{"error":"product not found","detail":"..."}`

As mensagens de detail de 400 (id) e 404 (produto) vêm em português, como o servidor as devolve.

Veja também

Ordem, giro 360 e remoção de imagens
Mídia do produto: visão geral, limites e o mapa das rotas.
Vídeos do produto
Consultar produto: a galeria também vem dentro do produto.

API atual/Guia rápido/Mídia do produto

Imagens do produto

Lista, adiciona, reordena, define o giro 360 e remove as imagens de um produto.

Listar as imagens

GET/api/v1/admin/products/{id}/imagesAdmin

Lista as imagens de um produto

Exige o privilégio view_catalog ou manage_catalog. Devolve a galeria já na ordem de exibição.

Path parameters

iduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Imagens do produto

json

{
  "images": [
    {
      "id": "5d1c2a64-0b0e-4c7a-8f41-6a0f7c9e1b21",
      "image_url": "https://cdn.minhaloja.com.br/p/mochila-frente.jpg",
      "alt_text": "Frente",
      "position": 0,
      "is_primary": true,
      "image_path": "https://cdn.minhaloja.com.br/p/mochila-frente.jpg",
      "alt": "Frente"
    },
    {
      "id": "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55",
      "image_url": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
      "alt_text": "",
      "position": 1,
      "is_primary": false,
      "image_path": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg"
    }
  ],
  "total": 2
}

Response fields

imagesarray

Imagens em ordem de position. Duas imagens com a mesma posição não têm ordem garantida entre si.

iduuid

Id da imagem.

image_urlstring

URL da imagem.

alt_textstring

Texto alternativo. Vazio quando não informado.

positioninteger

Posição de exibição, a partir de 0.

is_primaryboolean

true na imagem principal. Há no máximo uma.

image_pathstring

Cópia de image_url, com o nome usado pelas telas antigas.

altstring

Cópia de alt_text. Só aparece quando o texto não é vazio.

totalinteger

Quantidade de imagens.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	O usuário não tem `view_catalog` nem `manage_catalog`.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
500	O id não é um UUID válido.	`{"error":"failed to get product images","detail":"o valor \"abc\" não é um uuid válido..."}`

Um UUID de produto que não existe devolve 200 com lista vazia.

Adicionar uma imagem

POST/api/v1/admin/products/{id}/imagesAdmin

Adiciona uma imagem a um produto

Exige o privilégio manage_catalog. Cria a imagem e devolve o registro criado.

Path parameters

iduuidobrigatório

Id do produto. Um SKU não serve: a API recusa com 400.

Corpo da requisição

urlstringobrigatório

alt_textstringpadrão:

Texto alternativo, para acessibilidade e SEO.

positioninteger

is_primarybooleanpadrão: false

true torna esta a imagem principal e tira a marca das outras. A primeira imagem do produto é sempre principal, mesmo que você envie false.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
  "alt_text": "Lado"
}'

Resposta

201Imagem criada

json

{
  "id": "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55",
  "image_url": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
  "alt_text": "Lado",
  "position": 1,
  "is_primary": false,
  "image_path": "https://cdn.minhaloja.com.br/p/mochila-lado.jpg",
  "alt": "Lado"
}

Os campos são os mesmos da listagem. Guarde o id: é ele que você usa para reordenar, montar o giro 360 e remover (próxima página).

Erros

Status	Quando	Corpo
400	O corpo não é um JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	`url` ausente ou vazia.	`{"error":"url is required"}`
400	Endereço ou imagem inválidos.	`{"error":"invalid image url","detail":"invalid_image_url: unsupported scheme \"ftp\""}`
400	O `{id}` não é um UUID (por exemplo, um SKU).	`{"error":"invalid product id","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Nenhum produto ativo com esse id.	`{"error":"product not found","detail":"..."}`

As mensagens de detail de 400 (id) e 404 (produto) vêm em português, como o servidor as devolve.

Veja também

Ordem, giro 360 e remoção de imagens
Mídia do produto: visão geral, limites e o mapa das rotas.
Vídeos do produto
Consultar produto: a galeria também vem dentro do produto.