报告 - GetQR Docs

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

GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

报告按二维码汇总某个已结束的日、周或月内的扫描情况。您可以立即导出报告，也可以设置定期通过电子邮件发送的报告。

方法	路径	说明
`POST`	`/api/v1/reports`	导出报告
`GET`	`/api/v1/reports/schedules`	列出定时报告
`POST`	`/api/v1/reports/schedules`	创建定时报告
`PATCH`	`/api/v1/reports/schedules/{id}`	更新定时报告
`DELETE`	`/api/v1/reports/schedules/{id}`	删除定时报告

请求头

string

必填

Bearer 后跟您的 API 密钥。请参阅身份验证。

string

application/json。POST 和 PATCH 请求必须提供。

范围

一次性报告和定时报告都接受 scope：

`scope`	覆盖范围	`qrIds`
`all`	工作区中的二维码	省略
`selected`	选定的一组二维码	一个或多个 ID
`single`	恰好一个二维码	恰好一个 ID

一份报告最多列出 50 个二维码。使用 all 时，列出的是最近创建的启用中二维码，已暂停的二维码不包括在内。使用 selected 和 single 时，已暂停的二维码也会包括在内。没有短链接的二维码没有扫描，会被跳过。

周期

周期始终是最近一个已结束的周期，因此报告绝不会包含今天不完整的数据。周期的边界为报告所用时区的午夜。

`period` 或 `frequency`	覆盖范围
`daily`	前一天
`weekly`	上一周，周一至周日
`monthly`	上一个自然月

导出报告

POST /api/v1/reports 生成最近一个已结束周期的报告，并在响应中返回。

string

必填

all、selected 或 single。请参阅范围。

string

必填

daily、weekly 或 monthly。请参阅周期。

string

必填

json 在响应体中返回报告。csv 和 pdf 返回文件下载。

string[]

要包含的二维码。使用 selected（一个或多个 ID）和 single（恰好一个 ID）时必填。使用 all 时请省略。

string

默认值:"UTC"

周期边界所对齐的 IANA 时区，例如 America/New_York。未知时区会返回 422。

string

默认值:"en"

PDF 的语言，例如 en 或 de。不支持的值会回退为英语。csv 和 json 会忽略此参数。

string

显示在 PDF 上的标题，最多 40 个字符。csv 和 json 会忽略此参数。

JSON 响应

string

周期的第一天，格式为 YYYY-MM-DD。

string

周期结束后的第一天，格式为 YYYY-MM-DD。周期在这一天开始时的午夜结束。

object[]

每个二维码一项。

显示 properties

string

二维码的 ID。

string

二维码的标题，或 Untitled QR。

string

二维码类型，例如 website。

integer

周期内的扫描总数。

integer

周期内的唯一扫描数。

string

扫描次数最多的国家/地区代码；没有扫描时为 —。

string

扫描次数最多的设备，或 —。

string

扫描次数最多的操作系统，或 —。

string

扫描次数最多的浏览器，或 —。

CSV 和 PDF 响应

响应体就是文件本身。Content-Disposition 会以周期命名文件，例如 report-2026-08-10_2026-08-17.csv。CSV 中每个二维码占一行，列为 QR ID、QR name、QR type、Total scans、Unique scans、Top geography、Top device、Top OS 和 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"
    }
  ]
}

定时报告对象

定时报告会在其时区的午夜通过电子邮件发送给创建它的账户。

string

定时报告的 ID。

string | null

显示在邮件主题和控制台中的名称。

string

daily、weekly 或 monthly。

string

all、selected 或 single。

string[] | null

使用 selected 和 single 范围时报告包含的二维码。未发送 ID 时为 null。

null

始终为 null。保留字段。

boolean

邮件是否附带 PDF。

string

active 或 paused。

string

发送时间和周期所对齐的 IANA 时区。

string

邮件和 PDF 的语言。

string

下一封邮件的发送时间，ISO 8601 格式：按报告的时区，为下一个午夜（daily）、下一个周一（weekly）或下个月 1 日（monthly）。

string | null

上一封邮件的发送时间，ISO 8601 格式。

string

创建日期，ISO 8601 格式。

string

最后更新日期，ISO 8601 格式。

列出定时报告

GET /api/v1/reports/schedules 返回工作区中的定时报告（包括其他成员创建的报告），按从新到旧排序。列表支持分页：请参阅分页。

integer

默认值:"1"

要返回的页码，最小为 1。

integer

默认值:"100"

每页结果数，1 到 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 }
}

创建定时报告

POST /api/v1/reports/schedules 创建一份定期通过电子邮件发送的报告。nextRunAt 会根据发送频率和时区计算得出。

对于同一发送频率，一个二维码只能属于一份定时报告。重叠的计划会返回 409 conflict。

范围为 all 的报告与相同频率的其他所有报告都重叠。已暂停的报告同样计算在内。

string

必填

报告的发送频率：daily、weekly 或 monthly。同时决定报告覆盖的周期。请参阅周期。

string

必填

all、selected 或 single。请参阅范围。

string

必填

发送时间和周期所对齐的 IANA 时区，例如 America/New_York。未知时区会返回 422。

string

必填

邮件和 PDF 的语言，例如 en 或 de。不支持的值会回退为英语。zh、ja、ko 和 ar 的 PDF 以英语生成。

string[]

要包含的二维码。使用 selected（一个或多个 ID）和 single（恰好一个 ID）时必填。每个 ID 都必须是您工作区中的二维码，否则请求会返回 404。

string

显示在邮件主题和控制台中的名称，最多 40 个字符。

boolean

默认值:"false"

在邮件中附带报告的 PDF 版本。

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

更新定时报告

PATCH /api/v1/reports/schedules/{id} 更改定时报告，或暂停和恢复报告。只发送您要更改的字段，至少一个。更改发送频率或时区，或者恢复已暂停的报告，都会重新计算 nextRunAt。每种频率一份报告的规则仍然适用，因此造成重叠的更改会返回 409。

string

必填

定时报告的 ID。可从列表或创建接口的响应中获取。

string

paused 会停止发送邮件，但不删除计划。active 会恢复发送。

string

名称，最多 40 个字符。

string

daily、weekly 或 monthly。

string

all、selected 或 single。

string[]

要包含的二维码。每个 ID 都必须是您工作区中的二维码。

boolean

在邮件中附带 PDF。

string

IANA 时区。

string

邮件和 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"
}

删除定时报告

DELETE /api/v1/reports/schedules/{id} 删除计划，并停止之后的所有邮件。

删除定时报告后无法撤销。

string

必填

定时报告的 ID。

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

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

常见问题

导出报告时返回 404

使用 selected 或 single 范围时，qrIds 中没有任何一个与您工作区中带短链接的二维码匹配。请检查这些 ID。

创建定时报告时返回 404 "QR not found."

qrIds 中的某个 ID 不是您工作区中的二维码，或者该二维码已被删除。请通过列出二维码检查这些 ID。

创建定时报告时返回 409

其中某个二维码已属于相同频率的另一份定时报告，或者该频率下有一份报告使用了 all 范围。请编辑或删除那份报告，或选择其他频率。

404 "Scheduled report not found."

该 id 与您工作区中的任何定时报告都不匹配。请从列出定时报告中获取。

报告中缺少今天的扫描

报告只覆盖最近一个已结束的周期。如需实时数据，请使用数据分析。

API

报告

请求头

范围

周期

导出报告

JSON 响应

CSV 和 PDF 响应

定时报告对象

列出定时报告

创建定时报告

更新定时报告

删除定时报告

常见问题

后续步骤

数据分析

应用中的定时报告

阅读报告

错误

​请求头

​范围

​周期

​导出报告

​JSON 响应

​CSV 和 PDF 响应

​定时报告对象

​列出定时报告

​创建定时报告

​更新定时报告

​删除定时报告

​常见问题

​后续步骤

数据分析

应用中的定时报告

阅读报告

错误

请求头

范围

周期

导出报告

JSON 响应

CSV 和 PDF 响应

定时报告对象

列出定时报告

创建定时报告

更新定时报告

删除定时报告

常见问题

后续步骤