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

> Gerencie QR codes, templates, análises e relatórios a partir do seu próprio código.

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

A API do GetQR é uma API REST para o que você faz no painel: criar e atualizar QR codes, baixar as imagens deles, ler as análises 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 você pode fazer

> [card] [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md)
>
> Crie, liste, atualize, pause, duplique, exclua e baixe QR codes.

> [card] [Análises](https://docs.getqr.com/pt-br/api/endpoints/analytics.md)
>
> Totais e detalhamentos de leituras de um QR code ou do workspace inteiro.

> [card] [Relatórios](https://docs.getqr.com/pt-br/api/endpoints/reports.md)
>
> Exporte um relatório avulso ou agende o envio recorrente de relatórios por e-mail.

> [card] [Templates](https://docs.getqr.com/pt-br/api/endpoints/templates.md)
>
> Salve designs e aplique-os a novos QR codes.

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

> [card] [Arquivos](https://docs.getqr.com/pt-br/api/endpoints/files.md)
>
> Envie PDFs, imagens, vídeos e logos para os seus QR codes.

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

## Guias

> [card] [Tipos de QR](https://docs.getqr.com/pt-br/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-br/api/guides/customization.md)
>
> Estilos de pontos, cantos, cores, molduras e logos.

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

## URL base

Todos os endpoints ficam sob uma única URL base:

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

## Versionamento

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

* Mudanças incompatíveis saem com um novo prefixo de versão, como `/api/v2/`, e `/api/v1/` continua funcionando.
* Mudanças compatíveis, como novos campos opcionais ou novos endpoints, podem surgir dentro da v1. Ignore os campos da resposta que seu código não reconhecer.

## Início rápido

**1. Obtenha sua chave de API**

Gere ou exiba sua chave nas configurações da conta. Veja [Autenticação](https://docs.getqr.com/pt-br/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 seu primeiro QR code**

```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 QR code, incluindo o `id` e o `shortLink` dele.

**4. Baixe 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
```

## Requisições e respostas

* **Formato.** Envie os corpos das requisições em JSON com `Content-Type: application/json`. A exceção é o upload de CSV da [criação em massa](https://docs.getqr.com/pt-br/api/endpoints/bulk-qr-creations.md), que usa `multipart/form-data`.
* **Respostas.** As respostas são em JSON. Downloads, como imagens de QR e arquivos ZIP em massa, retornam o próprio arquivo.
* **Datas.** As datas são strings ISO 8601 em UTC, por exemplo `2026-08-01T10:00:00.000Z`.
* **Parâmetros de consulta.** Parâmetros booleanos recebem as strings `true` ou `false`.
* **Atualizações parciais.** Endpoints `PATCH` alteram apenas os campos que você envia.
* **Segredos.** As respostas nunca incluem senhas nem identificadores internos. Um QR code protegido por senha informa apenas `passwordProtected: true`.
* **Workspace.** Toda requisição é executada no workspace ao qual a sua chave de API pertence. Você não informa um ID de workspace. Veja [Acesso e funções](https://docs.getqr.com/pt-br/api/authentication.md#acesso-e-funções).
* **Erros.** Requisições com falha retornam um objeto `error` com um `code` estável. Veja [Erros](https://docs.getqr.com/pt-br/api/errors.md).

## Paginação

Os endpoints de listagem (QR codes, templates e relatórios agendados) recebem dois parâmetros de consulta:

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

Eles 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 você recebeu. |
| `pageSize` | O tamanho de página que você recebeu. |
| `total` | Número de resultados em todas as páginas. |
| `hasMore` | `true` enquanto houver outra página. |

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

## Idempotência

Um erro de rede pode deixar você sem saber se uma requisição foi processada. Para repetir [Criar um QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md#criar-um-qr-code) com segurança, envie um cabeçalho `Idempotency-Key` com um valor único da sua escolha:

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

* Repetir a requisição com a mesma chave em até 24 horas retorna a resposta original em vez de criar um segundo QR code.
* O cabeçalho de resposta `x-idempotent-replay` é `true` para uma resposta repetida e `false` para uma nova.
* Se a primeira requisição com essa chave ainda estiver em andamento, a API responde `409 conflict`. Tente de novo quando ela terminar.
* Reutilizar uma chave com um corpo de requisição diferente retorna `422 unprocessable_entity`.
* Sem o cabeçalho, um corpo de requisição idêntico enviado em até 30 segundos é tratado como duplicado.

As criações em massa recebem um campo `idempotencyKey` no corpo da requisição. Veja [Criação de QR codes em massa](https://docs.getqr.com/pt-br/api/endpoints/bulk-qr-creations.md).

## Limites de requisições

Cada chave de API pode enviar até 600 requisições por minuto. Veja [Limites de requisições](https://docs.getqr.com/pt-br/api/rate-limits.md).

## Em breve

Pacotes prontos para impressão estão planejados para uma versão futura.

## Próximos passos

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

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


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