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

# Ficheiros

> Carregue PDF, imagens, vídeos e logótipos para os seus códigos QR.

> [!NOTE]
>
> A API do GetQR está em versão beta e só está disponível para alguns espaços de trabalho. Os detalhes podem mudar antes do lançamento geral.

Os códigos QR de PDF, imagem e vídeo apontam para um ficheiro, e um logótipo personalizado também é um ficheiro. O carregamento tem dois passos: registe o ficheiro para obter um URL e, em seguida, envie os bytes para esse URL.

| Método | Caminho | Descrição |
| - | - | - |
| `POST` | `/api/v1/files` | [Registar o carregamento de um ficheiro](#registar-o-carregamento-de-um-ficheiro) |

## Carregar um ficheiro

**1. Registe o ficheiro**

Chame [Registar o carregamento de um ficheiro](#registar-o-carregamento-de-um-ficheiro) com o `target`, o `contentType` e o `size` do ficheiro. O `target` define os tipos de conteúdo aceites e o limite de tamanho. Recebe um `fileId` e um `uploadUrl`.

**2. Envie o ficheiro**

Envie o ficheiro com um pedido `PUT` para `uploadUrl`. O respetivo `Content-Type` e `Content-Length` têm de corresponder exatamente ao `contentType` e ao `size` que registou: qualquer outro valor é rejeitado. O URL é pré-assinado, por isso não adicione a sua chave de API. Expira ao fim de 10 minutos.

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

**3. Use o ID do ficheiro**

Passe `fileId` quando [criar um código QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md):

* Como `fileId` num código QR `pdf`, `image` ou `video`. Carregue-o com o target correspondente.
* Como `fileId` para a imagem de perfil de um código QR `vcard`, `social`, `multilink` ou `event`. Carregue-o com o target `logo`.
* Como `logoOptions.fileId`, com `logoOptions.type` definido como `uploaded`, para um logótipo personalizado. Carregue-o com o target `logo`. Consulte [Personalização](https://docs.getqr.com/pt/api/guides/customization.md).

## Limites

| `target` | Tipos de conteúdo aceites | 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`. Os parâmetros, como `;charset=`, e as listas são rejeitados.
* **Sem SVG.** Os tipos baseados em XML, como `image/svg+xml`, não são aceites. Carregue uma imagem rasterizada, como `image/png` ou `image/jpeg`.

## Cabeçalhos

**Authorization** `string` *required*

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

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

`application/json`.

## Registar o carregamento de um ficheiro

`POST /api/v1/files`

Regista um ficheiro e devolve um URL pré-assinado para onde o carregar. Esta chamada não carrega o ficheiro em si.

**target** `string` *required*

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

**contentType** `string` *required*

Tipo MIME do ficheiro, por exemplo `application/pdf`, sem parâmetros. O pedido de carregamento tem de enviar exatamente este `Content-Type`.

**size** `integer` *required*

Tamanho exato do ficheiro em bytes, um número inteiro positivo. É verificado face ao limite do target. O pedido de carregamento tem de enviar exatamente este `Content-Length`.

**name** `string`

Nome original do ficheiro, até 255 caracteres. É guardado para apresentação no painel. Um caminho com `/` ou `\` é rejeitado.

**fileId** `string`

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

**uploadUrl** `string`

URL pré-assinado para onde enviar o ficheiro com `PUT`.

**expiresIn** `integer`

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

**method** `string`

Método HTTP do carregamento: `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` só aceita `application/pdf`. Consulte [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` nem `image/png; charset=utf-8`.

> [accordion] 422 "File is too large for target"
>
> O `size` declarado ultrapassa o limite do target. Comprima o ficheiro antes de o registar.

> [accordion] O carregamento para uploadUrl falha
>
> O URL expira 10 minutos depois de registar o ficheiro, e o pedido tem de enviar exatamente o `Content-Type` e o `Content-Length` registados. Registe o ficheiro novamente para obter um novo URL.

> [accordion] 422 "is registered but its content was never uploaded" ao criar um código QR
>
> Registou o ficheiro, mas o `PUT` para `uploadUrl` não foi concluído. Carregue o ficheiro e, em seguida, crie o código QR.

> [accordion] 422 "was uploaded to …" ao criar um código QR
>
> O ficheiro foi registado com outro target, por exemplo um ficheiro `image` usado num código QR `pdf`. Registe um novo carregamento com o target correspondente.

> [accordion] 404 "File … was not found" ao criar um código QR
>
> O `fileId` não existe. Obtenha-o na resposta de [Registar o carregamento de um ficheiro](#registar-o-carregamento-de-um-ficheiro).

## Próximos passos

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

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

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

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


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