API 文档 · 微信统一登录网关

接口概览

方法	路径	调用方	说明
GET	`/oauth/authorize`	浏览器	业务站跳转发起微信授权。
POST	`/api/user/info`	业务后端	用一次性 ticket 换取用户资料。
GET	`/api/ping`	任意	健康检查，返回 pong。

统一响应结构： code 为业务状态码，msg 为说明，成功时附带 data。HTTP 状态码统一为 200，请以 code 字段判断结果。

鉴权方式

换取用户资料的接口需要项目凭证。支持两种传递方式，任选其一：

请求体：client_id、client_secret 作为表单字段。
请求头：X-Client-Id、X-Client-Secret。

client_secret 严禁出现在浏览器端。 换票请求必须由业务后端发起；前端只需要把回调带回的 ticket 交给后端。

发起授权

GET /oauth/authorize

由业务站点将用户浏览器重定向到该地址，网关校验通过后跳转微信扫码页。

参数	类型	必填	说明
`client_id`	string	是	项目凭证 ID，格式 `ak_...`。
`redirect_url`	string	否	授权完成后的回跳地址，需 URL 编码，域名必须在项目白名单内。
`state`	string	建议	业务方随机串，网关原样带回，用于防 CSRF。

授权成功后，浏览器会回到 redirect_url，并附加参数：

callback URL

https://wx.is3.cn/callback.php?code=32位一次性ticket&state=你的state

ticket 有效期默认 300 秒，只能使用一次。业务后端应在回调中立即换票，不要把 ticket 存起来延迟处理。

换取用户资料

POST /api/user/info 也支持 GET

业务后端凭 client_secret 与 ticket 换取微信用户资料，ticket 消费后立即失效。

请求参数

参数	类型	必填	说明
`client_id`	string	是	项目凭证 ID。
`client_secret`	string	是	项目密钥，仅服务端保存。
`code`	string	是	回调带回的一次性 ticket。

成功响应

200 OK

{
  "code": 200,
  "msg": "ok",
  "data": {
    "openid": "oX7Kj5xxxxxxxxxxxxxxxxxxxx",
    "unionid": "uN9Yt2xxxxxxxxxxxxxxxxxxxx",
    "nickname": "微信用户",
    "avatar": "https://thirdwx.qlogo.cn/.../132",
    "sex": 1,
    "country": "中国",
    "province": "广东",
    "city": "深圳"
  }
}

字段说明

字段	类型	说明
`openid`	string	用户在微信开放平台下的唯一标识，同一应用固定不变。
`unionid`	string	同一开放平台账号下的统一用户标识，可能为空。
`nickname`	string	微信昵称，可能为空字符串。
`avatar`	string	头像地址，可能为空字符串。
`sex`	int	1 男、2 女、0 未知。
`country`	string	国家。
`province`	string	省份。
`city`	string	城市。

健康检查

GET /api/ping

用于监控网关是否可用，无需鉴权。

200 OK

{
  "code": 200,
  "msg": "pong",
  "data": {
    "time": "2026-10-17 12:00:00"
  }
}

错误码

code	msg	处理建议
`200`	ok	成功。
`40001`	参数缺失	检查 client_id、client_secret、code 是否都已传递。
`40002`	凭证校验失败	核对 client_id / client_secret，确认项目未被停用且审核已通过。
`40003`	code 无效	ticket 过期、已使用或不属于该项目，引导用户重新登录。
`50000`	服务器内部错误	查看网关日志与微信接口返回，稍后重试。

授权页失败时不会返回 JSON，而是在浏览器展示失败原因，例如：

无效的 client_id，或该项目已被停用
redirect_url 不合法：必须是 http(s) 绝对地址，且域名需在项目白名单内
state 校验失败或已过期，请重新发起登录
网关尚未配置微信 AppID / AppSecret

调用示例

cURL

shell

curl -X POST 'https://login.fps5.cn/api/user/info' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=ak_你的client_id' \
  -d 'client_secret=sk_你的client_secret' \
  -d 'code=回调带回的ticket'

PHP

$ch = curl_init('https://login.fps5.cn/api/user/info');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'client_id'     => 'ak_你的client_id',
        'client_secret' => 'sk_你的client_secret',
        'code'          => $_GET['code'] ?? '',
    ]),
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($json['code'] ?? 0) === 200) {
    $user = $json['data'];
}

Node.js

JavaScript

const body = new URLSearchParams({
  client_id: 'ak_你的client_id',
  client_secret: 'sk_你的client_secret',
  code: req.query.code,
});

const resp = await fetch('https://login.fps5.cn/api/user/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body,
});
const json = await resp.json();
if (json.code === 200) {
  const user = json.data;
}

Java

HttpClient client = HttpClient.newHttpClient();

String form = "client_id=" + URLEncoder.encode(clientId, StandardCharsets.UTF_8)
        + "&client_secret=" + URLEncoder.encode(clientSecret, StandardCharsets.UTF_8)
        + "&code=" + URLEncoder.encode(ticket, StandardCharsets.UTF_8);

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://login.fps5.cn/api/user/info"))
        .header("Content-Type", "application/x-www-form-urlencoded")
        .POST(HttpRequest.BodyPublishers.ofString(form))
        .build();

HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());

在线调试

填入项目凭证与一次真实回调得到的 ticket，直接在浏览器验证接口返回。调试会真实消费 ticket，请勿重复提交同一个值。

请求结果会显示在这里

注意：在线调试会把 client_secret 提交到本网关，请仅在你自己的设备上使用。公共电脑调试后建议重置项目密钥。

安全建议

client_secret 只保存在业务后端，不下发浏览器、不写入前端日志。
业务回调必须校验 state，失败时不要建立登录态。
使用 unionid 作为跨站用户主键时，处理为空的情况（降级为 openid）。
不要把 ticket 拼进日志或监控上报，避免被他人复用。
发现密钥泄露时，立即在后台重置 client_secret。
生产环境关闭模拟模式，并定期检查授权日志中的异常来源。