QCS开放接口文档

QCS（QSL认证系统，QSL Certification System）对外开放接口文档：

基础信息

API地址

https://qcs.qsl.pub/api

基础响应模块

/**
 * API响应通用类型定义
 * @template T - 响应数据的类型
 */
export interface ApiResponse<T> {
  /** 响应数据 */
  data: T;
  /** 状态码 */
  code: number;
  /** 消息提示 */
  msg: string;
}

code状态码

状态码	描述
200	正常返回
500	系统错误
401	未授权
404	找不到资源

默认请求数据类型

application/json

默认响应数据类型

json

通用数据结构

StationItem

参数名称	参数说明	数据类型
id	台站ID	number
callsign	呼号	string
dxcc	DXCC实体	string
grid	网格	string
itu	ITU区域	string
cq	CQ区域	string
station_location	台站位置	string
first_qso_date	首次QSO时间（毫秒时间戳）	number
last_qso_date	最后QSO时间（毫秒时间戳）	number | null

QsoList

参数名称	参数说明	是否必须	数据类型
callsign	对方呼号	true	string
worked	我的呼号	true	string
date	通联时间（时间戳）	true	number
mode	模式	true	string
band	接收波段	true	string
band_tx	发送波段	false	string
freq	接收频率	true	number
freq_tx	发送频率	false	number
rst_rcvd	接收RST	true	string
rst_sent	发送RST	true	string
satellite	卫星名称	false	string
propagation	传播模式	false	string

OAuth模块

OAuth模块部分数据使用签名+加密传输。调用受保护接口时需要在请求头中携带：

Authorization: Bearer <access_token>

建议按以下顺序接入：获取授权码 -> 获取Token -> 刷新Token -> 调用资源接口。

OAuth授权码模式说明

• 当前仅支持 response_type=code
• 授权请求必须携带 state
• 当前支持两种 PKCE 方法：S256、SM3
• 授权码与 client_id、redirect_uri、scope、code_challenge 绑定
• 换取 token 时，必须提交原始 code_verifier

获取授权码

QCS 使用授权页完成用户登录、授权确认与授权码签发。第三方客户端应将用户浏览器跳转到 QCS 授权地址，并携带以下查询参数：

参数名称	参数说明	是否必须	数据类型
client_id	客户端ID	true	string
redirect_uri	回调地址，必须与应用登记值完全一致	true	string
response_type	固定为 code	true	string
scope	申请的权限范围，逗号分隔	true	string
state	客户端生成的随机态值，用于回调校验	true	string
code_challenge	PKCE 挑战值	true	string
code_challenge_method	PKCE 方法，支持 S256 / SM3	true	string

授权成功后，QCS 将通过 redirect_uri 回跳并附带：

参数名称	参数说明	数据类型
code	授权码	string
state	原样回传的 state	string

scope取值

scope	说明
basic	读取基础信息（openid、callsign）
station	读取台站列表
qsl	读取QSL统计信息
qso	导入QSO记录

获取Token

POST /oauth/token

请求说明

• 外层请求体使用“先 SM4-GCM 加密，再 SM2withSM3 签名”的方式传输
• code 作为外层明文字段传输
• data 中的 code 需与外层 code 保持一致

请求参数

参数名称	参数说明	是否必须	数据类型
code	授权码（明文）	true	string
iv	GCM 初始向量，base64；解码后为 12 字节随机值	true	string
data	加密后的明文请求体，base64	true	string
authtag	GCM 认证标签，base64	true	string
signature	签名值	true	string
timestamp	时间戳（秒）	true	number
nonce	随机字符串	true	string

data（明文解密后）

参数名称	参数说明	是否必须	数据类型
client_id	客户端ID	true	string
client_secret	客户端密钥	true	string
code	授权码，必须与外层 code 一致	true	string
redirect_uri	回调地址，必须与授权时一致	true	string
code_verifier	PKCE 原始校验串	true	string

响应参数

响应体同样使用签名 + SM4-GCM 加密；客户端需先验签，再按同一组参数解密。明文结构如下：

参数名称	参数说明	数据类型
access_token	访问令牌	string
refresh_token	刷新令牌	string
token_type	固定为 Bearer	string
expires_in	过期时间戳（秒）	number

刷新Token

POST /oauth/refresh_token

请求头

Authorization: Bearer <refresh_token>

说明

• refresh token 为一次性轮换凭证
• 刷新成功后，旧 refresh token 立即失效
• 客户端必须使用响应中的新 refresh token 覆盖本地旧值

响应参数

响应格式与 /oauth/token 相同，明文结构也相同。

请求说明

• 使用 refresh_token 作为 Bearer Token 调用
• 刷新成功后，旧 refresh token 立即失效
• 新的 access token / refresh token 会一起返回

获取用户信息

POST /oauth/userinfo

scope

basic

请求头

Authorization: Bearer <access_token>

请求说明

• 响应体使用签名 + SM4-GCM 加密

响应参数（明文解密后）

参数名称	参数说明	数据类型
openid	当前用户的 OAuth openid	string
callsign	当前用户呼号	string

获取QSL统计信息

POST /oauth/qsl_info

scope

qsl

请求头

Authorization: Bearer <access_token>

请求说明

• 响应体使用签名 + SM4-GCM 加密

响应参数（明文解密后）

参数名称	参数说明	数据类型
worked	主呼号	string
qso_total	QSO总数	number
qsl_total	QSL总数	number
latest_qsl_hash	最新QSL哈希	string | null
latest_qsl_date	最新QSL时间，毫秒时间戳	number | null

获取台站列表（OAuth）

POST /oauth/get_station_list

scope

station

请求头

Authorization: Bearer <access_token>

请求说明

• 响应体使用签名 + SM4-GCM 加密

响应参数（明文解密后）

响应为 StationItem[]。

导入QSO记录（OAuth）

POST /oauth/push_qso

scope

qso

请求说明

• 请求体使用签名 + SM4-GCM 加密
• data 解密后应为导入结构体 JSON

请求参数

参数名称	参数说明	是否必须	数据类型	schema
iv	加密向量（base64）	true	string
data	加密后的密文（base64）	true	string	data
authtag	GCM认证标签（base64）	true	string
signature	签名值	true	string
timestamp	时间戳（秒）	true	number
nonce	随机字符串	true	string

data（明文解密后）

参数名称	参数说明	是否必须	数据类型	schema
station_id	台站id	true	number
qso_list	qso列表	true	QsoList[]	QsoList

请求示例

{
  "iv": "...",
  "data": "...",
  "authtag": "...",
  "signature": "...",
  "timestamp": 1735660800,
  "nonce": "..."
}

响应示例

{
  "data": {
    "iv": "...",
    "data": "...",
    "authtag": "...",
    "signature": "...",
    "timestamp": 1735660800,
    "nonce": "..."
  },
  "code": 200,
  "msg": "success"
}

加密签名与验签解密

OAuth 加密接口（如 /oauth/token、/oauth/userinfo、/oauth/get_station_list、/oauth/qsl_info、/oauth/push_qso）统一采用同一套报文约定。

1. 整体流程

• 发送方先组装明文 JSON，再使用 SM4-GCM 加密，最后对密文做 SM2withSM3 签名
• 接收方先校验 timestamp、nonce、signature，验签通过后再执行 SM4-GCM 解密
• 请求与响应都遵循这一流程，只是双方使用的 SM2 密钥方向不同

2. 字段说明

字段	说明
iv	Base64 字符串，解码后必须为 12 字节随机值
data	业务明文经 SM4-GCM 加密后的密文，Base64 编码
authtag	SM4-GCM 认证标签，Base64 编码
signature	对 data|timestamp|nonce 进行 SM2withSM3 签名后的结果
timestamp	秒级 Unix 时间戳
nonce	每次请求/响应唯一的随机字符串，用于防重放
sn	对称密钥编号，参与 AAD 计算；无编号时使用空字符串

3. 明文封装格式

加密前，明文统一封装为：

{
  "data": { ...业务数据... },
  "_n": "<nonce>",
  "_appid": "<appid>",
  "_timestamp": 1735660800
}

其中：

• data 为真实业务数据
• _appid 必须与当前客户端 appid 一致
• _timestamp 必须与外层 timestamp 一致
• _n 建议与外层 nonce 保持一致

4. SM4-GCM 加密参数

• 对称算法：SM4-GCM
• 密钥：16 字节 SM4 密钥，接口传输和配置中统一使用 Base64 表示
• iv：12 字节随机值，Base64 编码后放入 iv
• authtag：GCM 输出的认证标签，Base64 编码后放入 authtag
• AAD 固定为：

{urlpath}|{appid}|{timestamp}|{sn}

说明：

• urlpath 为接口路径本身，例如 /oauth/token
• appid 为客户端 client_id
• timestamp 必须与报文外层字段一致
• sn 为对称密钥编号；如果接口场景没有编号，则传空字符串参与拼接

只要 urlpath、appid、timestamp、sn 任一项不一致，都会导致解密或认证失败。

5. 签名规则

签名原文固定为：

{data}|{timestamp}|{nonce}

签名说明：

• data 指加密后的密文字段，不是明文 JSON
• timestamp、nonce 取报文外层字段
• 签名算法为 SM2withSM3

5.1 SM2withSM3 兼容性要求

为避免不同语言/不同国密库之间互通失败，OAuth 模块在签名验签时建议按以下固定配置接入：

• 签名算法：SM2withSM3
• 公钥格式：未压缩公钥，04 开头的 130 位 Hex 字符串
• 私钥格式：32 字节私钥的 Hex 字符串
• 签名输出格式：推荐使用 DER 编码后再做 Base64
• 验签输入格式：推荐使用 DER 签名；当前接口兼容 DER 签名和 64 字节原始签名
• 用户标识（distid / userId）：固定为默认值 1234567812345678

其中签名值在本系统中的实际传输格式为：

Base64(DER(signature))

也就是说：

• 签名时，先生成 SM2 签名结果
• 将签名按 DER 编码
• 再将 DER 二进制做 Base64，作为 signature 字段传输

如果你的 SDK 支持“原始 64 字节签名”和“DER 编码签名”两种模式，优先选择 DER。

5.2 常见 SDK 配置提示

不同 SDK 的参数名可能不同，但语义建议对齐为：

• hash = true 或 useSm3 = true
• der = true
• userId / distId / id = "1234567812345678"
• 如果存在 cipherMode，在签名场景可忽略；在 SM2 加密场景建议选择 C1C3C2

JavaScript 接入推荐使用 sm-crypto-v2 国密库，签名常见写法可参考：

sign(data, privateKey, {
  hash: true,
  der: true,
})
// userId 默认即可

验签则保持同样的 hash/userId/der 语义。

6. 请求方向的密钥使用

客户端调用 QCS 加密接口时：

• 使用协商好的 SM4 密钥加密请求体
• 使用客户端自己的 SM2 私钥生成 signature
• QCS 使用客户端登记的 SM2 公钥验签

7. 响应方向的密钥使用

QCS 返回加密响应时：

• 使用同一把 SM4 密钥加密响应体
• 使用 QCS 平台 SM2 私钥生成 signature
• 客户端使用 QCS 平台 SM2 公钥验签

8. 接入建议

• 先固定一套测试参数，单独验证“加密 -> 签名 -> 验签 -> 解密”链路
• 优先确保 urlpath 与实际请求路径完全一致，包含前导 /
• 所有 Base64 字段均使用标准 Base64，不要混用 Base64URL
• nonce 每次请求都重新生成，不要复用
• 客户端与服务端时间应保持同步，避免因时钟漂移导致 timestamp 校验失败

PAT模块

PAT（Personal Access Token，个人访问令牌）由 QCS 个人中心创建并管理，对外仅开放使用接口。

• PAT 只能在创建时明文返回一次，请客户端自行安全保存
• push_qso_by_token 的业务数据使用 SM4-CBC + PKCS#7 加密，PAT 原文直接作为对称密钥使用

PAT加密传输约定

PAT 模式仅对业务数据做对称加密。

1. 整体流程

• 客户端持有 PAT 原文
• 调用方使用 PAT 原文作为 SM4-CBC 的密钥加密业务 JSON
• 请求时直接在 token 字段中传入 PAT 原文

2. 加密规则

• 对称算法：SM4-CBC
• 填充方式：PKCS#7
• 密钥：PAT 原文
• iv：16 字节随机值，Base64 编码后放入请求体 iv
• data：业务 JSON 加密后的密文，Base64 编码

3. 注意事项

• iv 必须每次重新生成，不能复用
• token 必须传 PAT 原文，不能传哈希值或掩码值
• token、iv、data 需保持匹配

获取QCS台站列表

POST /oauth/personal_access_tokens/get_station_list

请求参数

参数名称	参数说明	是否必须	数据类型
token	QCS 个人中心获取的 PAT	true	string

请求说明

• 该接口不需要 OAuth access token
• 直接使用 PAT 访问

请求示例

{
  "token": "MTIzNDU2"
}

响应参数

响应为 StationItem[]。

响应示例

{
  "data": [
    {
      "id": 1,
      "callsign": "BG7ZAG",
      "dxcc": "83",
      "grid": "OL50da",
      "itu": "44",
      "cq": "24",
      "station_location": "中国-海南",
      "first_qso_date": 1735660800000,
      "last_qso_date": null
    }
  ],
  "code": 200,
  "msg": "success"
}

导入QSO记录（PAT）

POST /oauth/personal_access_tokens/push_qso_by_token

请求参数

参数名称	参数说明	是否必须	数据类型	schema
token	QCS 个人中心获取的 PAT	true	string
iv	加密向量（16字节随机IV转 base64）	true	string
data	加密数据（json字符串密文）	true	string	data

请求说明

• 该接口不需要 OAuth access token
• data 使用 SM4-CBC + PKCS#7 加密
• 解密密钥直接使用 PAT 原文
• iv 为 16 字节随机值的 Base64 表示

data

参数名称	参数说明	是否必须	数据类型	schema
station_id	台站id	true	number
qso_list	qso列表	true	QsoList[]	QsoList

请求示例

{
  "token": "MTIzNDU2",
  "iv": "w==",
  "data": "..."
}

const data = {
  station_id: 1,
  qso_list: [
    {
      callsign: "BG7ZAG",
      worked: "BG7ZAG",
      date: 1735660800000,
      mode: "SSB",
      band: "160m",
      freq: 160000000,
      rst_rcvd: "59",
      rst_sent: "59",
      satellite: null,
      propagation: null
    }
  ]
}

响应示例

{
  "data": "提交成功",
  "code": 200,
  "msg": "success"
}