VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Biblioteca de mídia

Arquivos

Lista, envia e exclui arquivos da biblioteca de mídia da loja.

Operações sobre arquivos já com dono. Exigem o privilégio manage_media.

Listar arquivos

GET/api/v1/admin/mediaAdmin

Lista os arquivos da biblioteca com paginação

Ordenados por position crescente e, no empate, do mais recente para o mais antigo. Filtre por dono para ver só os arquivos de um produto, por exemplo.

Parâmetros de consulta

owner_typestring
Tipo do dono (product, banner, vendor...). Igualdade exata.
owner_idstring
Id do dono.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso volta a 20.

Exemplo de requisição

200Arquivos retornados

Campos da resposta

media[].iduuid
Identificador do arquivo.
media[].tenant_iduuid
Loja dona.
media[].owner_idstring
Id do dono.
media[].owner_typestring
Tipo do dono.
media[].filenamestring
Nome do arquivo como foi enviado.
media[].content_typestring
Tipo detectado do conteúdo.
media[].sizeinteger
Tamanho em bytes.
media[].urlstring
URL pública. Relativa (/uploads/...) no armazenamento local.
media[].altstring
Texto alternativo. Ausente quando não definido.
media[].positioninteger
Ordem entre os arquivos do mesmo dono, a partir de 1.
media[].created_atstring
Envio (RFC 3339, UTC).
totalinteger
Total de arquivos que atendem ao filtro.
pageinteger
Página retornada.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Quantidade de páginas.

Enviar arquivo

POST/api/v1/admin/mediaAdmin

Envia um arquivo e o associa a um dono

Requisição multipart/form-data. Há um alias idêntico em /api/v1/admin/media/upload, com o mesmo comportamento. O arquivo recebe position igual ao maior da lista daquele dono mais 1.

Campos do formulário

filefileobrigatório
O arquivo, até 10 MB. Tipos aceitos pelo conteúdo: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF, MP4.
owner_typestringobrigatório
Tipo do dono (product, banner, vendor, user...).
owner_idstringobrigatório
Id do dono.
POST/api/v1/admin/media/uploadAdmin

Alias de POST /api/v1/admin/media

Mesmos campos, mesma resposta e mesmos erros de POST /api/v1/admin/media. Existe por compatibilidade com documentação e testes que usam este caminho.

Exemplo de requisição

201Arquivo criado

Excluir arquivo

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

Exclui um arquivo do armazenamento e do cadastro

Remove o arquivo do disco ou do bucket e apaga o registro. Se a remoção física falhar, o registro é apagado mesmo assim e o erro só é registrado no log do servidor. Quem usa a URL (um produto, um banner) passa a ter imagem quebrada.

Parâmetros de caminho

iduuidobrigatório
Id do arquivo.
200Arquivo excluído

Erros

StatusQuandoCorpo
400Requisição que não é multipart; owner_id, owner_type ou file ausente; tipo de arquivo não aceito{"error":"owner_id is required"} ou {"error":"unsupported file type","detail":"Allowed types: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF, MP4. Detected: text/html; charset=utf-8"}
401Sem token ou token expirado{"error":"missing authorization header"}
403Sem o privilégio manage_media{"error":"insufficient privileges","required":"manage_media"}
500Falha ao gravar no armazenamento; excluir id inexistente ou que não é UUID{"error":"failed to delete file","detail":"..."}
SVG executa código

O SVG é um documento que o navegador pode executar. Aceite SVG apenas de fontes confiáveis e prefira PNG ou WebP em imagens de produto.

Veja também

  • Envio temporário
  • Ferramentas de imagem
Anterior
Biblioteca de mídia
Próxima
Envio temporário
Nesta página
  • Listar arquivos
  • Exemplo de requisição
  • Enviar arquivo
  • Exemplo de requisição
  • Excluir arquivo
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/media?owner_type=product&owner_id=$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "owner_type=product" \
  -F "owner_id=$PRODUCT_ID" \
  -F "file=@camiseta-frente.jpg;type=image/jpeg"
json
{
  "media": [
    {
      "id": "b063ff9a-8b11-4d2b-941f-f90d368bae75",
      "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
      "owner_id": "b6e23840f864a29f05e71799c1803a91",
      "owner_type": "intelligence",
      "filename": "ai-banner-6d028a9002c868c7.png",
      "content_type": "image/png",
      "size": 788544,
      "url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/intelligence/b6e23840f864a29f05e71799c1803a91/0335c6eb-c638-44d9-ac95-afd5d112c715_ai-banner-6d028a9002c868c7.png",
      "position": 1,
      "created_at": "2026-10-09T07:13:51.262088Z"
    }
  ],
  "total": 895,
  "page": 1,
  "per_page": 20,
  "total_pages": 45
}
json
{
  "id": "5d1f0a2e-3c4b-4d6e-8f70-9a1b2c3d4e5f",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "owner_id": "0d9f2f5a-3b8d-4f6a-a1b4-5c4a1a6a7e10",
  "owner_type": "product",
  "filename": "camiseta-frente.jpg",
  "content_type": "image/jpeg",
  "size": 184320,
  "url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/0d9f2f5a-3b8d-4f6a-a1b4-5c4a1a6a7e10/9b7c...-camiseta-frente.jpg",
  "position": 1,
  "created_at": "2026-10-11T17:00:00.000Z"
}
json
{ "message": "file deleted" }