开发者指南
CodeBox 可编程二维码平台 — API、SDK、Webhooks 完整开发者文档
平台概述
CodeBox 是可编程二维码基础设施平台，提供二维码生成、追踪、管理的全套 API 能力。你可以通过 REST API、TypeScript SDK 或 AI Agent（MCP）接入。
接入方式
| 方式 | 适用场景 | 文档 |
|---|---|---|
| REST API | 任意语言直接调用 | 生成二维码 |
| TypeScript SDK | Node.js / 前端项目 | SDK 文档 |
| MCP Server | Claude Desktop、Cursor 等 AI Agent | MCP 文档 |
| Webhooks | 实时接收扫码等事件通知 | Webhooks 文档 |
快速开始
1. 获取 API Key
登录后在 Dashboard → API 管理 中创建 API Key。
公开的二维码生成接口无需 API Key 即可使用。追踪、统计等高级功能需要认证。
2. 生成第一个二维码
最简调用，无需认证：
curl -X POST https://www.codebox.club/api/v1/qrcode/generate \
-H "Content-Type: application/json" \
-d '{"content": "https://example.com"}' \
-o qrcode.png使用 SDK 生成带追踪的动态二维码：
import { CodeBox } from '@codebox.club/sdk';
const client = new CodeBox({ apiKey: 'cb_sk_xxx' });
const qr = await client.qrcodes.create({
content: 'https://example.com',
mode: 'DYNAMIC',
});
console.log(qr.shortLink); // 带追踪的短链3. 接收扫码通知
配置 Webhook 实时接收扫码事件：
curl -X POST https://www.codebox.club/api/v1/webhooks \
-H "Authorization: Bearer cb_sk_xxx" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-server.com/webhook", "events": ["scan.created"]}'认证
详见 鉴权文档。
| 鉴权方式 | Header | 说明 |
|---|---|---|
| Bearer Token | Authorization: Bearer cb_sk_xxx | 推荐，适用于所有 API |
| cb-api-key | cb-api-key: cb_sk_xxx | 兼容旧版，Plugin 端点同时支持 |
频率限制
| 用户类型 | 频率限制 | 每日上限 | 最大尺寸 |
|---|---|---|---|
| 匿名用户 | 10 次/分钟 | — | 1000px |
| 登录用户 | 60 次/分钟 | — | 2000px |
| API Key | 60 次/分钟 | 1000 次/天 | 2000px |
API 端点一览
公开接口
| 端点 | 方法 | 说明 | 认证 |
|---|---|---|---|
/api/v1/qrcode/generate | POST | 生成二维码图片 | 可选 |
认证接口（API Key）
| 端点 | 方法 | 说明 | 权限 |
|---|---|---|---|
/api/v1/plugin/generate | POST | 生成带追踪的二维码 | qrcode:generate |
/api/v1/plugin/analytics | GET | 扫码统计 | qrcode:generate |
/api/v1/plugin/update | PATCH | 更新动态码目标链接 | qrcode:generate |
/api/v1/plugin/catalog | GET | 模板列表 | qrcode:generate |
额度接口
| 端点 | 方法 | 说明 | 认证 |
|---|---|---|---|
/api/v1/credits/packages | GET | 额度包列表 | 无需 |
/api/v1/credits/balance | GET | 查询当前额度余额 | Session |
/api/v1/credits/history | GET | 额度变动流水 | Session |
/api/v1/credits/purchase | POST | 购买额度包 | Session |
额度消耗规则：创建动态追踪码消耗 1 次普通额度，创建 AI 二维码消耗 1 次 AI 额度。静态码和纯图片生成不消耗额度。每月自动发放免费额度（普通 5 次、AI 5 次），充值额度永不过期。所有功能对全部用户开放，无 Feature 门槛。AI 二维码任务如果在短链创建、第三方任务创建或最终处理阶段失败，会自动补偿返还本次 AI 额度。当前 AI 任务链路使用 requestKey、sourceTaskId 和额度流水 operationKey 作为应用层幂等键，用于防止重复提交、重复回调和重复补偿，不依赖可空字段唯一约束。
管理接口（Session 登录）
| 端点 | 方法 | 说明 |
|---|---|---|
/api/v1/apikeys | POST / GET | 创建 / 列出 API Key |
/api/v1/apikeys/:id | GET / PATCH / DELETE | 查看 / 更新 / 删除 API Key |
/api/v1/webhooks | POST / GET | 创建 / 列出 Webhook |
/api/v1/webhooks/:id | GET / PATCH / DELETE | 查看 / 更新 / 删除 Webhook |
/api/ai/create | POST | 创建 AI 二维码异步任务并扣减 1 次 AI 额度 |
/api/ai/task | GET | 查询 AI 二维码任务状态（Dashboard 轮询） |
/api/v1/qrcode/verify-ai-task | GET | 校验 AI 任务完成后二维码记录是否已创建 |
AI 二维码任务状态
Dashboard 创建 AI 二维码时，会先提交生成任务，再轮询任务状态：
waiting/processing：任务仍在进行中，前端继续轮询finish：AI 图片已处理完成；任务表会记录完成时间，并通过sourceTaskId保证二维码记录只落库一次failed：任务失败，前端应直接停止轮询并展示错误提示
这两个端点是 Dashboard 内部 Session 接口，不面向 API Key / SDK / MCP 用户公开。若调整 AI 任务状态字段或终态语义，需要同步更新前端轮询逻辑与相关文档。
AI Agent
| 端点 | 方法 | 说明 |
|---|---|---|
/api/mcp | POST | MCP Server（Streamable HTTP） |
错误码
| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未认证 / API Key 无效 |
| 403 | 权限不足 / 额度不足（CREDIT_EXHAUSTED） |
| 429 | 频率或配额超限 |
| 500 | 服务器错误 |