Criar um arquivo

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

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

{
  "id": "file_BaydQ5zABzUt9RnD",
  "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_BaydQ5zABzUt9RnD"
}

{
  "error": {
    "code": "invalid_request",
    "message": "purpose is required",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "Auth kind not allowed for purpose user_avatar",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "file_too_large",
    "message": "The file exceeds the 20 MB input limit.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unsupported_file_type",
    "message": "The file type is not supported.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "file_processing_failed",
    "message": "The image could not be processed.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

Envia um arquivo para a Chargefy. A purpose define onde o arquivo fica (público ou privado), o limite de entrada e o formato final. Imagens são normalizadas antes de serem armazenadas; PDFs e evidências permanecem no formato enviado. O file retornado descreve o binário final e carrega uma url que aponta para ele. Apenas purpose e file são obrigatórios, enviados como multipart/form-data. filename assume o nome do arquivo enviado, e a URL é gerada automaticamente pela Chargefy. 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 sua organização atua diretamente nela. Não envie o header Organization nesse caso.

Com Chargefy for Platforms, envie também Organization: org_... para atuar em uma organização filha ativa da plataforma.

Tipo de conteúdo

multipart/form-data.

Attributes

binary

required

O arquivo em si. Tamanho máximo varia por purpose.

string

Nome amigável a aparecer em metadados. Padrão: o nome do arquivo enviado.

string

Objeto livre string → string para correlacionar com o seu sistema. Envie campos repetidos no formulário somente quando precisar preenchê-lo. Ao omitir todos eles, o arquivo retorna metadata: {}.

string

required

Define como o arquivo é validado e armazenado.

Valor	Criação	Visibilidade	Entrada	Limite de entrada	Binário armazenado
`organization_avatar`	API ou Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 1024×1024 e 500 KB
`user_avatar`	Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 512×512 e 500 KB
`product_image`	API ou Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 640×640 e 500 KB
`platform_avatar`	Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 1024×1024 e 500 KB
`dispute_evidence`	API	privado	PNG, JPG, WebP, PDF	5 MB	Arquivo original
`kyc_document`	API, Dashboard ou ativação hospedada	privado	PNG, JPG, WebP, BMP, HEIC, HEIF ou PDF	imagem 20 MB; PDF 5 MB	WebP até 2500 px e 4,5 MB; PDF original

user_avatar e platform_avatar são gerenciados pelo Dashboard. API keys não podem criar esses purposes; a resposta é 403 permission_denied.kyc_document é a foto de documento de identidade ou selfie usada no cadastro financeiro de uma organização. Depois do upload, referencie o file_* no bloco verification com POST /v1/organizations/{id} — o fluxo completo está em Ativação por API. Nesse purpose o tipo real do binário prevalece sobre o Content-Type declarado. Uma imagem só é rejeitada quando não pode ser normalizada dentro do limite final; não é necessário comprimi-la antes do upload. PDFs não são recomprimidos.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.

O que a Chargefy resolve sozinha

filename — quando omitido, usa o nome do arquivo enviado no formulário.
Preparação de imagens — valida o arquivo e, quando necessário, ajusta a resolução e a compressão antes de gravar em WebP. Um WebP que já atende à política pode ser armazenado sem nova codificação. filename, mime_type, size e url descrevem sempre o binário armazenado.
url — gerada automaticamente: permanente em storage.chargefy.io para purposes públicos; assinada com validade de 1 hora para purposes privados.
Visibilidade e armazenamento — definidos pelo purpose; você não escolhe bucket nem visibilidade no payload.

(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.jpg"

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

Depois, atualize o produto apontando para a URL retornada:

curl -X POST "https://api.chargefy.io/v1/products/prod_jTwQA7w6xGjuA2q1" \
  -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 {}.

Campo	Tipo	Observação
`id`	`string`	ID do arquivo (`file_*`)
`object`	`string`	Sempre `"file"`
`purpose`	`string`	Mesmo valor enviado
`filename`	`string`	Nome do binário armazenado; imagens normalizadas terminam em `.webp`
`mime_type`	`string`	MIME do binário armazenado
`size`	`integer`	Tamanho do binário armazenado, em bytes
`url`	`string \| null`	URL para acessar o binário. Pública para `organization_avatar`/`product_image`; assinada (1h) para `dispute_evidence` e `kyc_document`.
`livemode`	`boolean`	`true` em produção; `false` em ambiente de teste
`metadata`	`object`	Eco do `metadata` enviado
`created_at`	`string`	ISO 8601
`updated_at`	`string \| null`	ISO 8601

{
  "id": "file_BaydQ5zABzUt9RnD",
  "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_BaydQ5zABzUt9RnD"
}

{
  "error": {
    "code": "invalid_request",
    "message": "purpose is required",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "Auth kind not allowed for purpose user_avatar",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "file_too_large",
    "message": "The file exceeds the 20 MB input limit.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unsupported_file_type",
    "message": "The file type is not supported.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "file_processing_failed",
    "message": "The image could not be processed.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

Erros comuns

Status	`code`	Quando ocorre
`400`	`invalid_request`	`purpose` ausente ou inválido; `file` ausente ou vazio; corpo multipart inválido
`401`	`authentication_failed`	API key ausente, inválida ou revogada
`403`	`permission_denied`	`purpose` não permitido para o tipo de autenticação enviado (ex.: `user_avatar` exige sessão de admin, não API key)
`413`	`file_too_large`	Imagem acima de 20 MB, PDF de KYC acima de 5 MB ou arquivo acima do limite do `purpose`
`415`	`unsupported_file_type`	Tipo de arquivo não suportado pelo `purpose`
`422`	`file_processing_failed`	A imagem era válida, mas não pôde ser normalizada dentro do tamanho final

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

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

{
  "id": "file_BaydQ5zABzUt9RnD",
  "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_BaydQ5zABzUt9RnD"
}

{
  "error": {
    "code": "invalid_request",
    "message": "purpose is required",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "Auth kind not allowed for purpose user_avatar",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "file_too_large",
    "message": "The file exceeds the 20 MB input limit.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unsupported_file_type",
    "message": "The file type is not supported.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "file_processing_failed",
    "message": "The image could not be processed.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Autenticação

Tipo de conteúdo

Attributes

O que a Chargefy resolve sozinha

(a) Foto de produto

(b) Avatar de organização

Resposta

Erros comuns

​Autenticação

​Tipo de conteúdo

​Attributes

​O que a Chargefy resolve sozinha

​(a) Foto de produto

​(b) Avatar de organização

​Resposta

​Erros comuns

Autenticação

Tipo de conteúdo

Attributes

O que a Chargefy resolve sozinha

(a) Foto de produto

(b) Avatar de organização

Resposta

Erros comuns