Mídia do produto
Como funcionam as imagens, os vídeos e os anexos de um produto, os limites de cada um e o mapa de todas as rotas.
A mídia de um produto é tudo o que acompanha o cadastro dele e ajuda a vender: as imagens da galeria (e o giro 360), os vídeos (YouTube, Vimeo, arquivo ou trecho de transmissão ao vivo) e os anexos para download (manual, ficha técnica, certificado). Esta seção mostra como ler e alterar cada um por API.
Em todos os casos a API trabalha com endereços (URLs): ela não recebe o arquivo da imagem ou do anexo, ela guarda onde o arquivo está. Você hospeda o arquivo (CDN, armazenamento da loja) e registra o endereço aqui.
Como funciona
Um produto novo nasce sem mídia. Um fluxo típico de integração (por exemplo, um ERP ou PIM que publica fotos e ficha técnica):
- Hospedar os arquivos
Suba as fotos, os vídeos e os PDFs para um endereço público (seu CDN, por exemplo). A API só precisa do endereço.
- Cadastrar as imagens
Para cada foto, adicione a imagem. A primeira vira a principal sozinha. Guarde o
iddevolvido. - Ordenar e escolher a principal
Envie a lista de ids na ordem final em Ordem, giro 360 e remoção. A primeira da lista passa a ser a principal.
- Acrescentar vídeo e anexos
- Conferir
Chame as listagens de volta, ou consulte o produto, que traz a galeria dentro dele.
Conceitos-chave
Posição e imagem principal
Cada imagem, vídeo e anexo tem uma position (inteiro, a partir de 0) que define a ordem de exibição. A API não renumera os demais quando você informa uma posição ao adicionar ou editar: duas mídias podem ficar com o mesmo número. A forma segura de ordenar é a rota de reordenar, que recebe a lista inteira de ids e atribui 0, 1, 2... na sequência.
Só imagens têm o conceito de principal (is_primary): a que aparece nas listagens, no carrinho e nos compartilhamentos. Há no máximo uma por produto. A primeira imagem cadastrada é principal automaticamente; reordenar passa a marca para quem ficar em primeiro; apagar a principal promove a primeira que sobrar.
Imagem de que tipo e de onde
| Mídia | O que a API guarda | Formatos e limites |
|---|---|---|
| Imagem | A URL (http/https, caminho /uploads/... ou data:) e o texto alternativo. | JPEG, PNG, GIF, WebP, AVIF, SVG. data: até 5 MB. |
| Vídeo | O link (YouTube ou Vimeo), ou o arquivo enviado, mais a miniatura. | Até 3 por produto. Arquivo MP4 ou WebM, até 200 MB. |
| Anexo | A URL do arquivo, o nome, o tipo e o tamanho. | Sem limite de quantidade na API. |
Giro 360
Um giro 360 não é um tipo de mídia à parte: é um subconjunto ordenado das imagens do produto, marcado como quadros do visualizador. Você cadastra as fotos como imagens normais e depois escolhe quais formam o giro (Ordem, giro 360 e remoção).
Quem pode alterar
Na API de administração (/api/v1/admin), qualquer administrador com o privilégio certo altera a mídia de qualquer produto da loja. O vendedor (seller) tem rotas próprias no painel dele, com checagem de que o produto é seu; elas ficam fora desta seção. Sobre produto mestre e de seller, veja Produtos.
Identificadores
O {id} do produto nas rotas é sempre o UUID do produto, nunca o SKU ou o código. Imagens, vídeos e anexos também têm UUID próprio.
Endpoints
Auth: Admin é o administrador (Bearer).
| Método | Rota | O que faz | Auth | Página |
|---|---|---|---|---|
| GET | /api/v1/admin/products/{id}/images | Lista as imagens | Admin | Imagens do produto |
| POST | /api/v1/admin/products/{id}/images | Adiciona uma imagem | Admin | Imagens do produto |
| PUT | /api/v1/admin/products/{id}/images/reorder | Reordena (e define a principal) | Admin | Ordem, giro 360 e remoção |
| PUT | /api/v1/admin/products/{id}/images/spin-group | Define os quadros do giro 360 | Admin | Ordem, giro 360 e remoção |
| DELETE | /api/v1/admin/products/{id}/images/{imgId} | Remove uma imagem | Admin | Ordem, giro 360 e remoção |
| GET | /api/v1/admin/products/{id}/videos | Lista os vídeos | Admin | Vídeos do produto |
| POST | /api/v1/admin/products/{id}/videos | Adiciona um vídeo (JSON ou arquivo) | Admin | Vídeos do produto |
| PUT | /api/v1/admin/products/{id}/videos/{videoId} | Altera título ou posição | Admin | Vídeos do produto |
| POST | /api/v1/admin/products/{id}/videos/reorder | Reordena os vídeos | Admin | Vídeos do produto |
| DELETE | /api/v1/admin/products/{id}/videos/{videoId} | Remove um vídeo | Admin | Vídeos do produto |
| GET | /api/v1/admin/products/{id}/attachments | Lista os anexos | Admin | Anexos do produto |
| POST | /api/v1/admin/products/{id}/attachments | Cadastra um anexo | Admin | Anexos do produto |
| PUT | /api/v1/admin/products/{id}/attachments/reorder | Reordena os anexos | Admin | Anexos do produto |
Erros comuns
- Mandar o arquivo em vez da URL. Imagens e anexos recebem só o endereço. Só o vídeo
uploadaceita arquivo (multipart). - Usar o SKU no caminho. O
{id}é o UUID do produto. Um SKU devolve400 invalid product idao adicionar uma imagem e500em várias outras rotas desta seção. - Esperar
404para um produto que não existe nas listagens. Imagens, vídeos e anexos de um UUID inexistente voltam200com lista vazia. Confirme o produto antes. - Informar
positionpara "inserir" uma mídia. Ela não empurra as outras; use a rota de reordenar. - Reordenar com a lista incompleta. As mídias que ficarem de fora mantêm a posição antiga e podem empatar com as demais.
- Tentar o quarto vídeo. A resposta é
422 max 3 videos per product, e essa checagem vem antes de todas as outras. - Vimeo ou trecho de live sem miniatura. Só o YouTube gera a miniatura sozinho.