> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto File

Um `file` representa um arquivo binário que você enviou para a Chargefy e que fica hospedado para ser referenciado por outros recursos — uma foto usada em `product.image_url`, o avatar exibido em listas e recibos, ou um documento anexado como evidência de disputa. Cada `file` guarda os metadados do binário (nome, tipo MIME, tamanho) e expõe uma `url` que aponta para o conteúdo hospedado.

Ele surge quando você faz upload pela API e a `purpose` define como o arquivo é armazenado: arquivos públicos devolvem uma `url` permanente em `storage.chargefy.io`, enquanto arquivos privados devolvem uma URL assinada de curta validade, regenerada a cada leitura. O upload em si não vincula o arquivo a nenhum recurso — guardar a `url` no campo de destino é responsabilidade do recurso que vai referenciá-lo.

## Data Object

Este é o formato completo retornado em `create`, `get` e itens de `list`.

```json theme={}
{
  "id": "file_123",
  "object": "file",
  "created_at": "2026-05-16T14:09:27Z",
  "filename": "foto.webp",
  "livemode": true,
  "metadata": {
    "reference_id": "id_456"
  },
  "mime_type": "image/webp",
  "purpose": "product_image",
  "size": 184320,
  "updated_at": null,
  "url": "https://storage.chargefy.io/file_123"
}
```

<ResponseField name="id" type="string">
  Identificador do arquivo. Usa o prefixo `file_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"file"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="filename" type="string">
  Nome amigável do arquivo. Quando não foi informado no upload, usa o nome do
  binário enviado.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Objeto livre para correlacionar o arquivo com o seu sistema. Quando vazio,
  retorna `{}`.
</ResponseField>

<ResponseField name="mime_type" type="string">
  Tipo MIME do binário recebido, como `image/webp` ou `application/pdf`.
</ResponseField>

<ResponseField name="purpose" type="string">
  Define como o arquivo foi validado e armazenado. Um de `organization_avatar`,
  `user_avatar`, `product_image` ou `dispute_evidence`.
</ResponseField>

<ResponseField name="size" type="integer">
  Tamanho do arquivo em bytes.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601. Vem `null` enquanto o arquivo nunca
  foi atualizado.
</ResponseField>

<ResponseField name="url" type="string | null">
  URL para acessar o binário hospedado. Permanente para arquivos públicos
  (`organization_avatar`, `user_avatar`, `product_image`); assinada e de curta
  validade (1 hora) para arquivos privados (`dispute_evidence`), regenerada a
  cada `get`. Vem `null` quando a URL não pôde ser resolvida.
</ResponseField>

## Operações

* [Listar arquivos](/api-reference/files/list)
* [Enviar arquivo](/api-reference/files/create)
* [Consultar arquivo](/api-reference/files/get)
* [Excluir arquivo](/api-reference/files/delete)