API 简介

​

功能概览

​

指南

​

基础 URL

https://getqr.com/api/v1

​

版本控制

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

​

快速入门

curl https://getqr.com/api/v1/health

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

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。唯一的例外是批量创建的 CSV 上传，它使用 multipart/form-data。
• 响应。 响应为 JSON。下载类请求（例如二维码图片和批量创建的 ZIP 压缩包）直接返回文件本身。
• 日期。 日期为 UTC 时区的 ISO 8601 字符串，例如 2026-08-01T10:00:00.000Z。
• 查询参数。 布尔参数取字符串 true 或 false。
• 部分更新。 PATCH 端点只更改您发送的字段。
• 敏感信息。 响应中绝不包含密码或内部标识符。受密码保护的二维码只会返回 passwordProtected: true。
• 工作区。 每个请求都在 API 密钥所属的工作区中执行，无需传入工作区 ID。请参阅访问权限与角色。
• 错误。 失败的请求会返回带有固定 code 的 error 对象。请参阅错误。

​

分页

{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}

​

幂等性

-H "Idempotency-Key: order-4821-qr"

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

​

速率限制

​

即将推出

​

后续步骤