Skip to main content
curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "purpose=product_image" \
  -F "file=@/caminho/local/foto.webp"

{
  "id": "file_123",
  "object": "file",
  "created_at": "2026-05-24T10:14:50Z",
  "filename": "foto.webp",
  "livemode": true,
  "metadata": {},
  "mime_type": "image/webp",
  "purpose": "product_image",
  "size": 184320,
  "updated_at": null,
  "url": "https://storage.chargefy.io/file_123"
}
Envia um arquivo binário para a Chargefy. A purpose define onde o arquivo fica (público ou privado), o limite de tamanho e os tipos MIME aceitos. O file retornado carrega uma url que aponta para o binário hospedado. Use o objeto file.url em campos que aceitam URL de mídia, como product.image_url. Esses campos aceitam apenas URLs de file da própria Chargefy; não envie URLs externas. O upload em si não vincula o arquivo a recurso nenhum — a vinculação é responsabilidade do recurso destino.

​
Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o header Organization: <organization_id> apontando para uma organização conectada ativa.

​
Tipo de conteúdo

multipart/form-data.

​
Attributes

​
file
binary
required
O binário do arquivo. Tamanho máximo varia por purpose.
​
filename
string
Nome amigável a aparecer em metadados. Quando omitido, usa o nome do arquivo enviado.
​
metadata[key]
string
Objeto livre string → string para correlacionar com o seu sistema. Use campos repetidos no formulário: metadata[reference_id]=ref_456.
​
purpose
string
required
Define como o arquivo é validado e armazenado.
ValorVisibilidadeMIMEsTamanho máx
organization_avatarpúblicoPNG, JPG, WebP, GIF5 MB
product_imagepúblicoPNG, JPG, WebP, GIF2 MB
dispute_evidenceprivadoPNG, JPG, WebP, PDF5 MB
Arquivos públicos retornam url com a URL permanente em storage.chargefy.io. Arquivos privados retornam url com uma URL assinada de curta validade (1 hora) — refaça GET /v1/files/:id para obter uma URL nova.

​
(a) Foto de produto

Envia uma foto que você vai usar em product.image_url. 
curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "purpose=product_image" \
  -F "file=@/caminho/local/foto.webp"
Depois, atualize o produto apontando para a URL retornada: 
curl -X POST "https://api.chargefy.io/v1/products/id_123" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "<url do file retornado>"
  }'
Se a imagem deixar de ser usada, remova o arquivo com DELETE /v1/files/:id.

​
(b) Avatar de organização

Envia o avatar exibido em listas, recibos e e-mails transacionais. 
curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "purpose=organization_avatar" \
  -F "file=@/caminho/local/logo.png"

​
Resposta

200 OK com o objeto file completo. Todo campo declarado pelo DTO público é sempre retornado; vazio é null ou {}.
CampoTipoObservação
idstringID do arquivo (file_*)
objectstringSempre "file"
purposestringMesmo valor enviado
filenamestringNome amigável
mime_typestringMIME do binário recebido
sizeintegerTamanho em bytes
urlstring | nullURL para acessar o binário. Pública para organization_avatar/product_image; assinada (1h) para dispute_evidence.
livemodebooleantrue em produção; false em ambiente de teste
metadataobjectEco do metadata enviado
created_atstringISO 8601
updated_atstring | nullISO 8601
{
  "id": "file_123",
  "object": "file",
  "created_at": "2026-05-24T10:14:50Z",
  "filename": "foto.webp",
  "livemode": true,
  "metadata": {},
  "mime_type": "image/webp",
  "purpose": "product_image",
  "size": 184320,
  "updated_at": null,
  "url": "https://storage.chargefy.io/file_123"
}

​
Erros comuns

StatuscodeQuando ocorre
400invalid_requestpurpose ausente ou inválido; file ausente ou vazio; MIME não suportado para o purpose; tamanho acima do limite do purpose
400invalid_requestCorpo não é multipart/form-data válido
403permission_deniedpurpose não permitido para o tipo de autenticação enviado (ex.: user_avatar exige sessão de admin, não API key)