Ordem, giro 360 e remoção de imagens

Reordena as imagens de um produto, define a imagem principal, monta o giro 360 e remove imagens.

Esta página continua Imagens do produto: depois de cadastrar as imagens, você define a ordem delas (a primeira é a principal), escolhe quais formam o giro 360 e remove as que não servem mais. Tudo isso exige o privilégio manage_catalog.

Reordenar as imagens

PUT/api/v1/admin/products/{id}/images/reorderAdmin

Define a ordem de exibição das imagens

Exige manage_catalog. Você envia a lista de ids na ordem desejada; a primeira vira a posição 0 e passa a ser a imagem principal. É também o jeito de "definir como principal": ponha a imagem no começo da lista.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

image_idsarrayobrigatório

Ids das imagens do produto, na ordem final. Mande todas: as que ficarem de fora mantêm a posição antiga e podem empatar com as demais. Ao menos um id. Um id que já foi apagado é ignorado; um id de outro produto cancela a operação inteira.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_ids": [
    "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55",
    "5d1c2a64-0b0e-4c7a-8f41-6a0f7c9e1b21"
  ]
}'

Resposta

200Galeria reordenada

json

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

A resposta traz a galeria inteira já reordenada, com os mesmos campos da listagem.

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`image_ids` ausente ou vazio.	`{"error":"image_ids is required"}`
500	Um id não é UUID, ou pertence a outro produto.	`{"error":"failed to reorder images","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Montar o giro 360

PUT/api/v1/admin/products/{id}/images/spin-groupAdmin

Define as imagens que formam a visão 360

Exige manage_catalog. Um giro 360 é uma sequência de fotos do mesmo objeto, tiradas ao redor dele, que a vitrine exibe como um visualizador que o cliente arrasta. Aqui você escolhe quais imagens já cadastradas do produto são os quadros do giro, na ordem. A ação substitui o grupo anterior: quem não está na lista sai do giro. Uma lista vazia desfaz o giro. As imagens continuam na galeria normal.

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

image_idsarrayobrigatório

Ids das imagens, na ordem dos quadros (o primeiro é o quadro 1). Lista vazia ([]) remove o giro. Ids que não pertencem ao produto são ignorados sem erro.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images/spin-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_ids": [
    "5d1c2a64-0b0e-4c7a-8f41-6a0f7c9e1b21",
    "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55"
  ]
}'

Resposta

200Giro definido

json

{ "ok": true }

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
500	Um id não tem formato de UUID.	`{"error":"failed to set spin group","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Remover uma imagem

DELETE/api/v1/admin/products/{id}/images/{imgId}Admin

Remove uma imagem de um produto

Exige manage_catalog. Remove a imagem da galeria (o arquivo hospedado por você não é apagado). A plataforma fecha o buraco nas posições e, se a imagem removida era a principal, promove a primeira que sobrar.

Path parameters

iduuidobrigatório

Id do produto. A API confere que a imagem é mesmo dele.

imgIduuidobrigatório

Id da imagem.

Exemplo de requisição

bash

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

Resposta

204Imagem removida

text

(sem corpo)

Erros

Status	Quando	Corpo
404	A imagem não existe.	`{"error":"image not found"}`
404	A imagem existe, mas é de outro produto.	`{"error":"image not found for product"}`
500	O `imgId` não é um UUID.	`{"error":"failed to verify image ownership","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Repetir o DELETE na mesma imagem devolve 404, não 204.

Veja também

Imagens do produto: listar e adicionar imagens.
Mídia do produto: visão geral, limites e o mapa das rotas.
Vídeos do produto

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

Ordem, giro 360 e remoção de imagens

Reordena as imagens de um produto, define a imagem principal, monta o giro 360 e remove imagens.

Reordenar as imagens

PUT/api/v1/admin/products/{id}/images/reorderAdmin

Define a ordem de exibição das imagens

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

image_idsarrayobrigatório

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_ids": [
    "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55",
    "5d1c2a64-0b0e-4c7a-8f41-6a0f7c9e1b21"
  ]
}'

Resposta

200Galeria reordenada

json

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

A resposta traz a galeria inteira já reordenada, com os mesmos campos da listagem.

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`image_ids` ausente ou vazio.	`{"error":"image_ids is required"}`
500	Um id não é UUID, ou pertence a outro produto.	`{"error":"failed to reorder images","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Montar o giro 360

PUT/api/v1/admin/products/{id}/images/spin-groupAdmin

Define as imagens que formam a visão 360

Path parameters

iduuidobrigatório

Id do produto.

Corpo da requisição

image_idsarrayobrigatório

Ids das imagens, na ordem dos quadros (o primeiro é o quadro 1). Lista vazia ([]) remove o giro. Ids que não pertencem ao produto são ignorados sem erro.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/$PRODUCT_ID/images/spin-group" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_ids": [
    "5d1c2a64-0b0e-4c7a-8f41-6a0f7c9e1b21",
    "e8b4f3a0-91f2-47cb-a1c6-3f1d2b6a7c55"
  ]
}'

Resposta

200Giro definido

json

{ "ok": true }

Erros

Status	Quando	Corpo
400	Corpo inválido.	`{"error":"invalid request body","detail":"unexpected EOF"}`
500	Um id não tem formato de UUID.	`{"error":"failed to set spin group","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Remover uma imagem

DELETE/api/v1/admin/products/{id}/images/{imgId}Admin

Remove uma imagem de um produto

Path parameters

iduuidobrigatório

Id do produto. A API confere que a imagem é mesmo dele.

imgIduuidobrigatório

Id da imagem.

Exemplo de requisição

bash

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

Resposta

204Imagem removida

text

(sem corpo)

Erros

Status	Quando	Corpo
404	A imagem não existe.	`{"error":"image not found"}`
404	A imagem existe, mas é de outro produto.	`{"error":"image not found for product"}`
500	O `imgId` não é um UUID.	`{"error":"failed to verify image ownership","detail":"..."}`
401 / 403	Sem token / sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`

Repetir o DELETE na mesma imagem devolve 404, não 204.

Veja também

Imagens do produto: listar e adicionar imagens.
Mídia do produto: visão geral, limites e o mapa das rotas.
Vídeos do produto