开发者
API 与集成参考
调用 Business API、管理密钥和接收 Webhook 所需的全部信息。
身份验证
Business API 使用 API 密钥对每个请求进行身份验证。请通过 X-Api-Key 请求头发送密钥，或以 Bearer 令牌形式放在 Authorization 请求头中。
密钥以 qrg_ 为前缀，仅在创建时显示一次。请妥善保管；之后将无法再次查看该密钥。
未携带有效密钥的请求将返回 401。缺少所需权限的密钥会收到 403 及错误 insufficient_scope。工作区以外的资源返回 404，如同不存在一样。
基础 URL
所有 Business API 端点均位于 /v1 前缀下。
例如，通过 https://qr-global.com/api/v1/qr-codes 列出您的二维码。
- 解析后的基础 URL
- https://qr-global.com
端点
所有端点均位于 /api/v1 下，并需要具备所列权限的密钥。
| 方法 | 路径 | 权限 | 作用 |
|---|---|---|---|
| GET | /qr-codes | qr:read | 列出二维码（筛选：type、search、folder_id、tag、archived） |
| POST | /qr-codes | qr:write | 创建二维码 |
| POST | /qr-codes/bulk | qr:write | 一次最多创建 100 个二维码 |
| GET | /qr-codes/{id} | qr:read | 获取单个二维码 |
| PUT | /qr-codes/{id} | qr:write | 更新二维码及其文件夹和标签 |
| DELETE | /qr-codes/{id} | qr:write | 删除二维码 |
| GET | /qr-codes/{id}/image | qr:read | 渲染图片（PNG 或 SVG） |
| GET | /qr-codes/{id}/stats | analytics:read | 扫描统计 |
| GET | /qr-codes/{id}/scans | analytics:read | 扫描日志 |
| GET | /folders | qr:read | 列出文件夹 |
| GET | /tags | qr:read | 列出标签 |
| GET | /webhooks | webhooks:manage | 列出 Webhook 订阅 |
| POST | /webhooks | webhooks:manage | 订阅事件 |
| DELETE | /webhooks/{id} | webhooks:manage | 取消订阅 |
供 Postman、代码生成器和无代码工具使用的机器可读描述（OpenAPI 3.1）： 下载 openapi.json
API 密钥
在控制台的 API 密钥页面中创建和撤销密钥。
每个密钥都归属于您的工作区，并沿用您套餐的速率限制。
撤销密钥后立即生效。
权限（scope）
创建密钥时，可授予完全访问权限，或仅授予集成所需的权限。缺少权限的密钥会收到 403，响应中包含错误 insufficient_scope 和 required_scope。
qr:read— 读取二维码- 列出和查看二维码及其图片、文件夹和标签。
qr:write— 管理二维码- 创建二维码（包括批量创建）、编辑、在文件夹间移动、添加标签和删除。
analytics:read— 读取分析数据- 每个二维码的扫描统计和扫描日志。
webhooks:manage— 管理 Webhook- 为端点订阅事件及取消订阅（Zapier、Make）。
在引入权限之前创建的密钥保留完全访问权限。完全访问权限也涵盖以后新增的权限。
示例
复制粘贴以下 curl 命令即可快速上手。请将 YOUR_API_KEY 替换为 API 密钥页面中的密钥。
列出二维码
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
创建二维码
发送二维码类型和内容，服务器会生成并保存该二维码。
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'渲染图片
获取现成的 PNG 或 SVG 文件 — 传入 ?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Webhook 负载示例
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}扫描分析
GET /qr-codes/{id}/stats 返回总数、独立访客、热门国家、设备、浏览器和每日扫描量。GET /qr-codes/{id}/scans 返回扫描日志，最新的在前，每页 50 条（per_page 最多 100）。
两者都接受 from 和 to（如 2026-10-01 这样的日期或完整时间戳）以及 timezone（默认 UTC）。不含时间的日期表示该时区内的一整天。
只能获取您套餐历史保留期内的数据：更早的扫描会被删除。访客的 IP 地址和 User-Agent 永远不会返回。
指定时段的扫描统计
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
扫描日志，第 2 页
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
文件夹和标签
GET /folders 和 GET /tags 列出工作区的文件夹和标签。创建或更新二维码时传入 folder_id 和 tags（标签 slug）：folder_id 为 null 会将二维码移出文件夹，tags 会替换整组标签。
使用 ?folder_id= 或 ?tag= 筛选二维码列表。
将二维码移入文件夹并添加标签
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'批量创建
POST /qr-codes/bulk 一次请求最多创建 100 个二维码。与控制台中的 CSV 导入一样，需要包含批量创建功能的套餐，并受有效二维码数量上限的约束。
每个条目单独处理：响应会列出每个条目及其状态 created（附带新二维码）或 failed（附带 error 和 errors）。不要重新发送整批，只需重发失败的条目。
创建两个二维码
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Webhook 订阅（REST hooks）
Zapier、Make 以及您自己的服务都可以通过 API 订阅事件：使用 url 和 events 调用 POST /webhooks，取消订阅时调用 DELETE /webhooks/{id}。这些端点与 Webhook 页面上的端点相同。
POST 的响应中包含 secret，仅显示一次：用它来验证 X-Webhook-Signature 请求头。如果您未发送自己的 secret（至少 16 个字符），我们会自动生成一个。
事件：qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted。订阅需要包含 Webhook 的套餐；取消订阅始终可用。每个工作区最多可有 25 个端点。
订阅扫描事件
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'取消订阅
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhook
Webhook 会在事件发生时将其实时推送到您的端点，无需轮询。
在控制台的 Webhook 页面中配置端点。
每次投递都带有签名，失败时会按指数退避策略重试。
当有人扫描您的二维码时，会触发 scan 事件。
在投递日志中查看投递尝试、负载和响应。
返回 2xx 状态码即表示确认投递；其他任何状态码均视为失败。
转化跟踪
有了转化数据，A/B 测试就能知道哪个目标带来订单或注册，而不只是扫描。开启自动优化后，流量会转向转化最好的变体。
把脚本加到访客完成转化后看到的页面：订单确认页、感谢页或成功页。它适用于任何域名，不需要 API 密钥。
代码片段
<script src="https://qr-global.com/c.js" async></script>
- 每次扫描都会在目标 URL 后附加带签名的参数 qrg_v，从而把转化关联到二维码和变体。
- 脚本会把令牌在第一方 Cookie 中保存 30 天，即使访客先浏览了其他页面，转化也会被统计。
- 每次扫描只计一次：刷新感谢页不会增加转化。
- 适用于跳转到 http(s) 页面的二维码。
导出
在导出页面将您的二维码、扫描、位置和操作记录导出为 CSV。
导出使用控制台会话而非 API 密钥——请在登录状态下打开。
提示与常见错误
- 401 Unauthorized — API 密钥缺失或无效。请检查 X-Api-Key 请求头。
- 403 Forbidden — 密钥缺少所需权限（insufficient_scope），或您的套餐不包含该功能（api_access_required、bulk_not_available、webhooks_not_available）。
- 404 Not Found — 资源不存在或属于其他工作区。
- 429 Too Many Requests — 已达到您套餐的每分钟请求上限。请等待 Retry-After 响应头中指定的秒数。
- 部分功能（如 Webhook）取决于您的套餐。如果端点返回功能错误，请升级套餐。
- 还没有 Webhook 投递记录？扫描您的任一二维码即可生成一条。
- 失败的 Webhook 投递会自动重试；您也可以在投递日志中手动重试。
- 团队成员在您的工作区内操作；密钥和数据归属于工作区所有者。