Biblioteca de mídia

A biblioteca de mídia guarda os arquivos da loja: fotos de produto, banners, logos de seller (lojista), PDFs e vídeos curtos. Cada arquivo pertence a um dono (um produto, um banner, um seller...) e recebe uma URL pública. Esta seção cobre o envio, a listagem e a exclusão de arquivos, o envio temporário usado em formulários que ainda não foram salvos e duas ferramentas de edição de imagem. Todas as rotas exigem token de administrador com o privilégio manage_media.

Como funciona

Há dois caminhos de envio:

1. Envio direto
   POST /api/v1/admin/media com o arquivo e o dono. Serve quando o dono já existe (um produto já salvo, por exemplo). Devolve o arquivo criado.
2. Envio temporário
   POST /api/v1/admin/media/temp guarda o arquivo sem dono e devolve um id temporário. Serve para formulários de criação, em que o produto ainda não existe. Quando o formulário é salvo, POST /api/v1/admin/media/commit anexa os arquivos ao dono. Temporários não confirmados são limpos depois de 24 horas.

Conceitos-chave

Dono do arquivo

owner_type diz a que o arquivo pertence e owner_id identifica o registro. Valores usados pela plataforma incluem product, banner, vendor e user; o assistente de IA grava como intelligence. A listagem filtra por esses dois campos.

Armazenamento

A loja pode guardar os arquivos no disco do servidor ou em um bucket S3 com CDN, conforme a configuração da plataforma. O nome gravado é sanitizado e recebe um UUID de prefixo; a extensão vem do tipo detectado, não do nome enviado.

Vitrine e área do cliente

O mesmo envio é usado por outras áreas (painel do seller, área do cliente), com regras próprias por dono. Esta seção descreve o uso pelo administrador.

Endpoints

Erros comuns

• Enviar JSON em vez de multipart/form-data. O envio exige multipart; JSON retorna 400 failed to parse multipart form.
• Esquecer owner_id ou owner_type no envio direto. Retorna 400. Use o envio temporário quando não há dono.
• Mandar um arquivo com extensão certa e conteúdo errado. O tipo vem do conteúdo; um .jpg que na verdade é HTML é recusado com 400.
• Acima do limite de tamanho. 10 MB no direto e 50 MB no temporário; acima disso a leitura falha com 400.
• Esperar 404 ao excluir id inexistente. Retorna 500.
• Usar a URL relativa fora da vitrine. Prefixe com o endereço da loja.

Próximos passos