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

# API 简介

> 通过您自己的代码管理二维码、模板、分析数据和报告。

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

GetQR API 是一套 REST API，可完成您在控制台中的操作：创建和更新二维码、下载二维码图片、读取扫描分析数据以及导出报告。使用账户 API 密钥进行身份验证，并调用 `/api/v1` 下带版本号的端点。

## 功能概览

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)
>
> 创建、列出、更新、暂停、复制、删除和下载二维码。

> [card] [数据分析](https://docs.getqr.com/zh/api/endpoints/analytics.md)
>
> 单个二维码或整个工作区的扫描总数和细分数据。

> [card] [报告](https://docs.getqr.com/zh/api/endpoints/reports.md)
>
> 导出一次性报告，或设置定期发送的报告邮件。

> [card] [模板](https://docs.getqr.com/zh/api/endpoints/templates.md)
>
> 保存设计，并将其应用到新的二维码上。

> [card] [批量创建二维码](https://docs.getqr.com/zh/api/endpoints/bulk-qr-creations.md)
>
> 通过 JSON 或 CSV 文件一次创建最多 100 个二维码。

> [card] [文件](https://docs.getqr.com/zh/api/endpoints/files.md)
>
> 为二维码上传 PDF、图片、视频和 Logo。

> [card] [健康检查](https://docs.getqr.com/zh/api/endpoints/health.md)
>
> 检查 API 是否正常运行，无需 API 密钥。

## 指南

> [card] [二维码类型](https://docs.getqr.com/zh/api/guides/qr-types.md)
>
> 16 种二维码类型各自的数据格式。

> [card] [自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)
>
> 点样式、定位角、颜色、边框和 Logo。

> [card] [访问规则](https://docs.getqr.com/zh/api/guides/access-rules.md)
>
> 生效计划、扫描次数上限、密码、暂停和删除。

## 基础 URL

所有端点都位于同一个基础 URL 下：

```text theme={null}
https://getqr.com/api/v1
```

## 版本控制

API 版本是路径的一部分：所有端点都位于 `/api/v1/` 下。

* 不兼容的变更会以新的版本前缀发布，例如 `/api/v2/`，`/api/v1/` 会继续可用。
* 新增的可选字段或新端点等兼容性变更可能出现在 v1 中。请让您的代码忽略无法识别的响应字段。

## 快速入门

**1. 获取 API 密钥**

在账户设置中生成或查看密钥。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

**2. 检查 API 是否可以访问**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

响应为 `{ "status": "ok", "version": "v1" }`。

**3. 创建第一个二维码**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

API 会返回 `201` 和新建的二维码，其中包含 `id` 和 `shortLink`。

**4. 下载图片**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## 请求与响应

* **格式。** 请求体以 JSON 格式发送，并带上 `Content-Type: application/json`。唯一的例外是[批量创建](https://docs.getqr.com/zh/api/endpoints/bulk-qr-creations.md)的 CSV 上传，它使用 `multipart/form-data`。
* **响应。** 响应为 JSON。下载类请求（例如二维码图片和批量创建的 ZIP 压缩包）直接返回文件本身。
* **日期。** 日期为 UTC 时区的 ISO 8601 字符串，例如 `2026-08-01T10:00:00.000Z`。
* **查询参数。** 布尔参数取字符串 `true` 或 `false`。
* **部分更新。** `PATCH` 端点只更改您发送的字段。
* **敏感信息。** 响应中绝不包含密码或内部标识符。受密码保护的二维码只会返回 `passwordProtected: true`。
* **工作区。** 每个请求都在 API 密钥所属的工作区中执行，无需传入工作区 ID。请参阅[访问权限与角色](https://docs.getqr.com/zh/api/authentication.md#访问权限与角色)。
* **错误。** 失败的请求会返回带有固定 `code` 的 `error` 对象。请参阅[错误](https://docs.getqr.com/zh/api/errors.md)。

## 分页

列表端点（二维码、模板和定时报告）接受两个查询参数：

| 参数 | 说明 |
| - | - |
| `page` | 要返回的页码。默认为 `1`。 |
| `pageSize` | 每页结果数，最多 `100`。默认为 `100`。 |

响应包含一个 `data` 数组和一个 `pagination` 对象：

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| 字段 | 说明 |
| - | - |
| `page` | 本次返回的页码。 |
| `pageSize` | 本次返回的每页大小。 |
| `total` | 所有页面的结果总数。 |
| `hasMore` | 还有下一页时为 `true`。 |

只要 `hasMore` 为 `true`，就继续请求下一页。`pageSize` 超过 `100` 时会返回 [`422`](https://docs.getqr.com/zh/api/errors#校验错误)。

## 幂等性

发生网络错误时，您可能无法确定请求是否已成功执行。要安全地重试[创建二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md#创建二维码)，请发送 `Idempotency-Key` 请求头，并填入一个由您自定的唯一值：

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* 24 小时内使用相同的键重复请求，会返回原始响应，而不会再创建一个二维码。
* 对于重放的响应，`x-idempotent-replay` 响应头为 `true`；对于新的响应，则为 `false`。
* 如果使用该键的第一个请求仍在处理中，API 会返回 `409 conflict`。请等它完成后再重试。
* 使用相同的键但请求体不同时，会返回 `422 unprocessable_entity`。
* 不带该请求头时，30 秒内发送的相同请求体会被视为重复请求。

批量创建则改为在请求体中使用 `idempotencyKey` 字段。请参阅[批量创建二维码](https://docs.getqr.com/zh/api/endpoints/bulk-qr-creations.md)。

## 速率限制

每个 API 密钥每分钟最多可发送 600 个请求。请参阅[速率限制](https://docs.getqr.com/zh/api/rate-limits.md)。

## 即将推出

可直接印刷的文件包将在后续版本中推出。

## 后续步骤

> [card] [身份验证](https://docs.getqr.com/zh/api/authentication.md)

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)


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