Imagens e anexos de produto
Como a plataforma guarda as fotos e os arquivos de um produto, e as rotas para ajustar, trocar a principal, apagar e melhorar imagens com IA.
Cada produto tem uma galeria de imagens (a primeira, ou a marcada como principal, aparece na listagem e na vitrine) e, opcionalmente, anexos: arquivos para baixar, como manual em PDF, ficha técnica ou tabela de medidas. Esta seção cobre as operações que agem sobre uma imagem ou um anexo pelo id deles. Para adicionar ou reordenar imagens e anexos de um produto (rotas com products/{id} no caminho), veja a seção de produtos.
Como funciona
Galeria de imagens
A galeria é ordenada por position. Ao apagar uma imagem, as seguintes sobem uma posição, então as posições continuam contíguas. Definir a imagem principal renova o carimbo de atualização do produto e o índice de busca, para a vitrine mostrar a foto nova em seguida.
Edição com IA
O editor de imagem do painel envia a imagem atual e recebe de volta os bytes da imagem melhorada. O fluxo é: você envia o arquivo, a rota devolve o PNG processado, você confere e então grava no produto pelas rotas de upload e de galeria.
Conceitos-chave
Id de imagem e id de produto
Os caminhos desta seção usam o id da imagem. Um id de produto no lugar dá 404. Um valor que não é UUID dá 500 com uma mensagem em português (veja os erros).
Campos de uma imagem
| Campo | Tipo | Descrição |
|---|---|---|
id | UUID | Id da imagem. |
image_url | string | Caminho ou URL do arquivo. |
alt_text | string | Texto alternativo, para acessibilidade e SEO. |
position | inteiro | Ordem na galeria, a partir de 0. |
is_primary | booleano | Se é a imagem de capa. |
Endpoints
| Método e caminho | Para que serve | Autenticação | Página |
|---|---|---|---|
PUT /api/v1/admin/images/{id} | Altera texto, posição ou principal | administrador | Imagens |
PUT /api/v1/admin/images/{id}/primary | Define a imagem principal | administrador | Imagens |
DELETE /api/v1/admin/images/{id} | Apaga a imagem | administrador | Imagens |
DELETE /api/v1/admin/product-images/{id} | Mesma exclusão, caminho da plataforma antiga | administrador | Imagens |
POST /api/v1/admin/images/ai/removebg | Remove o fundo | administrador | Imagens com IA |
POST /api/v1/admin/images/ai/professionalize | Refaz como foto de estúdio | administrador | Imagens com IA |
PUT /api/v1/admin/attachments/{attachmentId} | Altera um anexo | administrador | Anexos |
DELETE /api/v1/admin/attachments/{attachmentId} | Apaga um anexo | administrador | Anexos |
Erros comuns
- Enviar o id do produto no lugar do id da imagem. Dá
404 image not found. - Mandar
PUT /images/{id}com corpo vazio{}. Responde500comno fields to update: envie ao menos um campo. - Esperar que as rotas de IA gravem a imagem. Elas só devolvem o arquivo processado.
- Enviar JSON nas rotas de IA. Elas esperam
multipart/form-datacom o campoimage. - Atualizar um anexo mandando só um campo.
descriptionepositionsão sempre regravados (veja a página de anexos). - Passar um valor que não é UUID. Dá
500, não400.