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",
  "expires_at": null,
  "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": "invalid_request",
    "message": "The PDF is encrypted; upload an unprotected copy.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided: ch_live_***************************************9f2c",
    "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 de avatar, produto, logo principal e KYC são normalizadas antes de serem armazenadas; PDFs, o logotipo do rodapé e arquivos de evidência de disputa 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

obrigatório

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

obrigatório

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é 256×256 e 40 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é 600 px no maior lado e 80 KB, preservando a proporção
`order_bump_image`	API ou Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 240 px no maior lado e 30 KB, preservando a proporção
`checkout_cover_image`	API ou Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 600 px no maior lado e 100 KB, preservando a proporção
`platform_avatar`	Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 256×256 e 40 KB
`branding_logo`	Dashboard	público	PNG, JPG, WebP, GIF, BMP, HEIC, HEIF	20 MB	WebP até 600×300 e 40 KB
`branding_footer_logo`	Dashboard	público	SVG estático, PNG, WebP	10 KB	Original, sem recompressão; PNG/WebP até 600×200
`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
`dispute_evidence`	API ou Dashboard	privado	PDF, JPG, PNG	7 MB	original

user_avatar, platform_avatar, branding_logo e branding_footer_logo são gerenciados pelo Dashboard. API keys não podem criar esses purposes; a resposta é 403 permission_denied.dispute_evidence é um documento da defesa de uma disputa — recibo, conversa com o comprador, comprovante de envio. Um PDF protegido por senha ou com conteúdo ilegível é recusado com 400. A defesa tem limites somados de páginas e tamanho, conferidos quando você anexa o arquivo à disputa e no envio — o PDF conta as páginas reais e cada imagem conta como uma página. Depois do upload, referencie o file_* em um campo de arquivo de evidence com POST /v1/disputes/{id} — o passo a passo está em Responder a disputas.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 Ativar organizaçã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. O arquivo espera 30 dias pelo cadastro: a resposta traz expires_at e, vencido esse prazo sem ser apontado, o bloco verification o recusa com 400 file_expired — envie o arquivo de novo. Apontado, a validade zera. Nenhum arquivo é apagado pela validade.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.

Avatar de organização

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

(c) Evidência de disputa

Envia um documento da defesa de uma disputa. Faça um upload por documento — cada campo de arquivo da defesa recebe um file_* próprio.

Evidência de disputa

curl -X POST "https://api.chargefy.io/v1/files" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "purpose=dispute_evidence" \
  -F "file=@/caminho/local/recibo.pdf;type=application/pdf"

Depois, anexe o file_* retornado ao campo correspondente de evidence:

curl -X POST "https://api.chargefy.io/v1/disputes/dp_5mK8wQ2rT9nV4xJc" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "receipt": "file_W7pR4kM9qT2xN6vB"
    },
    "submit": false
  }'

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"`
`expires_at`	`string \| null`	Validade de um `kyc_document` ainda não apontado no cadastro (30 dias); `null` para os demais purposes
`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 `kyc_document` e `dispute_evidence`.
`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",
  "expires_at": null,
  "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": "invalid_request",
    "message": "The PDF is encrypted; upload an unprotected copy.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided: ch_live_***************************************9f2c",
    "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
`400`	`invalid_request`	PDF de evidência de disputa protegido por senha ou ilegível — a contagem de páginas precisa ser possível no upload
`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, evidência de disputa acima de 7 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",
  "expires_at": null,
  "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": "invalid_request",
    "message": "The PDF is encrypted; upload an unprotected copy.",
    "param": "file",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided: ch_live_***************************************9f2c",
    "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

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Autenticação

Tipo de conteúdo

Attributes

O que a Chargefy resolve sozinha

(a) Foto de produto

(b) Avatar de organização

(c) Evidência de disputa

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

​(c) Evidência de disputa

​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

(c) Evidência de disputa

Resposta

Erros comuns