API atual/Referência completa/SEO, testes A/B e envio de arquivos

Envio de arquivos pelo cliente

Envia um arquivo (imagem, PDF ou vídeo MP4) em nome do cliente logado, para os documentos do perfil dele ou para uma conversa dele, com limites de tipo, tamanho e quantidade.

O cliente logado pode anexar arquivos: um documento exigido no cadastro (por exemplo, a foto de um comprovante) ou uma imagem numa conversa com a loja ou com um seller. Esta rota recebe o arquivo, valida o conteúdo e devolve o endereço dele.

O cliente só pode enviar para dois destinos, ambos dele: os próprios documentos de perfil (owner_type = user_profile_field, com owner_id igual ao id do cliente) e as próprias conversas (owner_type = message, com owner_id igual ao id de uma conversa da qual ele participa). Qualquer outro destino (produto, banner, seller, outro cliente) responde 403 owner_not_allowed. Uma conta ainda pendente de aprovação só pode enviar documentos de perfil dela, não mensagens.

Enviar um arquivo

POST/api/v1/storefront/mediaCliente

Envia um arquivo como o cliente logado

Corpo multipart/form-data. O tipo é identificado pelo conteúdo do arquivo (não pelo cabeçalho que o seu cliente HTTP manda), por isso renomear um .txt para .png não passa.

Cabeçalhos

Authorizationstringobrigatório

Bearer <token> do cliente. Sem ele: 401 missing authorization header.

Content-Typestringobrigatório

multipart/form-data com o boundary (o seu cliente HTTP preenche sozinho).

Corpo da requisição

filefileobrigatório

O arquivo. Até 10 MB. Tipos aceitos para o cliente: JPEG, PNG, GIF, WebP, AVIF, PDF e MP4. SVG é recusado para clientes.

owner_typestringobrigatório

user_profile_fieldmessage

Destino do arquivo.

owner_idstringobrigatório

Para user_profile_field, o id do próprio cliente. Para message, o id da conversa dele.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/media" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@comprovante.png" \
  -F "owner_type=user_profile_field" \
  -F "owner_id=$USER_ID"

Resposta

201Arquivo criado

json

{
  "id": "665b797d-64eb-413c-8e0a-d4bf2a55d5dc",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "owner_id": "61ba2e56-db7e-4514-a63c-3023c105c1e8",
  "owner_type": "user_profile_field",
  "filename": "pix.png",
  "content_type": "image/png",
  "size": 70,
  "url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/user_profile_field/61ba2e56-db7e-4514-a63c-3023c105c1e8/b8d0f9ec-823f-47b5-9a64-e0b5e9466192_pix.png",
  "position": 1,
  "created_at": "2026-10-12T00:11:31.146856Z"
}

Campos da resposta

iduuid

Id do arquivo.

tenant_iduuid

Loja dona do arquivo.

owner_idstring

Destino informado.

owner_typestring

Tipo do destino.

filenamestring

Nome original do arquivo.

content_typestring

Tipo detectado pelo conteúdo (image/png, application/pdf, video/mp4...).

sizeinteger

Tamanho em bytes.

urlstring

Caminho do arquivo, relativo ao domínio da loja ($BASE_URL + url).

altstring

Texto alternativo, quando existir. Ausente aqui.

positioninteger

Posição do arquivo entre os do mesmo destino.

created_atstring

Envio, RFC 3339.

Limites

Limite	Cliente	Conta pendente de aprovação
Tamanho de cada arquivo	10 MB	10 MB
Documentos de perfil guardados	50 arquivos, 200 MB	20 arquivos, 100 MB
Envios por hora	60	20
Envios por dia	300	60
Bytes por dia	500 MB	150 MB

Os limites são os padrões da plataforma e podem ser ajustados pelo operador do ambiente.

Erros

Status	Quando	Corpo
400	Corpo que não é multipart	`{"error":"failed to parse multipart form","detail":"..."}`
400	Sem `owner_id` ou `owner_type`	`{"error":"owner_id is required"}` (ou `owner_type is required`)
400	Sem o campo `file`	`{"error":"file is required","detail":"http: no such file"}`
400	Tipo não aceito	`{"error":"unsupported file type","detail":"Allowed types: JPEG, PNG, GIF, WebP, AVIF, SVG, PDF, MP4. Detected: text/plain; charset=utf-8"}`
400	SVG enviado por cliente	`{"error":"unsupported file type","detail":"Allowed types: JPEG, PNG, GIF, WebP, AVIF, PDF, MP4. Detected: image/svg+xml"}`
401	Sem token	`{"error":"missing authorization header"}`
403	Destino que não é do cliente	`{"error":"owner_not_allowed","code":"owner_not_allowed"}`
403	Conta pendente tentando enviar para outro destino	`{"error":"account_pending_approval","code":"account_pending_approval"}`
413	Cota de documentos do cliente cheia	`{"error":"upload_quota_exceeded","code":"upload_quota_exceeded","message":"this account reached its file limit"}`
429	Limite por hora, dia ou bytes estourado	`{"error":"upload_rate_limited","code":"upload_rate_limited","message":"too many uploads; try again later"}` com `Retry-After: 600`
500	Falha ao gravar	`{"error":"failed to upload file","detail":"..."}`

Veja também