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

# Arquivos

> Envie e gerencie arquivos PDF. Todo certificado deve referenciar um arquivo enviado.

# Arquivos

Arquivos são documentos PDF enviados ao DokStamp antes de serem anexados a certificados ou documentos. Cada arquivo só pode ser usado por **um** certificado — uma vez anexado, ele é marcado como usado e não pode ser reutilizado.

***

## O objeto arquivo

```json theme={null}
{
  "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
  "original_name": "diploma-maria-silva.pdf",
  "mime_type": "application/pdf",
  "extension": "pdf",
  "size": 245760,
  "used_at": null,
  "file": "https://storage.dokstamp.eu/files/h8i9j0k1.pdf"
}
```

| Campo           | Tipo           | Descrição                                                        |
| --------------- | -------------- | ---------------------------------------------------------------- |
| `uuid`          | string         | Identificador único — use como `file_uuid` ao criar certificados |
| `original_name` | string         | Nome original do arquivo                                         |
| `mime_type`     | string         | Tipo MIME (ex.: `application/pdf`)                               |
| `extension`     | string         | Extensão do arquivo                                              |
| `size`          | integer        | Tamanho do arquivo em bytes                                      |
| `used_at`       | datetime\|null | Nulo = disponível. Não nulo = já anexado a um certificado.       |
| `file`          | string         | URL de download direto                                           |

***

## Enviar arquivos

```http theme={null}
POST /files
```

Aceita `multipart/form-data`. Você pode enviar múltiplos arquivos em uma única requisição.

| Parâmetro | Tipo | Obrigatório | Descrição               |
| --------- | ---- | ----------- | ----------------------- |
| `files[]` | file | Sim         | Um ou mais arquivos PDF |

<CodeGroup>
  ```bash cURL theme={null}
  # Enviar um único arquivo
  curl -X POST https://api.dokstamp.com/files \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}" \
    -F "files[]=@/caminho/para/diploma-maria-silva.pdf"

  # Enviar múltiplos arquivos de uma vez
  curl -X POST https://api.dokstamp.com/files \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}" \
    -F "files[]=@diploma-1.pdf" \
    -F "files[]=@diploma-2.pdf" \
    -F "files[]=@diploma-3.pdf"
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('files[]', pdfBlob, 'diploma-maria-silva.pdf');

  const res = await fetch('https://api.dokstamp.com/files', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'X-Tenant': TENANT,
      // NÃO defina Content-Type — deixe o navegador definir o boundary multipart
    },
    body: formData,
  });

  const { data } = await res.json();
  const fileUuid = data[0].uuid; // Use como file_uuid em POST /certificates
  ```

  ```php PHP theme={null}
  $response = Http::withToken($token)
      ->withHeaders(['X-Tenant' => $tenant, 'Accept' => 'application/json'])
      ->attach('files[]', file_get_contents($filePath), basename($filePath))
      ->post('https://api.dokstamp.com/files');

  $fileUuid = $response->json('data.0.uuid');
  ```
</CodeGroup>

**Resposta `201`:**

```json theme={null}
{
  "data": [
    {
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
      "original_name": "diploma-maria-silva.pdf",
      "mime_type": "application/pdf",
      "size": 245760,
      "used_at": null
    }
  ]
}
```

***

## Listar arquivos

```http theme={null}
GET /files
```

Filtrar por arquivos não utilizados (disponíveis para anexar a novos certificados):

```bash theme={null}
GET /files?where[used_at]=null
```

***

## Obter metadados do arquivo

```http theme={null}
GET /files/{uuid}
```

***

## Baixar um arquivo

```http theme={null}
GET /files/{uuid}/download
```

<Note>Este endpoint é **público** — nenhum cabeçalho `Authorization` necessário. Compartilhe esta URL diretamente com signatários, estudantes ou empregadores.</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.dokstamp.com/files/h8i9j0k1-l2m3-4567-nopq-678901234567/download" \
    --output diploma.pdf
  ```
</CodeGroup>

***

## Atualizar metadados do arquivo

```http theme={null}
PATCH /files/{uuid}
PUT   /files/{uuid}
```

***

## Excluir um arquivo

```http theme={null}
DELETE /files/{uuid}
```

<Warning>
  Você não pode excluir um arquivo que já está anexado a um certificado (`used_at` não é nulo). Exclua ou revogue o certificado primeiro.
</Warning>

***

## Deduplicação

A API calcula um `hash` para cada arquivo enviado. Se você enviar o mesmo conteúdo de arquivo duas vezes, o segundo envio retorna o registro de arquivo existente em vez de criar um duplicado. Isso evita o acúmulo desnecessário de armazenamento em fluxos de envio em lote.