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

bash

curl "$BASE_URL/api/v1/admin/media?owner_type=product&owner_id=$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

200Arquivos retornados

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
}

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

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"

201Arquivo criado

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"
}

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

json

{ "message": "file deleted" }

Erros

Status	Quando	Corpo
400	Requisiçã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"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_media`	`{"error":"insufficient privileges","required":"manage_media"}`
500	Falha ao gravar no armazenamento; excluir id inexistente ou que não é UUID	`{"error":"failed to delete file","detail":"..."}`

Veja também

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

bash

curl "$BASE_URL/api/v1/admin/media?owner_type=product&owner_id=$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

200Arquivos retornados

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
}

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

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"

201Arquivo criado

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"
}

Excluir arquivo

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

Exclui um arquivo do armazenamento e do cadastro

Parâmetros de caminho

iduuidobrigatório

Id do arquivo.

200Arquivo excluído

json

{ "message": "file deleted" }

Erros

Status	Quando	Corpo
400	Requisiçã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"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_media`	`{"error":"insufficient privileges","required":"manage_media"}`
500	Falha ao gravar no armazenamento; excluir id inexistente ou que não é UUID	`{"error":"failed to delete file","detail":"..."}`