一个活码，持续更新。

快速开始

在用户后台「开发者」创建 Token。所有接口使用 HTTPS，基础地址为 https://app.pandaqr.xyz/api/v1。下列命令从环境变量读取 Token；不要将它写进公开代码或 URL。

curl https://app.pandaqr.xyz/api/v1/qrs \
  -H "Authorization: Bearer $PANDAQR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-community-001" \
  -d '{"title":"社区入口","target":{"type":"url","payload":{"url":"https://example.com"}}}'

保存返回的 data.qr.id 和 data.qr.scan_url。接口路径使用 ID，不是短链接里的 slug。

认证与权限

请求头：Authorization: Bearer pqr_live_…。Token 完整值只显示一次，服务端仅存 SHA-256 哈希。有效期可选 7、30、90、365 天，最多同时存在 20 个有效 Token；可随时撤销，最近使用时间和 API 请求记录可在后台查看。

权限：qrs:read 读取；qrs:write 创建和更新；images:write 上传；qrs:delete 删除。每个 Token 只操作所属账户。可以进一步限定到一个活码；限定 Token 不能创建活码或调用独立上传接口，应使用该活码的 PUT /qrs/{id}/image。

轮换方式：创建新 Token → 更新集成配置并验证 → 撤销旧 Token。到期不会自动延长。审计记录保留 90 天，不保存 Token 明文和请求正文。

接口参考

列表按 ID 降序排列，默认每页 20 条；next_cursor: null 表示结束。成功返回 {ok:true,data:…}，新建返回 201，其余成功返回 200。时间戳均为 Unix 毫秒。完整字段、限制及请求模型见 OpenAPI 规范。

PATCH 支持 title、description、note、status、target、expiry。target 整体替换；status 为 active 或 paused。多链接 target.type 为 multilink，payload.items 为 1–10 个包含 label 和 url 的对象。

创建图片活码

先上传，再使用响应中的 data.image.r2_key 和 mime 创建活码。支持 PNG、JPEG、WebP，单张不超过 2 MiB；HEIC 请先转换。只允许绑定本账户已上传的图片。

curl https://app.pandaqr.xyz/api/v1/images \
  -H "Authorization: Bearer $PANDAQR_ACCESS_TOKEN" \
  -F "file=@group-qr.png"

将下面 JSON 发送到 POST /qrs：

{
  "title": "微信群入口",
  "target": {
    "type": "image",
    "payload": { "r2_key": "上传接口返回的 r2_key", "mime": "image/png" }
  },
  "expiry": { "enabled": true, "window_seconds": 604800, "lead_times": [86400], "action": "keep" }
}

一键替换群二维码图片

对已有图片活码直接上传新图。接口同时保存图片和切换内容，无需先上传再 PATCH。支持原始图片字节，也支持 multipart/form-data 的 file 字段。

curl -X PUT "https://app.pandaqr.xyz/api/v1/qrs/$QR_ID/image" \
  -H "Authorization: Bearer $PANDAQR_ACCESS_TOKEN" \
  -H "Content-Type: image/jpeg" \
  -H "Idempotency-Key: replace-community-001" \
  --data-binary @group-qr.jpg

成功响应示例（省略部分字段）：

{
  "ok": true,
  "data": {
    "qr": {
      "id": "01...",
      "slug": "abcd2345",
      "scan_url": "https://q.pandaqr.xyz/abcd2345",
      "status": "active",
      "target": { "type": "image", "payload": { "r2_key": "images/.../new.jpg", "mime": "image/jpeg" } }
    }
  }
}

ID、slug 和 scan_url 不变；下一次重新打开扫码页会读取最新内容，已打开的页面需要刷新。启用的到期提醒重新计时，但暂停的活码不会自动恢复；如需恢复，明确 PATCH status 为 active。此接口用于图片活码，其他类型返回 409。

错误、限流与重试

每个 Token 每分钟最多 60 个请求。响应包含 X-Request-Id 和 X-RateLimit-Limit / Remaining / Reset。收到 429 时等待 Retry-After 秒再重试。

写请求可发送 Idempotency-Key（1–128 个字母、数字、点、下划线、冒号或短横线）。同 Token、同键、完全相同的请求在 24 小时内重放原响应，响应头含 Idempotency-Replayed: true。重复请求也消耗限流额度。不要给不同操作复用同一个键。

重试须保持方法、路径、Content-Type 和正文原始字节一致；multipart 的 boundary 也需相同，自动化建议发送原始图片字节。未带幂等键的 POST 不应盲目重试。409 request_in_progress 表示前次处理未完成或结果不确定，先读取活码状态；500 或网络断开后也先检查结果。

{"ok":false,"error":{"code":"insufficient_scope","message":"Requires qrs:write"}}

• 400：invalid_input / invalid_image，请修正字段或图片归属。
• 401：invalid_token，Token 无效、已到期或撤销。
• 403：insufficient_scope，缺少权限或受到单活码限制。
• 404：not_found，活码不存在或不属于此账户。
• 409：target_type_mismatch / idempotency_conflict / request_in_progress。
• 413 / 415：图片过大 / 格式不支持。
• 429：rate_limited。500：internal_error，保留 X-Request-Id 排查。

给 Agent 的 skill

下载 pandaqr skill 压缩包，将 pandaqr 文件夹放入 Agent 的 skills 目录。也可先阅读 SKILL.md。内置 Python 客户端无需第三方依赖，支持分页、上传、创建和替换图片，不会自动重试写请求。

export PANDAQR_ACCESS_TOKEN='你的 Token'
python3 pandaqr/scripts/pandaqr.py list
python3 pandaqr/scripts/pandaqr.py replace-image "$QR_ID" group-qr.jpg

Agent 应先识别目标活码，再替换图片并确认 scan_url 不变。删除活码需要明确指令。

iOS 快捷指令

下载「PandaQR 更新群二维码」

1. 先在后台创建一个图片活码。
2. 在「开发者」创建仅限此活码的 Token，勾选 qrs:write 和 images:write。
3. 在 iPhone 下载并用「快捷指令」打开文件，按导入提示填写 Token 和活码 ID；也可在编辑器最前面的两个文本动作里修改。
4. 运行快捷指令，选取最新的群二维码图片。它会转换为 JPEG，向 API 上传并显示响应；ok: true 才表示成功。
5. 可将快捷指令添加到主屏幕，之后点一下并选择图片即可更新。重新扫码确认新图。

iOS 首次运行可能询问照片和网络访问权限。若转换后仍超过 2 MiB，请先缩小图片。取消选图不会更新；Token 到期或撤销后需要替换配置。请勿分享填好个人 Token 的副本。