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

# Relatórios

> Exporte um relatório de leituras avulso ou agende o envio recorrente de relatórios por e-mail.

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

Os relatórios resumem as leituras por QR code de um dia, uma semana ou um mês já concluídos. Exporte um na hora ou agende um relatório enviado por e-mail regularmente.

| Método | Caminho | Descrição |
| - | - | - |
| `POST` | `/api/v1/reports` | [Exportar um relatório](#exportar-um-relatório) |
| `GET` | `/api/v1/reports/schedules` | [Listar relatórios agendados](#listar-relatórios-agendados) |
| `POST` | `/api/v1/reports/schedules` | [Agendar um relatório](#agendar-um-relatório) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Atualizar um relatório agendado](#atualizar-um-relatório-agendado) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Excluir um relatório agendado](#excluir-um-relatório-agendado) |

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

`application/json`. Obrigatório em requisições `POST` e `PATCH`.

## Escopo

Relatórios avulsos e agendados recebem um `scope`:

| `scope` | Abrange | `qrIds` |
| - | - | - |
| `all` | Os QR codes do seu workspace | Omita |
| `selected` | Um conjunto escolhido de QR codes | Um ou mais IDs |
| `single` | Exatamente um QR code | Exatamente um ID |

Um relatório lista no máximo 50 QR codes. Com `all`, são os QR codes ativos criados mais recentemente; os códigos pausados ficam de fora. Com `selected` e `single`, os códigos pausados são incluídos. QR codes sem link curto não têm leituras e são ignorados.

## Período

O período é sempre o último já concluído, então um relatório nunca inclui os dados parciais de hoje. Os limites dele são a meia-noite no fuso horário do relatório.

| `period` ou `frequency` | Abrange |
| - | - |
| `daily` | O dia anterior |
| `weekly` | A semana anterior, de segunda a domingo |
| `monthly` | O mês-calendário anterior |

## Exportar um relatório

`POST /api/v1/reports`

Gera um relatório do último período concluído e o retorna na resposta.

**scope** `string` *required*

`all`, `selected` ou `single`. Veja [Escopo](#escopo).

**period** `string` *required*

`daily`, `weekly` ou `monthly`. Veja [Período](#período).

**format** `string` *required*

`json` retorna o relatório no corpo da resposta. `csv` e `pdf` retornam um arquivo para download.

**qrIds** `string[]`

QR codes a incluir. Obrigatório para `selected` (um ou mais IDs) e `single` (exatamente um ID). Omita para `all`.

**timezone** `string` (default: UTC)

Fuso horário IANA ao qual os limites do período são alinhados, por exemplo `America/New_York`. Um fuso horário desconhecido retorna `422`.

**locale** `string` (default: en)

Idioma do PDF, por exemplo `en` ou `de`. Um valor não suportado volta para o inglês. Ignorado por `csv` e `json`.

**name** `string`

Título exibido no PDF, até 40 caracteres. Ignorado por `csv` e `json`.

### Resposta JSON

**periodStart** `string`

Primeiro dia do período, `YYYY-MM-DD`.

**periodEnd** `string`

Primeiro dia após o período, `YYYY-MM-DD`. O período termina à meia-noite do início desse dia.

**qrs** `object[]`

Uma entrada por QR code.

**properties**

**qrId** `string`

ID do QR code.

**name** `string`

Título do QR code, ou `Untitled QR`.

**type** `string`

Tipo do QR code, por exemplo `website`.

**totalScans** `integer`

Total de leituras no período.

**uniqueScans** `integer`

Leituras únicas no período.

**topGeography** `string`

Código do país com mais leituras, ou `—` sem leituras.

**topDevice** `string`

Dispositivo com mais leituras, ou `—`.

**topOs** `string`

Sistema operacional com mais leituras, ou `—`.

**topBrowser** `string`

Navegador com mais leituras, ou `—`.

### Respostas CSV e PDF

O corpo é o arquivo. `Content-Disposition` o nomeia de acordo com o período, por exemplo `report-2026-08-10_2026-08-17.csv`. O CSV tem uma linha por QR code com as colunas `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` e `Top browser`.

```bash JSON theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'
```

```bash PDF theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf
```

```json 200 theme={null}
{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}
```

## O objeto de relatório agendado

Um relatório agendado é enviado por e-mail para a conta que o criou, à meia-noite no fuso horário dele.

**id** `string`

ID do relatório agendado.

**name** `string | null`

Nome exibido no assunto do e-mail e no painel.

**frequency** `string`

`daily`, `weekly` ou `monthly`.

**scope** `string`

`all`, `selected` ou `single`.

**qrIds** `string[] | null`

QR codes que o relatório abrange com os escopos `selected` e `single`. `null` quando nenhum ID foi enviado.

**filters** `null`

Sempre `null`. Reservado.

**includePdf** `boolean`

Se um PDF é anexado ao e-mail.

**status** `string`

`active` ou `paused`.

**timezone** `string`

Fuso horário IANA ao qual o horário de envio e o período são alinhados.

**locale** `string`

Idioma do e-mail e do PDF.

**nextRunAt** `string`

Quando o próximo e-mail está previsto, ISO 8601: a próxima meia-noite (`daily`), a próxima segunda-feira (`weekly`) ou o dia 1º do próximo mês (`monthly`), no fuso horário do relatório.

**lastRunAt** `string | null`

Quando o último e-mail foi enviado, ISO 8601.

**createdAt** `string`

Data de criação, ISO 8601.

**updatedAt** `string`

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

## Listar relatórios agendados

`GET /api/v1/reports/schedules`

Retorna os relatórios agendados do seu workspace, incluindo os criados por outros membros, dos mais novos para os mais antigos. A lista é paginada: veja [Paginação](https://docs.getqr.com/pt-br/api/introduction.md#paginação).

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

Página a retornar, 1 ou mais.

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

Resultados por página, de 1 a 100.

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

```json 200 theme={null}
{
  "data": [
    {
      "id": "clx8f2k9a0001qk0c8vhd3xyz",
      "name": "Weekly campaign digest",
      "frequency": "weekly",
      "scope": "selected",
      "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr", "clw3n7t1x0004ab0d9rzu2wfh"],
      "filters": null,
      "includePdf": true,
      "status": "active",
      "timezone": "America/New_York",
      "locale": "en",
      "nextRunAt": "2026-08-10T04:00:00.000Z",
      "lastRunAt": "2026-08-03T04:00:12.000Z",
      "createdAt": "2026-07-01T12:34:56.000Z",
      "updatedAt": "2026-07-28T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Agendar um relatório

`POST /api/v1/reports/schedules`

Cria um relatório enviado por e-mail regularmente. `nextRunAt` é calculado a partir da frequência e do fuso horário.

> [!NOTE]
>
> Um QR code só pode pertencer a um relatório agendado por frequência. Um agendamento sobreposto retorna `409 conflict`.

Um relatório com o escopo `all` se sobrepõe a todos os outros relatórios da mesma frequência. Relatórios pausados também contam.

**frequency** `string` *required*

Com que frequência o relatório é enviado: `daily`, `weekly` ou `monthly`. Também define o período abrangido. Veja [Período](#período).

**scope** `string` *required*

`all`, `selected` ou `single`. Veja [Escopo](#escopo).

**timezone** `string` *required*

Fuso horário IANA ao qual o horário de envio e o período são alinhados, por exemplo `America/New_York`. Um fuso horário desconhecido retorna `422`.

**locale** `string` *required*

Idioma do e-mail e do PDF, por exemplo `en` ou `de`. Um valor não suportado volta para o inglês. PDFs em `zh`, `ja`, `ko` e `ar` são gerados em inglês.

**qrIds** `string[]`

QR codes a incluir. Obrigatório para `selected` (um ou mais IDs) e `single` (exatamente um ID). Todo ID precisa ser de um QR code do seu workspace, ou a requisição retorna `404`.

**name** `string`

Nome exibido no assunto do e-mail e no painel, até 40 caracteres.

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

Anexa uma versão em PDF do relatório ao e-mail.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/reports/schedules" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly campaign digest",
    "frequency": "weekly",
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "includePdf": true,
    "timezone": "America/New_York",
    "locale": "en"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Weekly campaign digest",
  "frequency": "weekly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-08-10T04:00:00.000Z",
  "lastRunAt": null,
  "createdAt": "2026-08-03T12:34:56.000Z",
  "updatedAt": "2026-08-03T12:34:56.000Z"
}
```

## Atualizar um relatório agendado

`PATCH /api/v1/reports/schedules/{id}`

Altera um relatório agendado, ou o pausa e o retoma. Envie apenas os campos que você quer alterar, pelo menos um. Alterar a frequência ou o fuso horário, ou retomar um relatório pausado, recalcula `nextRunAt`. A regra de um relatório por frequência continua valendo, então uma alteração sobreposta retorna `409`.

**id** `string` *required*

ID do relatório agendado. Pegue-o na resposta da listagem ou da criação.

**status** `string`

`paused` interrompe os e-mails sem excluir o agendamento. `active` os retoma.

**name** `string`

Nome, até 40 caracteres.

**frequency** `string`

`daily`, `weekly` ou `monthly`.

**scope** `string`

`all`, `selected` ou `single`.

**qrIds** `string[]`

QR codes a incluir. Todo ID precisa ser de um QR code do seu workspace.

**includePdf** `boolean`

Anexa um PDF ao e-mail.

**timezone** `string`

Fuso horário IANA.

**locale** `string`

Idioma do e-mail e do PDF.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly campaign digest",
    "frequency": "monthly",
    "status": "active"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Monthly campaign digest",
  "frequency": "monthly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-09-01T04:00:00.000Z",
  "lastRunAt": "2026-08-03T04:00:12.000Z",
  "createdAt": "2026-07-01T12:34:56.000Z",
  "updatedAt": "2026-08-05T10:15:00.000Z"
}
```

## Excluir um relatório agendado

`DELETE /api/v1/reports/schedules/{id}`

Exclui o agendamento e interrompe todos os próximos e-mails.

> [!WARNING]
>
> A exclusão de um relatório agendado não pode ser desfeita.

**id** `string` *required*

ID do relatório agendado.

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

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

## Problemas comuns

> [accordion] 404 ao exportar um relatório
>
> Com o escopo `selected` ou `single`, nenhum dos `qrIds` corresponde a um QR code com link curto no seu workspace. Verifique os IDs.

> [accordion] 404 "QR not found." ao agendar um relatório
>
> Um dos `qrIds` não é um QR code do seu workspace, ou foi excluído. Verifique os IDs com [Listar QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md).

> [accordion] 409 ao agendar um relatório
>
> Um dos QR codes já pertence a um relatório agendado com a mesma frequência, ou um relatório dessa frequência usa o escopo `all`. Edite ou exclua esse relatório, ou escolha outra frequência.

> [accordion] 404 "Scheduled report not found."
>
> O `id` não corresponde a um relatório agendado do seu workspace. Pegue-o em [Listar relatórios agendados](#listar-relatórios-agendados).

> [accordion] O relatório não tem as leituras de hoje
>
> Os relatórios abrangem apenas o último período concluído. Use [Análises](https://docs.getqr.com/pt-br/api/endpoints/analytics.md) para números em tempo real.

## Próximos passos

> [card] [Análises](https://docs.getqr.com/pt-br/api/endpoints/analytics.md)

> [card] [Relatórios agendados no app](https://docs.getqr.com/pt-br/analytics/scheduled-reports.md)

> [card] [Leia seus relatórios](https://docs.getqr.com/pt-br/analytics/reading-reports.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.