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

# Introdução à API

> Faça a gestão de códigos QR, modelos, estatísticas e relatórios a partir do seu próprio código.

> [!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.

A API do GetQR é uma API REST para aquilo que faz no painel: criar e atualizar códigos QR, transferir as respetivas imagens, consultar as estatísticas de leituras e exportar relatórios. Autentique-se com a chave de API da sua conta e chame os endpoints versionados em `/api/v1`.

## O que pode fazer

> [card] [Códigos QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md)
>
> Crie, liste, atualize, coloque em pausa, duplique, elimine e transfira códigos QR.

> [card] [Estatísticas](https://docs.getqr.com/pt/api/endpoints/analytics.md)
>
> Totais e discriminações de leituras de um código QR ou de todo o espaço de trabalho.

> [card] [Relatórios](https://docs.getqr.com/pt/api/endpoints/reports.md)
>
> Exporte um relatório pontual ou agende relatórios periódicos por e-mail.

> [card] [Modelos](https://docs.getqr.com/pt/api/endpoints/templates.md)
>
> Guarde designs e aplique-os a novos códigos QR.

> [card] [Criação de QR em massa](https://docs.getqr.com/pt/api/endpoints/bulk-qr-creations.md)
>
> Crie até 100 códigos QR de uma só vez a partir de JSON ou de um ficheiro CSV.

> [card] [Ficheiros](https://docs.getqr.com/pt/api/endpoints/files.md)
>
> Carregue PDF, imagens, vídeos e logótipos para os seus códigos QR.

> [card] [Estado](https://docs.getqr.com/pt/api/endpoints/health.md)
>
> Verifique se a API está a funcionar. Não precisa de chave de API.

## Guias

> [card] [Tipos de QR](https://docs.getqr.com/pt/api/guides/qr-types.md)
>
> O formato dos dados de cada um dos 16 tipos de QR.

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

> [card] [Regras de acesso](https://docs.getqr.com/pt/api/guides/access-rules.md)
>
> Agendamentos, limites de leituras, palavras-passe, pausa e eliminação.

## URL base

Todos os endpoints estão num único URL base:

```text theme={null}
https://getqr.com/api/v1
```

## Versões

A versão da API faz parte do caminho: todos os endpoints estão em `/api/v1/`.

* As alterações incompatíveis saem com um novo prefixo de versão, como `/api/v2/`, e `/api/v1/` continua a funcionar.
* As alterações compatíveis, como novos campos opcionais ou novos endpoints, podem surgir dentro da v1. Ignore os campos da resposta que o seu código não reconheça.

## Início rápido

**1. Obtenha a sua chave de API**

Gere ou mostre a sua chave nas definições da conta. Consulte [Autenticação](https://docs.getqr.com/pt/api/authentication.md).

**2. Verifique se a API está acessível**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

A resposta é `{ "status": "ok", "version": "v1" }`.

**3. Crie o seu primeiro código QR**

```bash 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: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

A API responde `201` com o novo código QR, incluindo o respetivo `id` e `shortLink`.

**4. Transfira a imagem**

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

## Pedidos e respostas

* **Formato.** Envie o corpo dos pedidos em JSON com `Content-Type: application/json`. A exceção é o carregamento de CSV da [criação em massa](https://docs.getqr.com/pt/api/endpoints/bulk-qr-creations.md), que usa `multipart/form-data`.
* **Respostas.** As respostas são em JSON. As transferências, como as imagens de QR e os arquivos ZIP da criação em massa, devolvem o próprio ficheiro.
* **Datas.** As datas são strings ISO 8601 em UTC, por exemplo `2026-08-01T10:00:00.000Z`.
* **Parâmetros de consulta.** Os parâmetros booleanos aceitam as strings `true` ou `false`.
* **Atualizações parciais.** Os endpoints `PATCH` só alteram os campos que enviar.
* **Segredos.** As respostas nunca incluem palavras-passe nem identificadores internos. Um código QR protegido por palavra-passe indica apenas `passwordProtected: true`.
* **Espaço de trabalho.** Cada pedido é executado no espaço de trabalho a que pertence a sua chave de API. Não indica nenhum ID de espaço de trabalho. Consulte [Acesso e funções](https://docs.getqr.com/pt/api/authentication.md#acesso-e-funções).
* **Erros.** Os pedidos falhados devolvem um objeto `error` com um `code` estável. Consulte [Erros](https://docs.getqr.com/pt/api/errors.md).

## Paginação

Os endpoints de listagem (códigos QR, modelos e relatórios agendados) aceitam dois parâmetros de consulta:

| Parâmetro | Descrição |
| - | - |
| `page` | Página a devolver. Por predefinição, `1`. |
| `pageSize` | Resultados por página, até `100`. Por predefinição, `100`. |

Respondem com um array `data` e um objeto `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Campo | Descrição |
| - | - |
| `page` | A página que recebeu. |
| `pageSize` | O tamanho de página que recebeu. |
| `total` | Número de resultados em todas as páginas. |
| `hasMore` | `true` enquanto houver mais uma página. |

Peça a página seguinte enquanto `hasMore` for `true`. Um `pageSize` superior a `100` devolve [`422`](https://docs.getqr.com/pt/api/errors#erros-de-validação).

## Idempotência

Um erro de rede pode deixá-lo sem saber se um pedido chegou ao destino. Para repetir [Criar um código QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md#criar-um-código-qr) em segurança, envie um cabeçalho `Idempotency-Key` com um valor único à sua escolha:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* 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.
* O cabeçalho de resposta `x-idempotent-replay` é `true` numa resposta repetida e `false` numa nova.
* Se o primeiro pedido com essa chave ainda estiver em curso, a API responde `409 conflict`. Repita quando terminar.
* Se reutilizar uma chave com outro corpo de pedido, a resposta é `422 unprocessable_entity`.
* Sem o cabeçalho, um corpo de pedido idêntico enviado no espaço de 30 segundos é tratado como duplicado.

A criação em massa usa, em vez disso, um campo `idempotencyKey` no corpo do pedido. Consulte [Criação de QR em massa](https://docs.getqr.com/pt/api/endpoints/bulk-qr-creations.md).

## Limites de pedidos

Cada chave de API pode enviar até 600 pedidos por minuto. Consulte [Limites de pedidos](https://docs.getqr.com/pt/api/rate-limits.md).

## Brevemente

Os pacotes prontos para impressão estão previstos para uma versão futura.

## Próximos passos

> [card] [Autenticação](https://docs.getqr.com/pt/api/authentication.md)

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


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