📦 CodeBox QR Code — 二维码生成
v1.0.0调用 CodeBox API 一键生成/管理动态二维码，内置200+样式模板，可实时追踪扫码数据（设备、位置、时间），支持扫描分析与导出，满足营销、分享、统计等多场景需求。
by 详细分析 ▾
运行时依赖
版本
Initial release: 9 QR code operations via CodeBox API
安装命令
点击复制技能文档
# CodeBox 二维码技能 使用 CodeBox API 生成、管理和追踪二维码。 ## 准备工作 用户需要 CodeBox API 密钥，可在 https://www.codebox.club/zh/dashboard/apikeys 获取。 设置环境变量： `` CODEBOX_API_KEY=cb_sk_xxxxxxxxxxxxxxxx ` ## API 基址 所有请求均发送至 https://www.codebox.club/api/v1/plugin ## 鉴权 每个请求都必须携带： ` Authorization: Bearer $CODEBOX_API_KEY ` ## 可用操作 ### 1. 生成二维码 POST https://www.codebox.club/api/v1/plugin/generate 用于创建新的二维码，支持动态（可追踪、可更新 URL）与静态模式。 `bash curl -X POST https://www.codebox.club/api/v1/plugin/generate \ -H "Authorization: Bearer $CODEBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "https://example.com", "mode": "DYNAMIC", "name": "My QR Code", "templateId": "classic-black", "errorCorrectionLevel": "M" }' ` 参数： - content（必填）：要编码的 URL 或文本 - mode：DYNAMIC（默认，可追踪）或 STATIC（无追踪，免费） - name：二维码的显示名称 - templateId：样式模板 ID（先用 list_templates 浏览） - keywords：关键词数组，用于自动模板匹配（如 ["christmas", "holiday"]） - errorCorrectionLevel：L、M（默认）、Q 或 H 返回包含：id、shortUrl、qrCodeUrl（PNG 图片）、targetUrl ### 2. 批量生成 POST https://www.codebox.club/api/v1/plugin/batch-generate 单次请求最多生成 20 个二维码，每个条目独立处理（支持部分失败）。 `bash curl -X POST https://www.codebox.club/api/v1/plugin/batch-generate \ -H "Authorization: Bearer $CODEBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ {"content": "https://example.com/1", "name": "Link 1"}, {"content": "https://example.com/2", "name": "Link 2", "templateId": "ocean-blue"} ] }' ` ### 3. 列出二维码 GET https://www.codebox.club/api/v1/plugin/qrcodes `bash curl "https://www.codebox.club/api/v1/plugin/qrcodes?page=1&size=10" \ -H "Authorization: Bearer $CODEBOX_API_KEY" ` 查询参数：page、size（最大 50）、mode（STATIC/DYNAMIC/AI）、keyword ### 4. 获取扫描分析 POST https://www.codebox.club/api/v1/plugin/analytics `bash curl -X POST https://www.codebox.club/api/v1/plugin/analytics \ -H "Authorization: Bearer $CODEBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "qrCodeId": "xxx", "startDate": "2026-01-01", "endDate": "2026-03-23" }' ` 返回：总扫描次数、独立扫描次数、时间序列、设备/浏览器/操作系统分布、地理位置统计。 ### 5. 更新动态二维码 POST https://www.codebox.club/api/v1/plugin/update 更改动态二维码的目标 URL、名称或状态。 `bash curl -X POST https://www.codebox.club/api/v1/plugin/update \ -H "Authorization: Bearer $CODEBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "xxx", "targetUrl": "https://new-destination.com", "name": "Updated Name" }' ` 参数：id（必填）、targetUrl、name、status（READY/EXPIRED/DELETED） ### 6. 删除二维码 DELETE https://www.codebox.club/api/v1/plugin/qrcodes/{id} `bash curl -X DELETE "https://www.codebox.club/api/v1/plugin/qrcodes/xxx" \ -H "Authorization: Bearer $CODEBOX_API_KEY" ` ### 7. 克隆二维码 POST https://www.codebox.club/api/v1/plugin/qrcodes/{id}/clone `bash curl -X POST "https://www.codebox.club/api/v1/plugin/qrcodes/xxx/clone" \ -H "Authorization: Bearer $CODEBOX_API_KEY" ` ### 8. 导出扫描事件 GET https://www.codebox.club/api/v1/plugin/qrcodes/{id}/scans `bash curl "https://www.codebox.club/api/v1/plugin/qrcodes/xxx/scans?page=1&size=20" \ -H "Authorization: Bearer $CODEBOX_API_KEY" ` 查询参数：page、size（最大 100）、startDate、endDate ### 9. 浏览模板 GET https://www.codebox.club/api/v1/plugin/catalog `bash curl "https://www.codebox.club/api/v1/plugin/catalog?keyword=christmas&limit=10" \ -H "Authorization: Bearer $CODEBOX_API_KEY" ` 查询参数：category、keyword、limit（默认 20） ## 规则 - 始终使用环境变量中的 $CODEBOX_API_KEY，切勿在行内询问用户。 - 除非用户明确要求静态二维码，否则默认使用 DYNAMIC 模式。 - 当用户描述样式（如“圣诞主题”、“蓝色海洋”）时，在生成调用中使用 keywords 参数进行自动模板匹配，或先调用 catalog 接口查找匹配的 templateId。 - 动态二维码每次生成消耗 1 积分，静态二维码免费。 - 批量生成多个二维码时，优先使用 batch-generate（上限 20 个），而非逐个调用。 - 返回中的 qrCodeUrl 是 PNG 图片的直接链接，可直接分享。 - shortUrl 是可追踪的跳转链接，用于分享给终端用户。 ## 错误处理 - 403 且 code 为 CREDIT_EXHAUSTED`：用户积分已用完，请其前往 https://www.codebox.club/zh/dashboard/pricing 充值。 - 401：API 密钥无效，请用户检查密钥 https://www.codebox.club/zh/dashboard/apikeys。 - 400：请求错误——请检查必填参数。