API atual/Referência completa/Biblioteca de mídia

Envio temporário

Guarda um arquivo sem dono enquanto o formulário é preenchido e o anexa ao registro quando ele é salvo.

Em telas de criação (um produto novo, por exemplo) o registro ainda não existe, então não há owner_id. O envio temporário resolve isso em dois passos: você envia cada arquivo assim que o usuário o escolhe, guarda o id devolvido e, quando o formulário é salvo, confirma os ids para o dono recém-criado. Exigem o privilégio manage_media.

Enviar arquivo temporário

POST/api/v1/admin/media/tempAdmin

Guarda um arquivo sem dono em área temporária

Requisição multipart/form-data. Aceita os mesmos tipos do envio direto (JPEG, PNG, GIF, WebP, AVIF, SVG, PDF, MP4, detectados pelo conteúdo), mas com limite de 50 MB. Temporários com mais de 24 horas são apagados automaticamente nos envios seguintes.

Campos do formulário

filefileobrigatório

O arquivo, até 50 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/media/temp" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@camiseta-frente.jpg;type=image/jpeg"

201Arquivo guardado

json

{
  "id": "e3c9d7a1-6b2f-4d58-9a40-1f2e3d4c5b6a",
  "filename": "camiseta-frente.jpg",
  "content_type": "image/jpeg",
  "size": 184320,
  "preview_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/_temp/e3c9d7a1-camiseta-frente.jpg",
  "created_at": "2026-10-11T17:05:00.000Z"
}

Campos da resposta

iduuid

Id temporário. Use em temp_ids ao confirmar.

filenamestring

Nome do arquivo.

content_typestring

Tipo detectado.

sizeinteger

Tamanho em bytes.

preview_urlstring

URL para pré-visualizar o arquivo enquanto ele não é confirmado.

created_atstring

Envio (RFC 3339, UTC).

Confirmar temporários

POST/api/v1/admin/media/commitAdmin

Move temporários para o armazenamento definitivo e liga ao dono

Passa os arquivos para o armazenamento permanente e os associa ao dono. É idempotente: ids que já foram confirmados, expiraram ou não existem são ignorados em silêncio; a resposta traz só os arquivos que de fato foram confirmados, então compare com o que você enviou. Uma lista vazia em temp_ids responde 200 com media vazio, sem exigir dono.

Corpo da requisição

temp_idsarrayobrigatório

Ids temporários (strings UUID).

owner_idstringobrigatório

Id do dono (obrigatório quando há ids).

owner_typestringobrigatório

Tipo do dono (obrigatório quando há ids).

200Arquivos confirmados

json

{
  "media": [
    {
      "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:06:00.000Z"
    }
  ]
}

Os campos de cada arquivo são os de Listar arquivos.

Descartar temporário

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

Descarta um arquivo temporário antes de salvar o formulário

Use quando o usuário remove o arquivo do formulário antes de salvar. É idempotente: devolve 204 mesmo que o id não exista mais.

Parâmetros de caminho

iduuidobrigatório

Id temporário.

A resposta é 204 No Content.

Erros

Status	Quando	Corpo
400	Requisição que não é multipart ou sem `file` (enviar); corpo JSON inválido, `owner_id` ou `owner_type` ausente (confirmar); tipo de arquivo não aceito	`{"error":"owner_id is required"}` ou `{"error":"unsupported file type","detail":"..."}`
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 ou confirmar	`{"error":"failed to commit temp uploads","detail":"..."}`

Veja também

Envio temporário

Guarda um arquivo sem dono enquanto o formulário é preenchido e o anexa ao registro quando ele é salvo.

Enviar arquivo temporário

POST/api/v1/admin/media/tempAdmin

Guarda um arquivo sem dono em área temporária

Campos do formulário

filefileobrigatório

O arquivo, até 50 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/media/temp" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@camiseta-frente.jpg;type=image/jpeg"

201Arquivo guardado

json

{
  "id": "e3c9d7a1-6b2f-4d58-9a40-1f2e3d4c5b6a",
  "filename": "camiseta-frente.jpg",
  "content_type": "image/jpeg",
  "size": 184320,
  "preview_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/_temp/e3c9d7a1-camiseta-frente.jpg",
  "created_at": "2026-10-11T17:05:00.000Z"
}

Campos da resposta

iduuid

Id temporário. Use em temp_ids ao confirmar.

filenamestring

Nome do arquivo.

content_typestring

Tipo detectado.

sizeinteger

Tamanho em bytes.

preview_urlstring

URL para pré-visualizar o arquivo enquanto ele não é confirmado.

created_atstring

Envio (RFC 3339, UTC).

Confirmar temporários

POST/api/v1/admin/media/commitAdmin

Move temporários para o armazenamento definitivo e liga ao dono

Corpo da requisição

temp_idsarrayobrigatório

Ids temporários (strings UUID).

owner_idstringobrigatório

Id do dono (obrigatório quando há ids).

owner_typestringobrigatório

Tipo do dono (obrigatório quando há ids).

200Arquivos confirmados

json

{
  "media": [
    {
      "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:06:00.000Z"
    }
  ]
}

Os campos de cada arquivo são os de Listar arquivos.

Descartar temporário

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

Descarta um arquivo temporário antes de salvar o formulário

Use quando o usuário remove o arquivo do formulário antes de salvar. É idempotente: devolve 204 mesmo que o id não exista mais.

Parâmetros de caminho

iduuidobrigatório

Id temporário.

A resposta é 204 No Content.

Erros

Status	Quando	Corpo
400	Requisição que não é multipart ou sem `file` (enviar); corpo JSON inválido, `owner_id` ou `owner_type` ausente (confirmar); tipo de arquivo não aceito	`{"error":"owner_id is required"}` ou `{"error":"unsupported file type","detail":"..."}`
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 ou confirmar	`{"error":"failed to commit temp uploads","detail":"..."}`