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

# Análises

> Estatísticas de leituras de um QR code ou do workspace inteiro.

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

Obtenha totais de leituras e detalhamentos por país, dispositivo, navegador e mais, para um único QR code ou para todo o workspace.

| Método | Caminho | Descrição |
| - | - | - |
| `GET` | `/api/v1/qrs/{qrId}/analytics` | [Obter as análises de um QR code](#obter-as-análises-de-um-qr-code) |
| `GET` | `/api/v1/analytics` | [Obter as análises do workspace](#obter-as-análises-do-workspace) |

Para um resumo pronto por QR code, veja [Relatórios](https://docs.getqr.com/pt-br/api/endpoints/reports.md).

## O que os números significam

* **Leituras.** Toda contagem vem no campo `clicks`. Uma leitura é contada cada vez que alguém abre o link curto do QR code.
* **Leituras únicas.** Com `unique=true`, cada visitante é contado uma vez no intervalo de datas.
* **Escopo.** Os números vêm do link curto do QR code. Um QR code sem link curto não tem leituras para contar.
* **Histórico.** As análises não podem ser zeradas pela API. Excluir um QR code não apaga o histórico de leituras dele.

## Cabeçalhos

**Authorization** `string` *required*

`Bearer` seguido da sua chave de API. Veja [Autenticação](https://docs.getqr.com/pt-br/api/authentication.md).

## Parâmetros de consulta

Os dois endpoints aceitam estes parâmetros. Todos são opcionais.

**groupBy** `string` (default: count)

Dimensão do detalhamento. `count` retorna o total. Veja [Detalhamentos](#detalhamentos) para todos os valores e o formato da resposta de cada um.

**interval** `string` (default: 30d)

Intervalo de datas predefinido: `24h`, `7d`, `30d`, `90d`, `1y`, `mtd`, `qtd`, `ytd` ou `all`. Veja [Intervalos de datas](#intervalos-de-datas). Ignorado quando você envia `start`.

**start** `string`

Início de um intervalo personalizado, ISO 8601, por exemplo `2026-08-01` ou `2026-08-01T00:00:00Z`. Tem prioridade sobre `interval`. Precisa ser anterior a `end`.

**end** `string`

Fim de um intervalo personalizado, ISO 8601. Padrão: o fim do dia de hoje. Usado junto com `start` ou `interval=all`, e ignorado com os outros intervalos.

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

Fuso horário IANA usado para alinhar os períodos de `timeseries`, por exemplo `America/New_York`. Um fuso horário desconhecido retorna `422`.

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

`true` conta leituras únicas em vez do total de leituras.

Você também pode enviar [filtros de dimensão](#filtros-de-dimensão).

## Intervalos de datas

| `interval` | Abrange | Períodos de `timeseries` |
| - | - | - |
| `24h` | As últimas 24 horas | Horas |
| `7d` | Os últimos 7 dias, incluindo hoje | Dias |
| `30d` | Os últimos 30 dias, incluindo hoje | Dias |
| `90d` | Os últimos 90 dias, incluindo hoje | Dias |
| `1y` | Os últimos 365 dias, incluindo hoje | Meses |
| `mtd` | Do início do mês até hoje | Dias |
| `qtd` | Do início do trimestre até hoje | Dias |
| `ytd` | Do início do ano até hoje | Dias, ou meses após 180 dias |
| `all` | Desde a criação do seu workspace | Dias, ou meses após 180 dias |

Para um intervalo personalizado, envie `start` e, opcionalmente, `end`. Intervalos de até 2 dias usam períodos por hora, intervalos acima de 180 dias usam períodos mensais, e todos os demais usam períodos diários.

## Filtros de dimensão

Restrinja os resultados às leituras que correspondem a um filtro. Filtros diferentes são combinados com AND. Quando um filtro aceita vários valores, separe-os com vírgulas: os valores são combinados com OR.

| Filtro | Valor | Vários valores |
| - | - | - |
| `country` | Código de país ISO 3166-1 alpha-2, por exemplo `US` | Sim |
| `region` | Código de região ISO 3166-2, por exemplo `US-CA` | Sim |
| `city` | Nome da cidade, por exemplo `New York` | Sim |
| `continent` | `AF`, `AN`, `AS`, `EU`, `NA`, `OC` ou `SA` | Sim |
| `device` | Tipo de dispositivo, por exemplo `Mobile` ou `Desktop` | Sim |
| `browser` | Nome do navegador, por exemplo `Chrome` | Sim |
| `os` | Sistema operacional, por exemplo `iOS` ou `Windows` | Sim |
| `url` | URL de destino | Sim |
| `referer` | Origem do acesso (referrer), por exemplo `google.com` | Não |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | Valor UTM, até 190 caracteres | Não |

Um código de país ou de continente desconhecido retorna `422`. Os nomes de dispositivo, navegador e sistema operacional são comparados com a primeira letra maiúscula, então `mobile` funciona como `Mobile`.

Por exemplo, leituras dos EUA ou do Canadá em dispositivos móveis: `?country=US,CA&device=Mobile`.

## Detalhamentos

`count` retorna um objeto. Todos os outros valores retornam um array, ordenado por `clicks` do maior para o menor (`timeseries` é ordenado por tempo).

| `groupBy` | Cada item contém |
| - | - |
| `count` | `clicks` (um objeto, não um array) |
| `timeseries` | `start` (início do período), `clicks` |
| `continents` | `continent`, `clicks` |
| `regions` | `region`, `country`, `clicks` |
| `countries` | `country`, `city` (sempre `*`), `clicks` |
| `cities` | `city`, `country`, `clicks` |
| `devices` | `device`, `clicks` |
| `browsers` | `browser`, `clicks` |
| `os` | `os`, `clicks` |
| `triggers` | `trigger` (`qr` ou `link`), `clicks` |
| `referers` | `referer` (`(direct)` quando desconhecido), `clicks` |
| `referer_urls` | `refererUrl` (`(direct)` quando desconhecido), `clicks` |
| `top_links` | `id`, `domain`, `key`, `shortLink`, `url`, `createdAt`, `qr` (`id`, `qrType`, `title`), `clicks` |
| `top_urls` | `url`, `clicks` |
| `top_types` | `qr_type`, `clicks` |
| `utm_sources`, `utm_mediums`, `utm_campaigns`, `utm_terms`, `utm_contents` | O valor UTM (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term` ou `utm_content`), `clicks` |

Um `groupBy` desconhecido retorna `422` com a lista de valores válidos.

Resposta quando `groupBy=count`:

```json theme={null}
{ "clicks": 142 }
```

Resposta quando `groupBy=countries`:

```json theme={null}
[
  { "country": "US", "city": "*", "clicks": 87 },
  { "country": "DE", "city": "*", "clicks": 31 },
  { "country": "GB", "city": "*", "clicks": 24 }
]
```

## Obter as análises de um QR code

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

Retorna as estatísticas de leituras de um QR code, restritas ao link curto dele. Aceita os [parâmetros de consulta](#parâmetros-de-consulta) e os [filtros de dimensão](#filtros-de-dimensão) acima.

**qrId** `string` *required*

ID do QR code. Pegue-o na resposta da listagem ou da criação de [QR codes](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md).

```bash Total scans, last 30 days theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Unique scans theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=count&interval=30d&unique=true" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash By country, last 7 days theme={null}
curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/analytics?groupBy=countries&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "clicks": 142
}
```

## Obter as análises do workspace

`GET /api/v1/analytics`

Retorna as estatísticas de leituras de todos os QR codes do seu workspace. Aceita os [parâmetros de consulta](#parâmetros-de-consulta) e os [filtros de dimensão](#filtros-de-dimensão) acima, além destes parâmetros de escopo.

**domain** `string`

Com `key`, restringe os resultados ao link curto com este domínio, por exemplo `getqr.sh`. O domínio precisa pertencer ao seu workspace.

**key** `string`

Slug do link curto, por exemplo `x7Kd2p1`. Use-o junto com `domain`. Os dois estão no [objeto QR code](https://docs.getqr.com/pt-br/api/endpoints/qr-codes.md).

**qrType** `string`

Tipos de QR code a incluir, separados por vírgula: `website`, `pdf`, `image`, `video`, `whatsapp`, `social`, `wifi`, `app`, `feedback`, `vcard`, `sms`, `payment`, `location`, `multilink`, `email` ou `event`. Veja [Tipos de QR](https://docs.getqr.com/pt-br/api/guides/qr-types.md).

```bash Devices, last 7 days theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=7d" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash Devices, website QR codes only theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=devices&interval=30d&qrType=website" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```bash One short link theme={null}
curl "https://getqr.com/api/v1/analytics?groupBy=count&domain=getqr.sh&key=x7Kd2p1" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
[
  { "device": "Mobile", "clicks": 980 },
  { "device": "Desktop", "clicks": 240 }
]
```

## Problemas comuns

> [accordion] 400 "QR has no associated link."
>
> O QR code não tem link curto, então não há leituras para contar.

> [accordion] 404 ao filtrar por domain e key
>
> Não existe no seu workspace um link curto com esse domínio e esse slug. Copie `domain` e `key` do objeto QR code.

> [accordion] 422 em groupBy, interval ou em um filtro
>
> O valor não é suportado. A mensagem de erro informa o parâmetro e lista os valores válidos.

> [accordion] Os números não batem com o painel
>
> Verifique se você usa o mesmo intervalo de datas e o mesmo fuso horário, e se está contando leituras únicas (`unique=true`) ou o total de leituras.

## Próximos passos

> [card] [Relatórios](https://docs.getqr.com/pt-br/api/endpoints/reports.md)

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

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

> [card] [Limites de requisições](https://docs.getqr.com/pt-br/api/rate-limits.md)


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