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 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
`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}`	Eliminar um relatório agendado

Cabeçalhos

string

obrigatório

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

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.

string

obrigatório

all, selected ou single. Consulte Âmbito.

string

obrigatório

daily, weekly ou monthly. Consulte Período.

string

obrigatório

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

string[]

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

string

padrão:"en"

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

string

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

object[]

Uma entrada por código QR.

Mostrar properties

string

ID do código QR.

string

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

string

Tipo de código QR, por exemplo website.

integer

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

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.

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 respetivo fuso horário.

string

ID do relatório agendado.

string | null

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

string

daily, weekly ou monthly.

string

all, selected ou single.

string[] | null

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

null

Sempre null. Reservado.

boolean

Se é anexado um PDF ao e-mail.

string

active ou paused.

string

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

string

Idioma do e-mail e do PDF.

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.

string | null

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

integer

padrão:"1"

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

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.

string

obrigatório

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

string

obrigatório

all, selected ou single. Consulte Âmbito.

string

obrigatório

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.

string

obrigatório

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.

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.

string

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

boolean

padrão:"false"

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

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

string

obrigatório

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

string

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

string

Etiqueta, até 40 caracteres.

string

daily, weekly ou monthly.

string

all, selected ou single.

string[]

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

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

Eliminar um relatório agendado

DELETE /api/v1/reports/schedules/{id} Elimina o agendamento e para todos os e-mails seguintes.

A eliminação de um relatório agendado não pode ser anulada.

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

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.

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.

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.

Faltam no relatório as leituras de hoje

Os relatórios abrangem apenas o último período concluído. Use Estatísticas para ver os números em tempo real.

API

Cabeçalhos

Âmbito

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

Eliminar um relatório agendado

Problemas comuns

Próximos passos

Estatísticas

Relatórios agendados na aplicação

Ler os seus relatórios

Erros

​Cabeçalhos

​Âmbito

​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

​Eliminar um relatório agendado

​Problemas comuns

​Próximos passos

Estatísticas

Relatórios agendados na aplicação

Ler os seus relatórios

Erros

Cabeçalhos

Âmbito

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

Eliminar um relatório agendado

Problemas comuns

Próximos passos