QSL 卡片制作工具 · API 使用文档

通过 URL 参数直接生成 QSL 卡片 · 支持一键出卡与配置云端同步 · 示例域名：qsl.ttdd.top（部署到其他域名时，把示例链接中的域名替换为你自己的域名即可）

💡 一句话入门：把通联信息拼到链接里，打开即自动生成并下载卡片：

https://qsl.ttdd.top/api/card?call=BG5XYZ&date=20260904&time=1234&freq=145.5&rst=59&mode=FM&auto=1

一、接口总览（v6.74 · 全站 49 个接口）

⭐ = QSL 卡片设计工具实际使用；接口随系统版本持续维护，本文档与 worker-unified.js 同步更新。除 /api/card 外均为 JSON 接口（Content-Type: application/json）。

1. 认证与账户

接口	方法	用途	登录
/api/register	POST	注册（昵称/邮箱/密码/呼号/邀请码，呼号自动大写，需管理员审批）	公开
/api/login	POST / GET	登录（邮箱+密码；GET 返回当前登录态）	公开
/api/logout	GET	退出登录	公开
/api/me	GET	当前登录态与个人信息（呼号、分组、权限、R2 开关等）	需登录 ⭐
/api/member	GET / POST	个人资料（昵称/呼号/主题/设备/功率/天线/QTH/签名等）读写	需登录
/api/profile	GET / POST	个人设置读写（公开资料与偏好）	需登录
/api/password	POST	修改密码	需登录
/api/theme	GET / POST	主题读取与保存（默认主题、用户主题）	公开 ⭐
/api/admin/reclaim	POST	空间回收（管理员，清理 R2/图床孤儿对象与超期文件）	管理员

2. 卡片生成（制作/填写工具）

接口	方法	用途	登录
/api/card	GET / POST	一键出卡：传通联参数 → 跳转到带参页面生成卡片（详见下文第二~四节）	公开
/api/qslcard	GET / POST	分享版直接出卡（不经 /api/card 跳转，POST 返回图片）	公开
/api/card/redeem	GET	礼品卡兑换后的一键出卡跳转	需登录

3. 素材与方案（设计/制作/展厅）

接口	方法	用途	登录
/api/materials	GET / POST	素材库：查询（按 scope/cat/权限过滤、含使用量/点赞数）、上传（分享/提交官方）、编辑、删除；分享时自动转存 R2	GET 公开 / 写需登录 ⭐
/api/plans	GET / POST	方案库：查询（scope=all/home/official/mine）、创建/编辑/删除方案；背景与素材自动转存 R2（v6.73+）	GET 公开 / 写需登录 ⭐
/api/official	GET	官方素材/方案库查询（分类、权限分组、使用量/点赞数、缩略图）	公开 ⭐
/api/categories	GET	分类读取（官方/素材/方案分类树）	公开 ⭐
/api/fav	POST	收藏 / 取消收藏素材与方案	需登录 ⭐
/api/upload	POST	图片上传（本地 dataURL 自动压缩转存 R2；有权限时）	需登录 ⭐
/api/uploadcfg	POST	上传方案/素材配置（JSON）	需登录 ⭐
/api/imgproxy	GET	图床代理（下载外网图转存本站 R2/图床，供分享使用）	需登录

4. 统计与互动

接口	方法	用途	登录
/api/stats/use	POST	素材/方案「使用」计数 +1	公开 ⭐
/api/stats/lockclick	POST	锁定素材/方案「点击」计数（未授权点击统计）	公开 ⭐

5. 数据同步与站点链接

接口	方法	用途	登录
/api/sync	GET / POST	配置云端同步（GitHub Gist / KV）	需登录
/api/ghsync	GET / POST	GitHub Gist 同步（模板/素材上传下载）	需登录 ⭐
/api/githubcfg	POST	保存 GitHub Token 配置	需登录
/api/links	GET / POST	站点外链（导航栏链接）读取 / 保存	GET 公开

6. 通知与消息

接口	方法	用途	登录
/api/notice	GET	公告文本（页面顶部横幅）	公开
/api/notify	GET / POST	站内消息：查询 / 标记已读 / 清除	需登录 ⭐

7. 管理后台（/api/admin/*，需管理员）

接口	方法	用途
/api/admin/users	GET / POST	用户管理：审批、分组、权限、停用
/api/admin/materials	GET / POST	素材管理：审核、提级、下架/恢复、删除、编辑 URL（原样保存，v6.74 起后台编辑不再自动转存 R2）
/api/admin/plans	GET / POST	方案管理：审核、下架/恢复、编辑（背景/素材 URL 原样保存）、删除（下架后用户侧转私密，v6.73）
/api/admin/official	GET / POST	官方素材库管理
/api/admin/categories	POST	分类增删改 / 合并
/api/admin/notice	POST	公告编辑
/api/admin/settings	GET / POST	全局设置（R2、图床、邮件、邀请制、主题默认值等）
/api/admin/invites	GET / POST	邀请码生成 / 管理
/api/admin/members	POST	会员权益发放 / 调整（member/vip/svip 到期时间）
/api/admin/cards	GET / POST	礼品卡管理（生成 / 查询 / 停用）
/api/admin/links	POST	站点外链管理
/api/admin/theme	POST	默认主题设置
/api/admin/backup	GET / POST	数据备份 / 恢复
/api/admin/cleanup	POST	清理（去重/垃圾数据）
/api/admin/stats	GET	站点统计（方案/素材使用量点赞数等）
/api/admin/mailtest	POST	发送测试邮件（Resend）
/api/admin/audit	GET	操作审计日志
/api/admin/ai-classify	POST	AI 自动分类（素材/方案）
/api/admin/reclaim	POST	呼号认领审核
/api/admin/migrate	POST	历史数据迁移
/api/admin/*	GET/POST	后台管理接口（用户/素材/方案/统计/公告/设置等，需管理员凭证：登录会话或 X-Admin-Key）	管理员

8. 其他

接口	方法	用途	登录
/api/invitecfg	GET / POST	邀请制注册配置（开关、说明）	公开

▸ 接口持续演进：上述总览与 worker-unified.js 同源（v6.74 校验，49 个端点全部存在）。设计工具实际调用 15 个（标注 ⭐）。

二、一键出卡 /api/card

把通联信息作为 URL 参数传递，Worker 校验后 302 跳转到 QSL 卡片制作页面，页面自动填入并生成卡片。支持 GET 和 POST（JSON / 表单）。

2.1 通联信息参数

参数	对应卡片字段	示例	必填
call	对方呼号	`BG5XYZ`	推荐
date	日期（自动拆分为年月日）	`20260904` / `2026-09-04` / `2026年9月4日`	可选
day / month / year	单独的年 / 月 / 日	`day=04&month=9&year=2026`	可选
utc	UTC 世界时（支持多种写法）	`1234` / `12:34`	可选
time	UTC 的别名	`1234`	可选
bjt	北京时间（与 UTC 自动互算）	`20:34`	可选
freq	频率 MHz	`145.5`	可选
rst	信号报告	`59` / `599`	可选
rig	设备（trx 为别名）	`IC-705`	可选
pwr	功率	`5W`	可选
ant	天线	`GP`	可选
rmks	寄语 RMKS	`73!`	可选
op	操作员 / 签名文本	`BG9PZK`	可选
mycall	我的呼号（导出文件命名用）	`BG9PZK`	可选
toqth	对方 QTH（通联对象的地点）	`北京市朝阳区`	可选
qth	我的 QTH 地点	`Zhongwei`	可选
mode	工作模式（FM/SSB/CW/FT8，其它文本作自定义模式）	`FM` / `DMR`	可选
type	确认类型（cfm 为别名）	`qso` / `swl` / `eye`	可选

2.2 行为控制参数

参数	作用	取值
side	导出哪一面 / 哪种形式	`front`（正面）、`back`（背面，默认）、`both` 或 `merged`（正反合并一张图）、`both2` 或 `two`（正反各导出一张）
auto	打开后是否自动下载 PNG	`1` / `true` / `yes` = 自动导出；缺省或 `0` = 渲染预览 + 手动导出
tpl	套用指定模板（模板 ID）	`tXXXXXX`（模板管理面板可复制）
page	指向分享版或默认页	`share` = 分享版；缺省 = 默认（个人版/分享版合并页）

2.3 二维码参数

参数	作用	示例
qr	二维码内容（URL 或文本），传了自动开启背面二维码	`https://bg9pzk.ttdd.top`
qrcode	qr 的别名	同 qr
qrcap	二维码说明文字，传了自动开启背面	`扫描获取电子QSL`
qrcaption / cap	qrcap 的别名	同 qrcap
qrside	二维码显示在哪一面	`front` / `back`（默认）/ `both`

2.4 回卡请求参数（勾选）

参数	含义	取值
pse	PSE（请回卡片）	`1` 勾选 / `0` 取消
tnx	TNX QSL（感谢你的卡片）	`1` / `0`
t73	VY 73!（通联愉快），vy73 为别名	`1` / `0`

2.5 备用信息参数（1-4）

参数	作用	示例
x1 .. x4	备用 1-4 的内容	`x1=Zhongwei`
x1name .. x4name	备用 1-4 的名称	`x1name=QTH`

备用信息只要名称或内容任一传参即显示，未传的字段显示为空，无需单独的显示开关。

三、完整示例

3.1 基础示例：预览出卡

https://qsl.ttdd.top/api/card?call=BG5XYZ&date=2026-09-04&utc=12:34&freq=145.5&rst=59&rig=IC-705&pwr=5W&ant=GP&mode=FM&type=qso&rmks=73!&qr=https%3A%2F%2Fqsl.ttdd.top%2FBG5XYZ&qrcap=%E6%89%AB%E7%A0%81%E6%9F%A5%E7%9C%8B&pse=1&x1name=QTH&x1=Zhongwei

打开后渲染预览，可在页面手动导出。

3.2 自动下载 PNG

https://qsl.ttdd.top/api/card?call=BG5XYZ&date=20260904&freq=438.5&mode=FM&auto=1

打开页面后约 1.5 秒自动导出并下载 PNG。

3.3 正反面合并导出（一张图）

https://qsl.ttdd.top/api/card?call=BG5XYZ&mode=SSB&side=both&auto=1

3.4 正反面各导出一张

https://qsl.ttdd.top/api/card?call=BG5XYZ&mode=FT8&side=both2&auto=1

3.5 套用模板

https://qsl.ttdd.top/api/card?tpl=tXXXXXX&call=BG5XYZ&auto=1

模板 ID 在「模板管理」面板中「复制ID」获取。

3.6 分享版页面直接传参（不经 /api/card）

https://qsl.ttdd.top/?call=BG5XYZ&mode=FM&auto=1

直接把参数加到主页 URL 上同样生效（页面会自动读取 URL 参数）。

四、POST 调用（外部程序）

4.1 POST JSON

POST https://qsl.ttdd.top/api/card
Content-Type: application/json

{
  "call": "BG5XYZ",
  "date": "20260904",
  "time": "1234",
  "freq": "145.5",
  "rst": "59",
  "rig": "IC-705",
  "pwr": "5W",
  "ant": "GP",
  "mode": "FM",
  "type": "qso",
  "rmks": "73!",
  "qr": "https://bg9pzk.ttdd.top",
  "auto": "1"
}

4.2 POST 表单（application/x-www-form-urlencoded）

POST https://qsl.ttdd.top/api/card
Content-Type: application/x-www-form-urlencoded

call=BG5XYZ&date=20260904&freq=438.5&mode=FM&auto=1

⚠️ 手机 / 微信等直接点击 /api/card 链接即可打开出卡页；如需程序自动下载 PNG，建议在服务端用 auto=1 并跟随 302 重定向到最终页面（PNG 由页面脚本触发下载）。

五、其它接口

5.1 配置同步 /api/sync（个人版，需登录）

上传配置：

POST https://qsl.ttdd.top/api/sync
Content-Type: application/json

{"action": "upload", "data": "<配置JSON字符串>"}

下载配置：

GET https://qsl.ttdd.top/api/sync?action=download

查询是否已有配置：

GET https://qsl.ttdd.top/api/sync?action=status

返回示例：

{"data": "<配置JSON>"}      // download
{"has": true}                  // status
{"ok": true, "bytes": 2048}    // upload

5.2 登录态 /api/me（个人版，需登录）

GET https://qsl.ttdd.top/api/me

{
  "loggedIn": true,
  "mode": "personal",
  "img": { "front": "https://...", "back": "https://...", "sig": "...", "stamp": "...", "imgA": "...", "imgB": "..." },
  "mycall": "BG9PZK",
  "qrText": "https://bg9pzk.ttdd.top",
  "qrCap": "扫描二维码获取精美电子QSL卡片",
  "announcement": "📢：系统公告！"
}

未登录访问会被 Cloudflare Access 拦截（302 到登录页）。

5.3 登录 / 退出

GET https://qsl.ttdd.top/api/login    // 跳转 Cloudflare Access 邮箱验证
GET https://qsl.ttdd.top/api/logout   // 退出登录

5.4 公告 /api/notice（公开）

GET https://qsl.ttdd.top/api/notice

{"text": "📢：系统公告！"}

页面顶部横幅自动拉取显示。

六、参数速查表（全部参数）

类别	参数
呼号/地点	call（对方呼号）、toqth（对方QTH）、mycall（我的呼号）、op（操作员）、qth（我的QTH）
时间	date / day / month / year / utc / time / bjt
通联	freq / rst / rig / trx / pwr / ant / mode / type / cfm / toqth
文案	rmks / qth
二维码	qr / qrcode / qrcap / qrcaption / cap / qrside
回卡请求	pse / tnx / t73 / vy73
备用信息	x1..x4 / x1name..x4name
行为控制	side / auto / tpl / page

📌 有参数传入则使用该参数，未传参的字段使用当前配置默认值。更多疑问可查看页面内「使用说明」或联系 BG9PZK。

← 返回首页（QSL 卡片制作工具）