API 开发文档

目录

① 概述与架构	② 快速开始	③ 签名算法
④ SSO 一键登录	⑤ 同步登录广播	⑥ 开放接口规范
⑦ 错误码总表	⑧ PHP SDK 参考	⑨ 安全规范与联调清单

① 概述与架构

壹证通 是统一用户管理中心（UCenter）：各接入平台不建独立用户体系，用户在任意平台注册一次即进入中心，之后可在所有平台一号通行。

┌──────────┐     ①注册/登录API      ┌──────────────────┐
│ 平台 A   │ ──────────────────────▶ │                  │
└──────────┘ ◀────────────────────── │  壹证通 UCenter   │
     ▲            用户信息+令牌        │  uc.3707.wang           │
     │②SSO跳转                        │                  │
     ▼      ③票据回跳/核验           └──────────────────┘
┌──────────┐ ──────────────────────▶        ▲
│ 平台 B   │ ◀──────────────────────        │ 中心免登Cookie
└──────────┘    （无需注册直接登录）    （一次登录，处处免密）

核心规则：

• 密码只存中心（加密存储），平台侧不存密码；平台通过 API 校验或 SSO 确认身份。
• 用户首次经某平台注册/登录/SSO 即自动绑定该平台；绑定关系决定平台可查询哪些用户。
• 所有接口走 HTTPS，需 app_id + 签名；密钥仅存于平台服务端，绝不前端暴露。

② 快速开始（5 步接入）

步骤	操作
1	管理员在 后台 → 应用管理 创建应用，获得 app_id 与 app_key（密钥仅存平台服务端配置）
2	平台「登录」按钮指向 SSO 入口（见 ④），回跳页用票据换取用户并建立平台本地会话 —— 最小可用接入即完成
3	（可选）平台自带注册/登录表单的，改调 user.register / user.login API（见 ⑥）
4	（推荐）密码登录成功后嵌入 uc_synlogin_script() 广播，让其它平台免密通行（见 ⑤）
5	在 后台 → API 调试台 联调自测，再上线

PHP 平台直接用 SDK：下载 uc_client.php，然后：

require 'uc_client.php';
uc_init('https://uc.3707.wang', '你的app_id', '你的app_key');
// 登录按钮
<a href="<?= uc_sso_url('https://你的平台/sso.php') ?>">登录</a>
// 回跳页开头
if ($user = uc_handle_sso()) { $_SESSION['uid'] = $user['uid']; header('Location: /'); exit; }

③ 签名算法（必读）

每个请求须携带 action、app_id、ts（10 位秒级时间戳）、sign：

data = 请求字段中除 action / ts / sign 外的全部字段，按 key 升序排序（ksort）
sign = sha256( app_id + "|" + app_key + "|" + ts + "|" + md5(json_encode(data, JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_SLASHES)) )

服务端校验规则：ts 与服务器时间差 ≤ 300 秒；sign 使用 hash_equals 恒时比较。data 为空对象时同样参与计算（md5("{}")，注意空数组在 PHP 中需强制 (object)[] 或直接传 {}）。

各语言参考实现：

# Python
import json, hashlib, time
def uc_sign(app_id, app_key, data):
    ts = str(int(time.time()))
    payload = json.dumps(data, ensure_ascii=False, separators=(',', ':'), sort_keys=True)
    sign = hashlib.sha256(f"{app_id}|{app_key}|{ts}|".encode() +
                          hashlib.md5(payload.encode()).hexdigest().encode()).hexdigest()
    return {'action': ACTION, 'app_id': app_id, 'ts': ts, 'sign': sign, **data}

// Node.js
const crypto = require('crypto');
function ucSign(appId, appKey, data) {
  const ts = String(Math.floor(Date.now() / 1000));
  const payload = JSON.stringify(data, Object.keys(data).sort());
  const sign = crypto.createHash('sha256')
    .update(`${appId}|${appKey}|${ts}|${crypto.createHash('md5').update(payload).digest('hex')}`)
    .digest('hex');
  return { action: ACTION, app_id: appId, ts, sign, ...data };
}

注意：JSON 序列化必须不转义中文与斜杠（PHP 端用 JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_SLASHES），否则签名不一致。空参数请传 {}。

④ SSO 一键登录（推荐主流程）

入口：平台将用户重定向到

https://uc.3707.wang/sso.php?app_id=你的app_id&back=urlencode(回跳地址)

流程：

1. 中心已有登录态（中心 Cookie）→ 直接签发一次性票据并 302 回跳；无登录态 → 先到中心登录/注册页，完成后自动回跳。
2. 回跳地址形如：back?ticket=...&uid=...&ts=...&sign=...（sign = sha256(app_key|ticket|uid|ts)）。
3. 平台二选一确认身份：本地验签（不联网，校验回跳 sign，ts 差 ≤300 秒）；或调 ticket.verify 核销票据（一次性，同时返回 7 天 token）。
4. 建立平台本地会话，登录完成。绑定关系自动建立。

回跳参数	说明
ticket	64 位一次性票据，120 秒内有效、仅可核销一次
uid	中心用户 ID
ts	签发时间戳（10 位）
sign	sha256(app_key|ticket|uid|ts)

回跳地址必须 HTTPS，且必须在后台为该应用配置的「回跳白名单前缀」内（未配置白名单时仅允许应用自身域名）。

⑤ 同步登录广播（跨平台免密）

平台在账号密码登录成功后（SSO 流程无需此步，中心已有登录态），输出一段脚本把用户登录态广播到中心：

<?= uc_synlogin_script($uid) ?>
// 生成：<script src="https://uc.3707.wang/synlogin.php?app_id=..&uid=..&ts=..&sign=sha256(app_key|uid|ts)"></script>

中心校验签名后写入免登 Cookie（30 天）——此后用户访问任何接入平台，SSO 自动免密通行。退出登录时无需广播（各平台各自销毁本地会话即可，中心免登 Cookie 过期或用户在中心退出时失效）。

⑥ 开放接口规范

统一入口：POST https://uc.3707.wang/api.php（Content-Type: application/json，也兼容表单编码）。返回统一为：

成功：{"ok": true,  ...业务字段}
失败：{"ok": false, "error": "人类可读原因", "code": "机器错误码"}

通用参数：action（接口名）、app_id、ts、sign。以下仅列业务参数。

6.1 app.ping — 连通与密钥自检

参数	无业务参数
响应	app_name（应用名）、server_time。首次联调先用它验证密钥与签名实现正确。

6.2 user.register — 注册（平台内引导注册）

参数	必填	说明
username	是	2-32 位中文/字母/数字/_/-，全局唯一
password	是	6-64 位
email / phone / nickname	否	选填资料
响应	uid、username、token、expires_in（自动绑定本平台并登录）。用户名已存在 → user_exists（引导用户走登录）。

6.3 user.login — 登录校验

参数	必填	说明
username / password	是	账号密码（中心校验）
响应	用户公开信息（uid/username/nickname/email/phone/avatar/created_at）+ token / expires_in。通过即自动绑定本平台。

6.4 user.bind — 绑定存量用户（迁移老用户）

参数	必填	说明
username / password	是	用户在中心已有账号（如中心直接注册过），密码校验通过后绑定本平台
响应	同 user.login。用于平台已有用户体系的迁移：让老用户用中心账号关联。

6.5 user.exists — 用户名占用查询

参数	必填	说明
username	是	待查询用户名
响应	exists（bool）、uid。注册表单实时校验用。

6.6 ticket.verify — SSO 票据核销

参数	必填	说明
ticket	是	SSO 回跳获得的一次性票据
响应	用户公开信息 + token/expires_in。票据过期/已用/不属本应用 → bad_ticket。

6.7 token.verify — 平台令牌校验

参数	必填	说明
token	是	登录/票据时获得的平台令牌（当前 7 天有效）
响应	用户公开信息。令牌跨应用隔离，只能在本应用使用；用户被停用后立即失效。

6.8 user.info — 查询用户资料

参数	必填	说明
uid / username / token	三选一	查询目标
响应	user 对象（uid/username/nickname/email/phone/avatar/created_at）。仅限已绑定本平台的用户。

6.9 user.changepwd — 修改密码

参数	必填	说明
username / old_password / new_password	是	新密码 6-64 位
响应	成功后全平台登录密码同步生效。

6.10 syn.logout — 同步登出

参数	必填	说明
token	是	销毁该平台的令牌（用户在平台点退出时调用）

6.11 app.stats — 应用自查统计

响应	binds 绑定用户数、tokens_active 活跃令牌、registers_7d / logins_7d / sso_7d 近 7 天注册/登录/SSO 次数、server_time。

调用示例（curl）

curl -s https://uc.3707.wang/api.php \
  -H 'Content-Type: application/json' \
  -d '{"action":"user.login","app_id":"demo_a","username":"test01","password":"xxx","ts":"1710000000","sign":"按③计算"}'

⑦ 错误码总表

code	含义	平台建议处理
no_app / app_not_found	app_id 缺失或不存在	检查配置
app_disabled	应用已被中心停用	联系管理员
no_action / unknown_action	action 缺失或不存在	检查接口名
bad_ts / ts_expired	时间戳缺失 / 偏差超 300 秒	校准服务器时间（NTP）
sign_error	签名不匹配	核对 app_key 与签名算法③
bad_username / bad_password	用户名/密码格式不合规	前端校验提示
user_exists	用户名已被占用	引导直接登录
user_not_found	用户不存在	提示注册
not_bound	用户未绑定本平台	引导从本平台登录一次自动绑定
bad_credentials	账号或密码错误	统一提示，勿区分账号/密码
user_disabled	账号被停用	提示联系管理员
locked	同 IP 失败过多（10 分钟 ≥10 次）	提示稍后再试
bad_ticket	票据无效/已使用/过期	重新走 SSO
bad_token	令牌无效/过期	重新登录
register_closed	中心已关闭自助注册	提示联系管理员
network / bad_response	SDK 侧网络/响应异常	重试并告警

⑧ PHP SDK 参考

下载：/sdk/uc_client.php.txt（另存为 uc_client.php）。函数清单：

函数	说明
uc_init($url, $app_id, $app_key)	初始化（一次即可）
uc_api($action, $data)	通用调用，返回数组（ok=true/false）
uc_register($u, $p, $extra=[])	注册（自动绑定本平台）
uc_login($u, $p)	登录校验（自动绑定本平台）
uc_bind($u, $p)	绑定存量用户（迁移）
uc_exists($username)	用户名是否已存在（bool）
uc_sso_url($back_url)	SSO 跳转地址
uc_handle_sso()	回跳页处理票据 → 用户数组或 null
uc_callback_verify()	回跳参数本地验签（不联网）
uc_check_token($token)	校验令牌 → 用户数组或 null
uc_user_info($uid或$username)	查用户资料
uc_change_password($u, $old, $new)	改密（全平台生效）
uc_logout($token)	同步登出
uc_synlogin_script($uid)	同步登录广播脚本（登录成功后 echo）
uc_app_stats()	本平台接入统计
uc_ping()	连通与密钥自检

其它语言平台按 ③ 签名算法 自行实现（一次 HTTPS POST 即可）；完整离线文档：api-docs.md（Markdown 版）。

⑨ 安全规范与联调清单

接口有新增或变更会在本页与后台公告同步；对接支持请联系 壹证通 管理员。