Relatórios

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"
  }'

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

{
  "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"
    }
  ]
}

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"
  }'

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

{
  "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"
    }
  ]
}

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
`GET`	`/api/v1/reports/schedules`	Listar relatórios agendados
`POST`	`/api/v1/reports/schedules`	Agendar um relatório
`PATCH`	`/api/v1/reports/schedules/{id}`	Atualizar um relatório agendado
`DELETE`	`/api/v1/reports/schedules/{id}`	Excluir um relatório agendado

Cabeçalhos

string

obrigatório

Bearer seguido da sua chave de API. Veja Autenticação.

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.

string

obrigatório

all, selected ou single. Veja Escopo.

string

obrigatório

daily, weekly ou monthly. Veja Período.

string

obrigatório

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

string[]

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

string

padrão:"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.

string

padrão:"en"

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

string

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

Resposta JSON

string

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

string

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

object[]

Uma entrada por QR code.

Mostrar properties

string

ID do QR code.

string

Título do QR code, ou Untitled QR.

string

Tipo do QR code, por exemplo website.

integer

Total de leituras no período.

integer

Leituras únicas no período.

string

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

string

Dispositivo com mais leituras, ou —.

string

Sistema operacional com mais leituras, ou —.

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.

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"
  }'

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

{
  "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.

string

ID do relatório agendado.

string | null

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

string

daily, weekly ou monthly.

string

all, selected ou single.

string[] | null

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

null

Sempre null. Reservado.

boolean

Se um PDF é anexado ao e-mail.

string

active ou paused.

string

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

string

Idioma do e-mail e do PDF.

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.

string | null

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

string

Data de criação, ISO 8601.

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.

integer

padrão:"1"

Página a retornar, 1 ou mais.

integer

padrão:"100"

Resultados por página, de 1 a 100.

curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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.

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.

string

obrigatório

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

string

obrigatório

all, selected ou single. Veja Escopo.

string

obrigatório

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.

string

obrigatório

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.

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.

string

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

boolean

padrão:"false"

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

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"
  }'

{
  "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.

string

obrigatório

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

string

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

string

Nome, até 40 caracteres.

string

daily, weekly ou monthly.

string

all, selected ou single.

string[]

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

boolean

Anexa um PDF ao e-mail.

string

Fuso horário IANA.

string

Idioma do e-mail e do PDF.

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"
  }'

{
  "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.

A exclusão de um relatório agendado não pode ser desfeita.

string

obrigatório

ID do relatório agendado.

curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }

Problemas comuns

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.

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.

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.

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.

O relatório não tem as leituras de hoje

Os relatórios abrangem apenas o último período concluído. Use Análises para números em tempo real.

API

Cabeçalhos

Escopo

Período

Exportar um relatório

Resposta JSON

Respostas CSV e PDF

O objeto de relatório agendado

Listar relatórios agendados

Agendar um relatório

Atualizar um relatório agendado

Excluir um relatório agendado

Problemas comuns

Próximos passos

Análises

Relatórios agendados no app

Leia seus relatórios

Erros

​Cabeçalhos

​Escopo

​Período

​Exportar um relatório

​Resposta JSON

​Respostas CSV e PDF

​O objeto de relatório agendado

​Listar relatórios agendados

​Agendar um relatório

​Atualizar um relatório agendado

​Excluir um relatório agendado

​Problemas comuns

​Próximos passos

Análises

Relatórios agendados no app

Leia seus relatórios

Erros

Cabeçalhos

Escopo

Período

Exportar um relatório

Resposta JSON

Respostas CSV e PDF

O objeto de relatório agendado

Listar relatórios agendados

Agendar um relatório

Atualizar um relatório agendado

Excluir um relatório agendado

Problemas comuns

Próximos passos