把微信扫码登录开放给其他项目

公共服务平台已封装微信开放平台扫码登录，优货通、AI 项目等公司产品无需自建微信对接，凭 clientId + clientSecret 即可获得登录二维码，并通过回调跳回业务系统完成登录。

Base URL：https://yht.szhsy123.cn/auth-api/v1

1在线测试台

clientId

returnUrl（必填，扫码后跳回地址）

state（可选，透传参数）

扫码成功后会直接跳回该地址并携带一次性 code 与 state；returnUrl 域名必须配置在客户端白名单中。

点击“生成登录二维码”，这里会显示微信扫码页面。
测试密钥只用于联调，正式项目请注册专属客户端。

过期时间

授权链接

扫码成功后，浏览器会跳回 returnUrl。业务系统后端凭回调中的一次性 code 与客户端密钥调用 /wechat/token 换领身份，密钥不能出现在前端。

等待操作…

2对接流程

外部项目前端调用 POST /wechat/qr，传入已配置白名单的 returnUrl，获得 authorizeUrl。
用 iframe 或二维码组件展示 authorizeUrl，用户扫码并在微信中确认。
扫码确认后，认证平台将浏览器 302 跳回 returnUrl?code=一次性授权码&state=透传参数。
业务后端凭 code + clientId + clientSecret 调用 POST /wechat/token，换领 accessToken 与微信身份（openid/unionid）。
后续需要校验时调用 POST /wechat/verify。

唯一扫码模式：returnUrl 为必填项，域名须在客户端白名单内；不再提供前端轮询或 ticket 换领身份。

3接口文档

接口	方法	调用方	说明
`/auth-api/v1/wechat/status`	GET	任意	网关配置状态
`/auth-api/v1/wechat/qr`	POST	外部前端	创建登录二维码
`/auth-api/v1/wechat/callback`	GET	微信回调	微信授权回调（浏览器跳转）
`/auth-api/v1/wechat/token`	POST	外部后端	一次性 code 换领身份令牌
`/auth-api/v1/wechat/verify`	POST	外部后端	校验 accessToken
`/auth-api/v1/clients`	POST / GET	平台管理员	注册 / 查看客户端
`/auth-api/v1/clients/{clientId}/return-domains`	PUT	平台管理员	更新回调域名白名单
`/auth-api/v1/clients/{clientId}/reset-secret`	POST	平台管理员	重置客户端密钥
`/auth-api/v1/clients/{clientId}/status`	PATCH	平台管理员	启用 / 停用客户端

POST/auth-api/v1/wechat/qr外部前端调用

请求

{
  "clientId": "ai-ceo",
  "returnUrl": "https://app.szhsy123.cn/login?from=wx",
  "state": "第三方自定义透传参数"
}

说明

returnUrl 必填，域名必须在客户端白名单内，生产环境需 HTTPS；state 可选并会原样透传回业务系统。

响应

{
  "authorizeUrl": "https://open.weixin.qq.com/connect/qrconnect?...",
  "expiresIn": 600
}

POST/auth-api/v1/wechat/token外部后端调用

请求

{
  "code": "回调带回来的一次性授权码",
  "clientId": "ai-ceo",
  "clientSecret": "外部项目持有的密钥"
}

code 为回调返回的一次性授权码，只能使用一次。

响应

{
  "accessToken": "F0kP...",
  "expiresIn": 86400,
  "openid": "oX4y...",
  "unionid": "oU7w...",
  "nickname": "张三",
  "avatarUrl": "https://thirdwx.qlogo.cn/..."
}

curl 示例

curl -X POST https://yht.szhsy123.cn/auth-api/v1/wechat/token \
  -H 'Content-Type: application/json' \
  -d '{"code":"<callback-code>","clientId":"ai-ceo","clientSecret":"<clientSecret>"}'

POST/auth-api/v1/wechat/verify外部后端调用

请求

{"accessToken": "F0kP..."}

响应

{
  "valid": true,
  "clientId": "ai-ceo",
  "openid": "oX4y...",
  "unionid": "oU7w...",
  "expiresIn": 3600
}

4客户端管理（平台管理员）

先在公共服务平台管理后台登录管理员账号，再调用以下接口（请求头带 X-Admin-Token）。clientSecret 只在创建和重置时返回一次。

操作	方法	示例
注册客户端	POST `/auth-api/v1/clients`	`{"clientId":"ai-ceo","name":"AI-CEO 项目","allowedReturnDomains":["szhsy123.cn"]}`
查看列表	GET `/auth-api/v1/clients`	-
更新回调白名单	PUT `/auth-api/v1/clients/{clientId}/return-domains`	`{"allowedReturnDomains":["szhsy123.cn"]}`
重置密钥	POST `/auth-api/v1/clients/{clientId}/reset-secret`	-
启用/停用	PATCH `/auth-api/v1/clients/{clientId}/status`	`{"status":"DISABLED"}`

5前端接入示例

const resp = await fetch('/auth-api/v1/wechat/qr', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientId: 'ai-ceo',
    returnUrl: 'https://app.szhsy123.cn/login?from=wx', // 方式二：扫码后跳回
    state: 'session-' + Date.now()
  })
});
const { authorizeUrl } = await resp.json();

// 在页面中展示二维码（iframe 或 qrcode 组件渲染 authorizeUrl）

// 扫码确认后浏览器自动跳回 returnUrl，登录页读取 code：
const params = new URLSearchParams(window.location.search);
const code = params.get('code');
if (code) {
  await fetch('/api/login-by-wechat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code })
  });
  window.location.href = '/dashboard';
}

// 业务后端用 code + clientId + clientSecret 换领身份后建立自己的登录会话。

6错误码

错误码	HTTP	说明
`CLIENT_NOT_FOUND`	404	客户端不存在
`CLIENT_DISABLED`	403	客户端已停用
`INVALID_CLIENT_CREDENTIALS`	401	clientSecret 错误
`WECHAT_NOT_CONFIGURED`	503	微信凭据未配置
`INVALID_RETURN_URL`	400	returnUrl 缺失、不安全或不在白名单
`CODE_INVALID`	400	一次性 code 缺失
`CALLBACK_CODE_NOT_FOUND`	404	回调 code 不存在或已失效
`CALLBACK_CODE_USED`	409	回调 code 已被使用
`INVALID_TOKEN`	401	accessToken 无效或过期
`RATE_LIMITED`	429	触发限流

7安全说明

clientSecret 只保存在外部项目后端和公共服务平台服务器，禁止出现在前端代码中。
公共服务平台只保存密钥、回调 code、state、accessToken 的 SHA-256 哈希。
跳回模式的 returnUrl 域名必须命中客户端白名单，扫码回调时二次校验，防止开放重定向。
回调 code 单次使用、10 分钟过期；accessToken 默认 24 小时过期。
客户端注册、重置密钥、启用停用均需平台管理员权限并写入审计日志。
生产环境必须全链路 HTTPS。