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

# 报告

> 导出一次性扫描报告，或设置定期发送的报告邮件。

> [!NOTE]
>
> 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}` | [删除定时报告](#删除定时报告) |

## 请求头

**Authorization** `string` *required*

`Bearer` 后跟您的 API 密钥。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

**Content-Type** `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`

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

**scope** `string` *required*

`all`、`selected` 或 `single`。请参阅[范围](#范围)。

**period** `string` *required*

`daily`、`weekly` 或 `monthly`。请参阅[周期](#周期)。

**format** `string` *required*

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

**qrIds** `string[]`

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

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

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

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

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

**name** `string`

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

### JSON 响应

**periodStart** `string`

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

**periodEnd** `string`

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

**qrs** `object[]`

每个二维码一项。

**properties**

**qrId** `string`

二维码的 ID。

**name** `string`

二维码的标题，或 `Untitled QR`。

**type** `string`

二维码类型，例如 `website`。

**totalScans** `integer`

周期内的扫描总数。

**uniqueScans** `integer`

周期内的唯一扫描数。

**topGeography** `string`

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

**topDevice** `string`

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

**topOs** `string`

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

**topBrowser** `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`。

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

## 定时报告对象

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

**id** `string`

定时报告的 ID。

**name** `string | null`

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

**frequency** `string`

`daily`、`weekly` 或 `monthly`。

**scope** `string`

`all`、`selected` 或 `single`。

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

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

**filters** `null`

始终为 `null`。保留字段。

**includePdf** `boolean`

邮件是否附带 PDF。

**status** `string`

`active` 或 `paused`。

**timezone** `string`

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

**locale** `string`

邮件和 PDF 的语言。

**nextRunAt** `string`

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

**lastRunAt** `string | null`

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

**createdAt** `string`

创建日期，ISO 8601 格式。

**updatedAt** `string`

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

## 列出定时报告

`GET /api/v1/reports/schedules`

返回工作区中的定时报告（包括其他成员创建的报告），按从新到旧排序。列表支持分页：请参阅[分页](https://docs.getqr.com/zh/api/introduction.md#分页)。

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

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

**pageSize** `integer` (default: 100)

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

## 创建定时报告

`POST /api/v1/reports/schedules`

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

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

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

**frequency** `string` *required*

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

**scope** `string` *required*

`all`、`selected` 或 `single`。请参阅[范围](#范围)。

**timezone** `string` *required*

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

**locale** `string` *required*

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

**qrIds** `string[]`

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

**name** `string`

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

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

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

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

## 更新定时报告

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

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

**id** `string` *required*

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

**status** `string`

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

**name** `string`

名称，最多 40 个字符。

**frequency** `string`

`daily`、`weekly` 或 `monthly`。

**scope** `string`

`all`、`selected` 或 `single`。

**qrIds** `string[]`

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

**includePdf** `boolean`

在邮件中附带 PDF。

**timezone** `string`

IANA 时区。

**locale** `string`

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

## 删除定时报告

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

删除计划，并停止之后的所有邮件。

> [!WARNING]
>
> 删除定时报告后无法撤销。

**id** `string` *required*

定时报告的 ID。

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

## 常见问题

> [accordion] 导出报告时返回 404
>
> 使用 `selected` 或 `single` 范围时，`qrIds` 中没有任何一个与您工作区中带短链接的二维码匹配。请检查这些 ID。

> [accordion] 创建定时报告时返回 404 "QR not found."
>
> `qrIds` 中的某个 ID 不是您工作区中的二维码，或者该二维码已被删除。请通过[列出二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)检查这些 ID。

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

> [accordion] 404 "Scheduled report not found."
>
> 该 `id` 与您工作区中的任何定时报告都不匹配。请从[列出定时报告](#列出定时报告)中获取。

> [accordion] 报告中缺少今天的扫描
>
> 报告只覆盖最近一个已结束的周期。如需实时数据，请使用[数据分析](https://docs.getqr.com/zh/api/endpoints/analytics.md)。

## 后续步骤

> [card] [数据分析](https://docs.getqr.com/zh/api/endpoints/analytics.md)

> [card] [应用中的定时报告](https://docs.getqr.com/zh/analytics/scheduled-reports.md)

> [card] [阅读报告](https://docs.getqr.com/zh/analytics/reading-reports.md)

> [card] [错误](https://docs.getqr.com/zh/api/errors.md)


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