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

# Arquivos

> Envie PDFs, imagens, vídeos e logos para os seus QR codes.

> [!NOTE]
>
> A API do GetQR está em beta e disponível para workspaces selecionados. Os detalhes podem mudar antes do lançamento oficial.

QR codes de PDF, Image e Video apontam para um arquivo, e um logo personalizado também é um arquivo. O upload tem duas etapas: registre o arquivo para obter uma URL e depois envie os bytes para essa URL.

| Método | Caminho | Descrição |
| - | - | - |
| `POST` | `/api/v1/files` | [Registrar um upload de arquivo](#registrar-um-upload-de-arquivo) |

## Enviar um arquivo

**1. Registre o arquivo**

Chame [Registrar um upload de arquivo](#registrar-um-upload-de-arquivo) com o `target`, o `contentType` e o `size` do arquivo. O `target` define os tipos de conteúdo aceitos e o limite de tamanho. Você recebe um `fileId` e uma `uploadUrl`.

**2. Envie o arquivo**

Envie o arquivo com uma requisição `PUT` para a `uploadUrl`. O `Content-Type` e o `Content-Length` precisam corresponder exatamente ao `contentType` e ao `size` que você registrou: qualquer diferença é rejeitada. A URL é pré-assinada, então não adicione sua chave de API. Ela expira após 10 minutos.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf
```

**3. Use o ID do arquivo**

Passe o `fileId` ao [criar um QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md):

* Como `fileId` de um QR code `pdf`, `image` ou `video`. Envie com o target correspondente.
* Como `fileId` da imagem de perfil de um QR code `vcard`, `social`, `multilink` ou `event`. Envie com o target `logo`.
* Como `logoOptions.fileId`, com `logoOptions.type` definido como `uploaded`, para um logo personalizado. Envie com o target `logo`. Veja [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md).

## Limites

| `target` | Tipos de conteúdo aceitos | Tamanho máximo |
| - | - | - |
| `pdf` | `application/pdf` | 20 MB (20.971.520 bytes) |
| `image` | `image/*` | 5 MB (5.242.880 bytes) |
| `video` | `video/*` | 50 MB (52.428.800 bytes) |
| `logo` | `image/*` | 5 MB (5.242.880 bytes) |

* **Tipo MIME simples.** Envie um único tipo e subtipo em minúsculas, como `image/png`. Parâmetros como `;charset=` e listas são rejeitados.
* **Sem SVG.** Tipos baseados em XML, como `image/svg+xml`, não são aceitos. Envie uma imagem rasterizada, como `image/png` ou `image/jpeg`.

## Cabeçalhos

**Authorization** `string` *required*

`Bearer` seguido da sua chave de API. Veja [Autenticação](https://docs.getqr.com/pt-br/api/authentication.md).

**Content-Type** `string` *required*

`application/json`.

## Registrar um upload de arquivo

`POST /api/v1/files`

Registra um arquivo e retorna uma URL pré-assinada para onde enviá-lo. Esta chamada não envia o arquivo em si.

**target** `string` *required*

Para que serve o arquivo: `pdf`, `image`, `video` ou `logo`. Define os tipos de conteúdo aceitos e o limite de tamanho. Veja [Limites](#limites).

**contentType** `string` *required*

Tipo MIME do arquivo, por exemplo `application/pdf`, sem parâmetros. A requisição de upload precisa enviar exatamente este `Content-Type`.

**size** `integer` *required*

Tamanho exato do arquivo em bytes, um número inteiro positivo. É comparado com o limite do target. A requisição de upload precisa enviar exatamente este `Content-Length`.

**name** `string`

Nome original do arquivo, até 255 caracteres. Guardado para exibição no painel. Um caminho com `/` ou `\` é rejeitado.

**fileId** `string`

ID a passar como `fileId` ou `logoOptions.fileId`.

**uploadUrl** `string`

URL pré-assinada para onde fazer o `PUT` do arquivo.

**expiresIn** `integer`

Segundos até a `uploadUrl` expirar: `600`.

**method** `string`

Método HTTP do upload: `PUT`.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'
```

```json 200 theme={null}
{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}
```

## Problemas comuns

> [accordion] 422 "Content type … is not allowed for target"
>
> O tipo de conteúdo não corresponde ao target. Por exemplo, `pdf` aceita apenas `application/pdf`. Veja [Limites](#limites).

> [accordion] 422 "must be a single lowercase type/subtype"
>
> Envie o tipo de conteúdo em minúsculas e sem parâmetros: `image/png`, e não `Image/PNG` ou `image/png; charset=utf-8`.

> [accordion] 422 "File is too large for target"
>
> O `size` declarado está acima do limite do target. Comprima o arquivo antes de registrá-lo.

> [accordion] O upload para a uploadUrl falha
>
> A URL expira 10 minutos depois que você registra o arquivo, e a requisição precisa enviar exatamente o `Content-Type` e o `Content-Length` registrados. Registre o arquivo de novo para obter uma nova URL.

> [accordion] 422 "is registered but its content was never uploaded" ao criar um QR code
>
> Você registrou o arquivo, mas o `PUT` para a `uploadUrl` não foi concluído. Envie o arquivo e depois crie o QR code.

> [accordion] 422 "was uploaded to …" ao criar um QR code
>
> O arquivo foi registrado com outro target, por exemplo um arquivo `image` usado em um QR code `pdf`. Registre um novo upload com o target correspondente.

> [accordion] 404 "File … was not found" ao criar um QR code
>
> O `fileId` não existe. Pegue-o na resposta de [Registrar um upload de arquivo](#registrar-um-upload-de-arquivo).

## Próximos passos

> [card] [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md)

> [card] [Tipos de QR](https://docs.getqr.com/pt-br/api/guides/qr-types.md)

> [card] [Personalização](https://docs.getqr.com/pt-br/api/guides/customization.md)

> [card] [Erros](https://docs.getqr.com/pt-br/api/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.