API atual/Referência completa/Catálogo: imagens e anexos

Imagens do produto

Altera o texto alternativo e a posição de uma imagem, define a principal e apaga imagens da galeria de um produto.

Estas quatro rotas ajustam uma imagem que já está na galeria de um produto. Para saber o id de cada imagem, liste a galeria do produto (GET /api/v1/admin/products/{id}/images). Todas exigem o privilégio manage_catalog.

Alterar uma imagem

PUT/api/v1/admin/images/{id}Admin

Alterar texto alternativo, posição ou principal

Atualização parcial: só os campos enviados mudam. Se is_primary for true, a plataforma antes desmarca a principal anterior do mesmo produto. Devolve a imagem já atualizada.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

Corpo da requisição

alt_textstring

Texto alternativo. Envie "" para limpar.

positioninteger

Nova posição na galeria, a partir de 0. A rota não reajusta as outras imagens: para reordenar várias de uma vez use a rota de reordenar do produto.

is_primaryboolean

true torna esta a imagem principal. false só desmarca esta, e o produto pode ficar sem principal.

bash

curl -X PUT "$BASE_URL/api/v1/admin/images/acd51513-0264-46c7-a667-504e3ec77e19" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alt_text":"Caderno vermelho, vista frontal","is_primary":true}'

200Imagem atualizada

json

{
  "id": "acd51513-0264-46c7-a667-504e3ec77e19",
  "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/produto.png",
  "alt_text": "Caderno vermelho, vista frontal",
  "position": 0,
  "is_primary": true
}

Campos da resposta

iduuid

Id da imagem.

image_urlstring

Caminho ou URL do arquivo.

alt_textstring

Texto alternativo.

positioninteger

Posição na galeria.

is_primaryboolean

Se é a imagem principal.

Definir a imagem principal

PUT/api/v1/admin/images/{id}/primaryAdmin

Tornar esta imagem a principal do produto

Marca a imagem como principal e desmarca todas as outras do mesmo produto. Sem corpo. Renova o carimbo de atualização do produto e reindexa a busca, para a vitrine trocar a capa logo.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

bash

curl -X PUT "$BASE_URL/api/v1/admin/images/acd51513-0264-46c7-a667-504e3ec77e19/primary" \
  -H "Authorization: Bearer $TOKEN"

200Principal definida

json

{ "message": "primary image set" }

Apagar uma imagem

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

Apagar uma imagem da galeria

Remove a imagem do produto. As imagens com posição maior sobem uma posição, e se a apagada era a principal, a primeira restante vira a principal. O arquivo original continua no armazenamento; só o vínculo com o produto desaparece.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

DELETE/api/v1/admin/product-images/{id}Admin

Apagar uma imagem (caminho da plataforma antiga)

Faz exatamente o mesmo que DELETE /images/{id}. Existe para clientes que usavam o caminho product-images da plataforma antiga. Em integrações novas use DELETE /images/{id}.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/images/acd51513-0264-46c7-a667-504e3ec77e19" \
  -H "Authorization: Bearer $TOKEN"

200Imagem apagada

json

{ "message": "image deleted" }

Erros

Status	Quando	Corpo de exemplo
400	`PUT /images/{id}` com corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Nenhuma imagem com esse id.	`{"error":"image not found"}`
500	`PUT /images/{id}` sem nenhum campo.	`{"error":"failed to update image","detail":"no fields to update"}`
500	O `{id}` não é um UUID.	`{"error":"failed to delete image","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo..."}`

Os textos em detail que o servidor devolve em português chegam exatamente assim.

Veja também

API atual/Referência completa/Catálogo: imagens e anexos

Imagens do produto

Altera o texto alternativo e a posição de uma imagem, define a principal e apaga imagens da galeria de um produto.

Alterar uma imagem

PUT/api/v1/admin/images/{id}Admin

Alterar texto alternativo, posição ou principal

Atualização parcial: só os campos enviados mudam. Se is_primary for true, a plataforma antes desmarca a principal anterior do mesmo produto. Devolve a imagem já atualizada.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

Corpo da requisição

alt_textstring

Texto alternativo. Envie "" para limpar.

positioninteger

Nova posição na galeria, a partir de 0. A rota não reajusta as outras imagens: para reordenar várias de uma vez use a rota de reordenar do produto.

is_primaryboolean

true torna esta a imagem principal. false só desmarca esta, e o produto pode ficar sem principal.

bash

curl -X PUT "$BASE_URL/api/v1/admin/images/acd51513-0264-46c7-a667-504e3ec77e19" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"alt_text":"Caderno vermelho, vista frontal","is_primary":true}'

200Imagem atualizada

json

{
  "id": "acd51513-0264-46c7-a667-504e3ec77e19",
  "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/produto.png",
  "alt_text": "Caderno vermelho, vista frontal",
  "position": 0,
  "is_primary": true
}

Campos da resposta

iduuid

Id da imagem.

image_urlstring

Caminho ou URL do arquivo.

alt_textstring

Texto alternativo.

positioninteger

Posição na galeria.

is_primaryboolean

Se é a imagem principal.

Definir a imagem principal

PUT/api/v1/admin/images/{id}/primaryAdmin

Tornar esta imagem a principal do produto

Marca a imagem como principal e desmarca todas as outras do mesmo produto. Sem corpo. Renova o carimbo de atualização do produto e reindexa a busca, para a vitrine trocar a capa logo.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

bash

curl -X PUT "$BASE_URL/api/v1/admin/images/acd51513-0264-46c7-a667-504e3ec77e19/primary" \
  -H "Authorization: Bearer $TOKEN"

200Principal definida

json

{ "message": "primary image set" }

Apagar uma imagem

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

Apagar uma imagem da galeria

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

DELETE/api/v1/admin/product-images/{id}Admin

Apagar uma imagem (caminho da plataforma antiga)

Faz exatamente o mesmo que DELETE /images/{id}. Existe para clientes que usavam o caminho product-images da plataforma antiga. Em integrações novas use DELETE /images/{id}.

Parâmetros de caminho

iduuidobrigatório

Id da imagem.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/images/acd51513-0264-46c7-a667-504e3ec77e19" \
  -H "Authorization: Bearer $TOKEN"

200Imagem apagada

json

{ "message": "image deleted" }

Erros

Status	Quando	Corpo de exemplo
400	`PUT /images/{id}` com corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_catalog`.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Nenhuma imagem com esse id.	`{"error":"image not found"}`
500	`PUT /images/{id}` sem nenhum campo.	`{"error":"failed to update image","detail":"no fields to update"}`
500	O `{id}` não é um UUID.	`{"error":"failed to delete image","detail":"o valor \"abc\" não é um uuid válido. Envie o identificador completo..."}`

Os textos em detail que o servidor devolve em português chegam exatamente assim.