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

# Códigos QR

> Crie, liste, atualize, coloque em pausa, duplique, elimine e transfira 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.

No GetQR, um código QR é a imagem mais uma ligação curta através da qual é resolvido. Criar um código QR cria também a respetiva ligação curta, pelo que pode alterar o destino mais tarde sem voltar a imprimir o código.

| Método | Caminho | Descrição |
| - | - | - |
| `GET` | `/api/v1/qrs` | [Listar códigos QR](#listar-códigos-qr) |
| `POST` | `/api/v1/qrs` | [Criar um código QR](#criar-um-código-qr) |
| `GET` | `/api/v1/qrs/{qrId}` | [Obter um código QR](#obter-um-código-qr) |
| `PATCH` | `/api/v1/qrs/{qrId}` | [Atualizar um código QR](#atualizar-um-código-qr) |
| `PUT` | `/api/v1/qrs/{qrId}` | [Definir o estado de pausa](#definir-o-estado-de-pausa) |
| `POST` | `/api/v1/qrs/{qrId}/pause` | [Pausar um código QR](#pausar-um-código-qr) |
| `POST` | `/api/v1/qrs/{qrId}/activate` | [Reativar um código QR](#reativar-um-código-qr) |
| `POST` | `/api/v1/qrs/{qrId}/duplicate` | [Duplicar um código QR](#duplicar-um-código-qr) |
| `DELETE` | `/api/v1/qrs/{qrId}` | [Eliminar um código QR](#eliminar-um-código-qr) |
| `GET` | `/api/v1/qrs/{qrId}/download` | [Transferir a imagem de um código QR](#transferir-a-imagem-de-um-código-qr) |

> [card] [Dados do código QR por tipo](https://docs.getqr.com/pt/api/guides/qr-types.md)
>
> O formato de `data` de cada um dos 16 tipos.

> [card] [Personalização](https://docs.getqr.com/pt/api/guides/customization.md)
>
> Estilos de pontos, cores, molduras e logótipos.

> [card] [Regras de acesso](https://docs.getqr.com/pt/api/guides/access-rules.md)
>
> Agendamento, limite de leituras e palavra-passe.

Para as estatísticas de leituras de um código QR, consulte [Estatísticas](https://docs.getqr.com/pt/api/endpoints/analytics.md).

## O objeto de código QR

Todos os endpoints de códigos QR respondem com este objeto, exceto [Eliminar](#eliminar-um-código-qr) e [Transferir](#transferir-a-imagem-de-um-código-qr). A listagem devolve um array destes objetos.

**id** `string`

ID único do código QR, por exemplo `qr_1EPcVfeHZAY2iNoVLsgW2Aqf`.

**qrType** `string`

Tipo de código QR, por exemplo `website`. Consulte [Dados do código QR por tipo](https://docs.getqr.com/pt/api/guides/qr-types.md) para ver os 16 valores.

**title** `string | null`

Nome do código QR, apresentado no painel.

**description** `string | null`

Nota livre sobre o código QR.

**data** `string`

O payload guardado. Em `wifi`, `vcard`, `social`, `multilink`, `event` e `sms`, é o payload que enviou. Nos restantes tipos, é a ligação curta, pelo que deve ler o destino em `url`.

**archived** `boolean`

`true` quando o código QR está em pausa.

**isStatic** `boolean`

`true` num código QR estático criado no painel, que não tem ligação curta. A API cria sempre códigos QR dinâmicos.

**shortLink** `string | null`

Ligação curta completa, por exemplo `https://getqr.sh/x7Kd2p1`.

**domain** `string | null`

Domínio da ligação curta.

**key** `string | null`

Slug da ligação curta.

**keyIsCustom** `boolean`

`true` quando o slug foi escolhido em vez de gerado.

**url** `string | null`

Destino para o qual a ligação curta redireciona.

**ios** `string | null`

Destino para os visitantes em iOS, nos códigos QR `app`.

**android** `string | null`

Destino para os visitantes em Android, nos códigos QR `app`.

**scans** `integer`

Número total de leituras.

**access** `object`

Regras de acesso. A palavra-passe nunca é devolvida. Consulte [Regras de acesso](https://docs.getqr.com/pt/api/guides/access-rules.md).

**properties**

**passwordProtected** `boolean`

Se os visitantes têm de introduzir uma palavra-passe.

**activeAt** `string | null`

Início agendado, ISO 8601.

**pauseAt** `string | null`

Fim agendado, ISO 8601.

**scanLimit** `integer | null`

Número máximo de leituras.

**designKind** `string`

Só de leitura. `custom` é um design que a API pode editar na totalidade. `branded` e `ai` são um Branded design ou um AI design criado no painel. A API não pode editar a respetiva imagem, mas mantém-na quando altera outros campos.

**design** `object`

O design guardado: `styles`, `frameOptions` e `logoOptions`, cada um um objeto ou `null`. Têm a mesma estrutura dos campos do pedido, pelo que os pode reenviar. Consulte [Personalização](https://docs.getqr.com/pt/api/guides/customization.md).

**file** `object | null`

O ficheiro de um código QR `pdf`, `image` ou `video`: `id`, `name` e `size` em bytes.

**appName** `string | null`

Só de leitura. Nome apresentado de um código QR `app` criado no painel.

**pdfBundle** `object | null`

Só de leitura. Um código QR `pdf` com vários ficheiros, criado no painel: `title`, `layout` e `files`.

**imageGallery** `object | null`

Só de leitura. Um código QR `image` com várias imagens, criado no painel: `title`, `layout` e `files`.

**createdAt** `string`

Data de criação, ISO 8601.

**updatedAt** `string`

Data da última atualização, ISO 8601.

Os segredos e os IDs internos (`password`, `userId`, `workspaceId`, `projectId`) nunca são devolvidos.

```json theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}
```

## Listar códigos QR

`GET /api/v1/qrs`

Devolve os códigos QR do seu espaço de trabalho, uma página de cada vez.

**page** `integer` (default: 1)

Página a devolver, 1 ou mais.

**pageSize** `integer` (default: 100)

Códigos QR por página, de 1 a 100. Um valor superior é rejeitado.

**search** `string`

Pesquisa no título do código QR. As pesquisas com mais de 2 caracteres também pesquisam no `data` guardado. Nos tipos de ligação, o `data` guardado é a ligação curta, pelo que não é possível pesquisar pelos URL de destino.

**sortBy** `string` (default: createdAt)

Campo pelo qual ordenar: `createdAt`, `updatedAt`, `clicks` (leituras totais), `lastClicked` (última leitura) ou `type`. `type` ordena sempre por ordem decrescente e ignora `sortOrder`.

**sortOrder** `string` (default: desc)

Sentido da ordenação: `asc` ou `desc`.

**showArchived** `boolean` (default: false)

Inclui os códigos QR em pausa.

**onlyArchived** `boolean` (default: false)

Devolve apenas os códigos QR em pausa. Prevalece sobre `showArchived`.

Os parâmetros booleanos aceitam as strings `true` ou `false`. Peça a página seguinte enquanto `pagination.hasMore` for `true`. Consulte [Paginação](https://docs.getqr.com/pt/api/introduction.md#paginação).

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Criar um código QR

`POST /api/v1/qrs`

Cria um código QR e a respetiva ligação curta em conjunto. Responde `201 Created` com o novo [código QR](#o-objeto-de-código-qr).

**Idempotency-Key** `string`

O seu próprio token de repetição. Se repetir o pedido com a mesma chave no prazo de 24 horas, recebe a resposta original em vez de um segundo código QR. Consulte [Repetições e duplicados](#repetições-e-duplicados).

**qrType** `string` *required*

O que o código QR codifica. Define também o formato que `data` tem de ter. Um de `website`, `pdf`, `image`, `video`, `whatsapp`, `social`, `wifi`, `app`, `feedback`, `vcard`, `sms`, `payment`, `location`, `multilink`, `email`, `event`.

**data** `string` *required*

O payload do tipo, validado face a `qrType`. Uma string vazia ignora a validação. O formato de cada tipo está em [Dados do código QR por tipo](https://docs.getqr.com/pt/api/guides/qr-types.md).

**link** `object`

A ligação curta através da qual o código QR é resolvido. Opcional: se for omitida, `link.url` segue `data`.

**properties**

**url** `string`

Destino para o qual a ligação curta redireciona. Se for omitido ou estiver vazio, assume o valor de `data`. Quando ambos são enviados e são diferentes, prevalece `link.url`. Os códigos QR `vcard`, `social`, `multilink` e `event` apontam sempre para a respetiva página alojada, e os códigos QR `pdf`, `image` e `video` com um `fileId`, para o ficheiro. Esquemas aceites: `http:`, `https:`, `wifi:`, `mailto:`, `sms:`, `begin:`.

**domain** `string`

Domínio da ligação curta. Tem de ser um domínio ativo do seu espaço de trabalho: outro domínio devolve `403`, e um domínio que ainda não está ativo devolve `422`. Por predefinição, o domínio predefinido do espaço de trabalho.

**key** `string`

Slug da ligação curta, de 3 a 15 caracteres, guardado em minúsculas. Um slug não permitido devolve `422`, e um slug já utilizado devolve `409`. Se for omitido, é gerado um slug aleatório de 7 caracteres.

**ios** `string | null`

URL de destino para os visitantes em iOS, nos códigos QR `app`.

**android** `string | null`

URL de destino para os visitantes em Android, nos códigos QR `app`.

**title** `string | null`

Título da pré-visualização da ligação (`og:title`), guardado na ligação curta. Não confundir com o `title` do próprio código QR. De momento, não é apresentado em lado nenhum.

**description** `string | null`

Descrição da pré-visualização da ligação (`og:description`), guardada na ligação curta. De momento, não é apresentada em lado nenhum.

**expiresAt, expiredUrl** `—`

Não disponíveis nesta API: enviar qualquer um deles devolve `422`. Use `access.pauseAt` para parar o código QR num determinado momento.

**title** `string`

Nome do código QR, apresentado no painel. Os espaços no início e no fim são removidos; de 1 a 40 caracteres. Se for omitido, o código QR fica sem título.

**description** `string`

Nota livre sobre o código QR. Até 280 caracteres.

**fileId** `string`

O ficheiro de um código QR `pdf`, `image` ou `video`, carregado com o target correspondente. Em `vcard`, `social` e `multilink`, uma imagem de perfil opcional carregada com o target `logo`. `event` também o aceita, mas a respetiva página lê a capa a partir de `data.fileId`. Os outros tipos devolvem `422`. Carregue primeiro o ficheiro com [Ficheiros](https://docs.getqr.com/pt/api/endpoints/files.md). Consulte [Ficheiros em códigos QR](https://docs.getqr.com/pt/api/guides/qr-types.md#ficheiros-em-códigos-qr).

**templateId** `string`

[Modelo](https://docs.getqr.com/pt/api/endpoints/templates.md) cujo design é aplicado ao novo código QR. Os campos de design que enviar são combinados sobre ele. Um modelo de Branded design ou AI design devolve `422` (`art_template_unsupported`). Um modelo desconhecido, ou de outro espaço de trabalho, devolve `404`.

**styles** `object`

Formas e cores dos pontos e dos cantos. Consulte [Personalização](https://docs.getqr.com/pt/api/guides/customization.md).

**frameOptions** `object`

Moldura desenhada à volta do código QR e o respetivo texto de apelo à ação. Consulte [Personalização](https://docs.getqr.com/pt/api/guides/customization.md).

**logoOptions** `object`

Logótipo no centro: um logótipo sugerido ou o seu próprio ficheiro carregado com o target `logo`. Um ficheiro desconhecido, um carregamento não concluído ou um ficheiro de outro target é rejeitado. Consulte [Personalização](https://docs.getqr.com/pt/api/guides/customization.md).

**access** `object`

Agendamento, limite de leituras e proteção por palavra-passe. Consulte [Regras de acesso](https://docs.getqr.com/pt/api/guides/access-rules.md).

**properties**

**activeAt** `string | null`

Início agendado, ISO 8601.

**pauseAt** `string | null`

Fim agendado, ISO 8601.

**scanLimit** `integer | null`

Número máximo de leituras, um número inteiro positivo.

**password** `string | null`

Palavra-passe que os visitantes têm de introduzir. Enviá-la ativa a proteção.

**passwordProtected** `boolean`

Desativa ou volta a ativar a proteção, mantendo a palavra-passe guardada.

**archived** `boolean`

Se o código QR está em pausa. `true` cria-o já em pausa: as leituras mostram a página de pausa em vez do destino.

Os campos desconhecidos são descartados sem erro. Consulte [Não suportado na API](https://docs.getqr.com/pt/api/guides/qr-types.md#não-suportado-na-api).

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'
```

```json 201 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}
```

### Repetições e duplicados

* **Com chave.** Com um cabeçalho `Idempotency-Key`, a resposta é reproduzida durante 24 horas.
* **Sem chave.** Um corpo idêntico enviado no espaço de 30 segundos é tratado como duplicado.
* **Reproduções.** Uma reprodução devolve a resposta guardada com `x-idempotent-replay: true`. Um novo código QR devolve `false`.
* **Em curso.** Um segundo pedido enquanto o primeiro ainda está em curso devolve `409 conflict`.
* **Falhas.** Uma criação falhada liberta a chave de imediato, pelo que pode repetir com a mesma chave.
* **Sem garantia.** Se a proteção não estiver disponível, as criações são processadas sem proteção.

Consulte também [Idempotência](https://docs.getqr.com/pt/api/introduction.md#idempotência).

## Obter um código QR

`GET /api/v1/qrs/{qrId}`

Devolve um [código QR](#o-objeto-de-código-qr) com a respetiva ligação curta, regras de acesso, design e, nos tipos baseados em ficheiros, o ficheiro.

**qrId** `string` *required*

ID do código QR, obtido na resposta da listagem ou da criação.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

A resposta é o [objeto de código QR](#o-objeto-de-código-qr) completo.

## Atualizar um código QR

`PATCH /api/v1/qrs/{qrId}`

Altera o conteúdo, o destino, o design ou as regras de acesso de um código QR. Envie apenas os campos que pretende alterar. Responde com o [código QR](#o-objeto-de-código-qr) atualizado.

**qrId** `string` *required*

ID do código QR.

O corpo aceita os mesmos campos de [Criar um código QR](#criar-um-código-qr), todos opcionais, com estas diferenças:

* **`templateId`.** Não é aceite.
* **`link`.** Parcial. O destino atual é mantido se omitir `link.url`. `link.domain` e `link.key` devolvem `422`: a ligação curta é o que o código impresso codifica, por isso crie um novo código QR para usar outra.
* **`data`.** Só é validado face ao tipo resultante quando `data` ou `qrType` muda. Mudar `qrType` sem um `data` correspondente é rejeitado. Consulte [Mudar de tipo](https://docs.getqr.com/pt/api/guides/qr-types.md#mudar-de-tipo).
* **Design.** `styles`, `frameOptions` e `logoOptions` são combinados com o design guardado, pelo que um objeto parcial só altera o que indica. Escolher outro logótipo substitui-o, mas mantém o respetivo tamanho.
* **`access`.** Cada chave é aplicada quando está presente. `null` apaga uma regra. As regras de acesso ficam dentro de `access`: enviá-las dentro de `link` devolve `422`.
* **`archived`.** Coloca em pausa ou reativa em conjunto o código QR e a ligação curta, tal como [Pausar](#pausar-um-código-qr) e [Reativar](#reativar-um-código-qr).

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}
```

O que cada tipo permite alterar após a impressão está indicado em [Dados do código QR por tipo](https://docs.getqr.com/pt/api/guides/qr-types.md).

## Definir o estado de pausa

`PUT /api/v1/qrs/{qrId}`

Define diretamente o estado de pausa. [Pausar](#pausar-um-código-qr) e [Reativar](#reativar-um-código-qr) fazem o mesmo de forma mais legível.

**qrId** `string` *required*

ID do código QR.

**archived** `boolean` *required*

`true` para colocar o código QR em pausa, `false` para o reativar.

```bash cURL theme={null}
curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}
```

## Pausar um código QR

`POST /api/v1/qrs/{qrId}/pause`

O código QR deixa de encaminhar para o destino: as leituras mostram a página de pausa. O código impresso e a ligação curta continuam válidos. Sem corpo de pedido.

**qrId** `string` *required*

ID do código QR.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}
```

## Reativar um código QR

`POST /api/v1/qrs/{qrId}/activate`

Um código QR em pausa volta a encaminhar para o destino. O agendamento e o limite de leituras continuam a aplicar-se. Sem corpo de pedido.

**qrId** `string` *required*

ID do código QR.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}
```

## Duplicar um código QR

`POST /api/v1/qrs/{qrId}/duplicate`

Cria uma cópia com o mesmo conteúdo e design. Sem corpo de pedido. Responde `201 Created` com o novo [código QR](#o-objeto-de-código-qr).

**qrId** `string` *required*

ID do código QR a copiar.

* **Ligação curta.** A cópia recebe a sua própria ligação curta, com um slug aleatório no domínio predefinido do espaço de trabalho, e não no domínio do original. As respetivas leituras são contadas em separado.
* **Título.** O título recebe o sufixo ` (Copy)`. O resultado não ultrapassa os 40 caracteres: um título longo é encurtado primeiro. Um código QR sem título continua sem título.
* **Não copiado.** As regras de acesso (palavra-passe, agendamento, limite de leituras) e o estado de pausa. A cópia fica sempre ativa.
* **Ficheiros.** Os ficheiros PDF e de imagem, incluindo os de conjuntos e galerias, são copiados, pelo que passam a pertencer à cópia. Os ficheiros de vídeo e os ficheiros de design, como os logótipos, são partilhados com o original.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 201 theme={null}
{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}
```

## Eliminar um código QR

`DELETE /api/v1/qrs/{qrId}`

Elimina o código QR e a respetiva ligação curta. Responde com o ID eliminado.

> [!WARNING]
>
> A eliminação é permanente. O código impresso e a ligação curta deixam de funcionar, e o histórico de leituras deixa de estar acessível. Se puder voltar a precisar dele, [coloque o código QR em pausa](#pausar-um-código-qr).

**qrId** `string` *required*

ID do código QR.

**id** `string`

ID do código QR eliminado.

**deleted** `boolean`

Sempre `true`.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }
```

## Transferir a imagem de um código QR

`GET /api/v1/qrs/{qrId}/download`

Gera o código QR com o respetivo design e devolve o ficheiro.

**qrId** `string` *required*

ID do código QR a gerar, obtido na resposta da listagem ou da criação.

**format** `string` (default: jpg)

Formato de saída: `jpg`, `png`, `svg`, `pdf` (uma página A4) ou `eps`. Um Branded design ou AI design só é transferido em `jpg`, `png` ou `pdf`.

**resolution** `integer` (default: 1024)

Tamanho da imagem em píxeis: `1024`, `2048` ou `4096`. `svg` e `pdf` ignoram este valor. Um Branded design ou AI design só é transferido em `1024`.

| `format` | `Content-Type` | Nome do ficheiro |
| - | - | - |
| `jpg` | `image/jpeg` | `<title>-<resolution>px.jpg` |
| `png` | `image/png` | `<title>-<resolution>px.png` |
| `svg` | `image/svg+xml` | `<title>.svg` |
| `pdf` | `application/pdf` | `<title>.pdf` |
| `eps` | `application/postscript` | `<title>-<resolution>px.eps` |

* **Corpo.** O corpo da resposta é o ficheiro. O nome de ficheiro sugerido está no cabeçalho `Content-Disposition`, criado a partir do título, ou `qr-code` num código QR sem título.
* **Cache.** As respostas incluem um `ETag` e `Cache-Control: private, max-age=3600, must-revalidate`. Reenvie o `ETag` em `If-None-Match` para receber `304 Not Modified` quando o código QR não tiver mudado.
* **Erros.** Um formato ou uma resolução não suportados devolvem `400 bad_request`. A mensagem de erro indica o motivo: `qr_download_invalid_format`, `qr_download_invalid_resolution`, `qr_download_art_format_unsupported` ou `qr_download_art_resolution_unsupported`.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>
```

## Regras de acesso

Envie um objeto `access` na criação ou na atualização para agendar um início e um fim, limitar o número de leituras ou exigir uma palavra-passe. As regras omitidas não são alteradas, e `null` apaga uma regra. O comportamento completo, com exemplos, está em [Regras de acesso](https://docs.getqr.com/pt/api/guides/access-rules.md).

## Objetos de design

`styles`, `frameOptions` e `logoOptions` definem as formas dos pontos e dos cantos, as cores, a moldura e o logótipo. Funcionam da mesma forma em códigos QR, [modelos](https://docs.getqr.com/pt/api/endpoints/templates.md) e [criações em massa](https://docs.getqr.com/pt/api/endpoints/bulk-qr-creations.md). As formas, molduras ou logótipos desconhecidos são rejeitados. Todos os valores aceites e um exemplo completo estão em [Personalização](https://docs.getqr.com/pt/api/guides/customization.md).

## Problemas comuns

> [accordion] 422 ao definir uma palavra-passe, um agendamento ou um limite de leituras
>
> Envie a regra dentro de `access` e não dentro de `link`.

> [accordion] 422 ao alterar link.domain ou link.key
>
> A ligação curta não pode mudar depois da criação, porque é o que o código impresso codifica. Crie um novo código QR.

> [accordion] 422 "Expected … for qrType"
>
> `data` não corresponde ao formato de `qrType`. Verifique o tipo em [Dados do código QR por tipo](https://docs.getqr.com/pt/api/guides/qr-types.md).

> [accordion] 409 conflict ao criar um código QR
>
> Uma criação idêntica ainda está em curso, ou `link.key` já está a ser utilizado. Repita quando o primeiro pedido terminar. Com uma `Idempotency-Key`, a repetição devolve o código QR original.

> [accordion] A transferência é um JPEG e não um PNG
>
> Os parâmetros são `format` e `resolution`, e `format` é `jpg` por predefinição. Envie `format=png`.

> [accordion] 404 num código QR que vejo no painel
>
> Cada pedido é executado no espaço de trabalho da sua chave de API. Verifique se o código QR pertence a esse espaço de trabalho. Consulte [Autenticação](https://docs.getqr.com/pt/api/authentication.md).

## Próximos passos

> [card] [Dados do código QR por tipo](https://docs.getqr.com/pt/api/guides/qr-types.md)

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

> [card] [Regras de acesso](https://docs.getqr.com/pt/api/guides/access-rules.md)

> [card] [Estatísticas](https://docs.getqr.com/pt/api/endpoints/analytics.md)


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