> ## 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 pontual ou agende relatórios periódicos por e-mail.

> [!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 relatórios resumem as leituras por código QR de um dia, de uma semana ou de um mês já concluídos. Exporte um de imediato ou agende um relatório enviado por e-mail com regularidade.

| 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}` | [Eliminar um relatório agendado](#eliminar-um-relatório-agendado) |

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

`application/json`. Obrigatório nos pedidos `POST` e `PATCH`.

## Âmbito

Tanto os relatórios pontuais como os agendados aceitam um `scope`:

| `scope` | Abrange | `qrIds` |
| - | - | - |
| `all` | Os códigos QR do seu espaço de trabalho | Omita |
| `selected` | Um conjunto escolhido de códigos QR | Um ou mais IDs |
| `single` | Exatamente um código QR | Exatamente um ID |

Um relatório inclui no máximo 50 códigos QR. Com `all`, são os códigos QR ativos criados mais recentemente; os códigos em pausa ficam de fora. Com `selected` e `single`, os códigos em pausa são incluídos. Os códigos QR sem ligação curta não têm leituras e são ignorados.

## Período

O período é sempre o último já concluído, pelo que um relatório nunca inclui os dados parciais de hoje. Os limites do período 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 civil anterior |

## Exportar um relatório

`POST /api/v1/reports`

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

**scope** `string` *required*

`all`, `selected` ou `single`. Consulte [Âmbito](#âmbito).

**period** `string` *required*

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

**format** `string` *required*

`json` devolve o relatório no corpo da resposta. `csv` e `pdf` devolvem um ficheiro para transferir.

**qrIds** `string[]`

Códigos QR a abranger. Obrigatório para `selected` (um ou mais IDs) e `single` (exatamente um ID). Omita-o em `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 devolve `422`.

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

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

**name** `string`

Título apresentado 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 deste dia.

**qrs** `object[]`

Uma entrada por código QR.

**properties**

**qrId** `string`

ID do código QR.

**name** `string`

Título do código QR, ou `Untitled QR`.

**type** `string`

Tipo de código QR, por exemplo `website`.

**totalScans** `integer`

Leituras totais 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 operativo com mais leituras, ou `—`.

**topBrowser** `string`

Navegador com mais leituras, ou `—`.

### Respostas CSV e PDF

O corpo é o ficheiro. `Content-Disposition` dá-lhe o nome do período, por exemplo `report-2026-08-10_2026-08-17.csv`. O CSV tem uma linha por código QR 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 respetivo fuso horário.

**id** `string`

ID do relatório agendado.

**name** `string | null`

Etiqueta apresentada no assunto do e-mail e no painel.

**frequency** `string`

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

**scope** `string`

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

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

Códigos QR que o relatório abrange com os âmbitos `selected` e `single`. `null` quando não foram enviados IDs.

**filters** `null`

Sempre `null`. Reservado.

**includePdf** `boolean`

Se é anexado um PDF ao e-mail.

**status** `string`

`active` ou `paused`.

**timezone** `string`

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

**locale** `string`

Idioma do e-mail e do PDF.

**nextRunAt** `string`

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

**lastRunAt** `string | null`

Quando foi enviado o último e-mail, 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`

Devolve os relatórios agendados do seu espaço de trabalho, incluindo os criados por outros membros, do mais recente para o mais antigo. A lista é paginada: consulte [Paginação](https://docs.getqr.com/pt/api/introduction.md#paginação).

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

Página a devolver, 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 com regularidade. `nextRunAt` é calculado a partir da frequência e do fuso horário.

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

Um relatório com o âmbito `all` sobrepõe-se a todos os outros relatórios da mesma frequência. Os relatórios em pausa também contam.

**frequency** `string` *required*

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

**scope** `string` *required*

`all`, `selected` ou `single`. Consulte [Âmbito](#âmbito).

**timezone** `string` *required*

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

**locale** `string` *required*

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

**qrIds** `string[]`

Códigos QR a abranger. Obrigatório para `selected` (um ou mais IDs) e `single` (exatamente um ID). Cada ID tem de ser um código QR do seu espaço de trabalho, caso contrário o pedido devolve `404`.

**name** `string`

Etiqueta apresentada no assunto do e-mail e no painel, até 40 caracteres.

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

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

```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 coloca-o em pausa e retoma-o. Envie apenas os campos que pretende alterar, pelo menos um. Alterar a frequência ou o fuso horário, ou retomar um relatório em pausa, recalcula `nextRunAt`. A regra de um relatório por frequência continua a aplicar-se, pelo que uma alteração que crie sobreposição devolve `409`.

**id** `string` *required*

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

**status** `string`

`paused` para os e-mails sem eliminar o agendamento. `active` retoma-os.

**name** `string`

Etiqueta, até 40 caracteres.

**frequency** `string`

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

**scope** `string`

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

**qrIds** `string[]`

Códigos QR a abranger. Cada ID tem de ser um código QR do seu espaço de trabalho.

**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"
}
```

## Eliminar um relatório agendado

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

Elimina o agendamento e para todos os e-mails seguintes.

> [!WARNING]
>
> A eliminação de um relatório agendado não pode ser anulada.

**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 âmbito `selected` ou `single`, nenhum dos `qrIds` corresponde a um código QR com ligação curta no seu espaço de trabalho. Verifique os IDs.

> [accordion] 404 "QR not found." ao agendar um relatório
>
> Um dos `qrIds` não é um código QR do seu espaço de trabalho, ou foi eliminado. Verifique os IDs com [Listar códigos QR](https://docs.getqr.com/pt/api/endpoints/qr-codes.md).

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

> [accordion] 404 "Scheduled report not found."
>
> O `id` não corresponde a nenhum relatório agendado do seu espaço de trabalho. Obtenha-o em [Listar relatórios agendados](#listar-relatórios-agendados).

> [accordion] Faltam no relatório as leituras de hoje
>
> Os relatórios abrangem apenas o último período concluído. Use [Estatísticas](https://docs.getqr.com/pt/api/endpoints/analytics.md) para ver os números em tempo real.

## Próximos passos

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

> [card] [Relatórios agendados na aplicação](https://docs.getqr.com/pt/analytics/scheduled-reports.md)

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