> ## 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.

# Create a File

> Faz upload de um arquivo.

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

<ParamField body="file" type="binary" required>
  O binário do arquivo. Tamanho máximo varia por `purpose`.
</ParamField>

<ParamField body="filename" type="string">
  Nome amigável a aparecer em metadados. Quando omitido, usa o nome do arquivo
  enviado.
</ParamField>

<ParamField body="metadata[key]" type="string">
  Objeto livre `string → string` para correlacionar com o seu sistema. Use
  campos repetidos no formulário: `metadata[reference_id]=ref_456`.
</ParamField>

<ParamField body="purpose" type="string" required>
  Define como o arquivo é validado e armazenado.

  | Valor                 | Visibilidade | MIMEs               | Tamanho máx |
  | --------------------- | ------------ | ------------------- | ----------- |
  | `organization_avatar` | público      | PNG, JPG, WebP, GIF | 5 MB        |
  | `product_image`       | público      | PNG, JPG, WebP, GIF | 2 MB        |
  | `dispute_evidence`    | privado      | PNG, JPG, WebP, PDF | 5 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.
</ParamField>

### (a) Foto de produto

Envia uma foto que você vai usar em `product.image_url`.

<RequestExample>
  ```bash product_image theme={}
  curl -X POST "https://api.chargefy.io/v1/files" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -F "purpose=product_image" \
    -F "file=@/caminho/local/foto.webp"
  ```
</RequestExample>

Depois, atualize o produto apontando para a URL retornada:

```bash theme={}
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`](/api-reference/files/delete).

### (b) Avatar de organização

Envia o avatar exibido em listas, recibos e e-mails transacionais.

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

## 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 amigável                                                                                                          |
| `mime_type`  | `string`         | MIME do binário recebido                                                                                               |
| `size`       | `integer`        | Tamanho em bytes                                                                                                       |
| `url`        | `string \| null` | URL para acessar o binário. Pública para `organization_avatar`/`product_image`; assinada (1h) para `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                                                                                                               |

<ResponseExample>
  ```json Response 200 theme={}
  {
    "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"
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`              | Quando ocorre                                                                                                                     |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`   | `purpose` ausente ou inválido; `file` ausente ou vazio; MIME não suportado para o `purpose`; tamanho acima do limite do `purpose` |
| `400`  | `invalid_request`   | Corpo não é `multipart/form-data` válido                                                                                          |
| `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)               |