中转登录开放平台 · 接入文档

0中转登录开放平台

1快速开始

2对接凭据

3签名机制

签名步骤

1. 收集所有业务参数（app_id、timestamp、nonce 以及接口自身的其他参数，不含 sign），过滤掉空值。
2. 按参数名字典序排序。
3. 拼成 key1=urlencode(value1)&key2=urlencode(value2) 格式（rawurlencode）。
4. 使用 App Secret 作为 key，对拼接串做 HMAC-SHA256，输出小写 hex。

签名示例（PHP）

// 1. 准备参数
$params = [
    'app_id'    => 'a1b2c3d4e5f60789',
    'cross_site' => 'https://your-site.com/callback',
    'timestamp'  => time(),
    'nonce'      => bin2hex(random_bytes(16)),
];

// 2. 过滤空值 + 字典序排序
$params = array_filter($params, fn($v) => $v !== '' && $v !== null);
ksort($params);

// 3. 拼接（rawurlencode）
$parts = [];
foreach ($params as $k => $v) {
    $parts[] = $k . '=' . rawurlencode((string)$v);
}
$signStr = implode('&', $parts);

// 4. HMAC-SHA256
$appSecret = '你的AppSecret';
$sign = hash_hmac('sha256', $signStr, $appSecret);

// 5. 最终请求携带 sign
$params['sign'] = $sign;

签名示例（Python）

# 与 PHP 一致：值用 rawurlencode（RFC 3986，保留 -_.~）
import hmac, hashlib, time, secrets, urllib.parse

APP_ID = "a1b2c3d4e5f60789"
APP_SECRET = "你的AppSecret"

def sign(params, secret):
    p = {k: v for k, v in params.items() if v not in ("", None)}
    raw = "&".join(
        k + "=" + urllib.parse.quote(str(p[k]), safe="-_.~")
        for k in sorted(p)
    )
    return hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest()

签名示例（Node.js）

const crypto = require('crypto');

const APP_ID = 'a1b2c3d4e5f60789';
const APP_SECRET = '你的AppSecret';

function sign(params, secret) {
  const filtered = {};
  for (const k in params) {
    if (params[k] !== '' && params[k] !== null) filtered[k] = params[k];
  }
  const raw = Object.keys(filtered).sort()
    .map(k => k + '=' + encodeURIComponent(String(filtered[k]))).join('&');
  return crypto.createHmac('sha256', secret).update(raw).digest('hex');
}

4在线调试

5接口一：发起登录跳转

请求参数

回调返回（重定向到您的 cross_site）

https://your-site.com/callback?token=2f8e3b...&from=qq_login_api

6接口二：Token 交换用户信息

请求参数

响应示例

{
  "code": 200,
  "message": "Token验证成功",
  "data": {
    "is_login": true,
    "user": {
      "id": 128,
      "nickname": "小明",
      "avatar": "https://thirdqq.qlogo.cn/.../100",
      "gender": 1,
      "qq_openid": "A1B2C3D4E5F6..."
    }
  },
  "timestamp": 1722585600
}

错误码

完整对接示例（服务端：Python）

import time, secrets, urllib.parse, urllib.request, json, hmac, hashlib

APP_ID = "a1b2c3d4e5f60789"
APP_SECRET = "你的AppSecret"
BASE = "https://your-platform.com"  # 换成你的部署域名

def sign(params):
    p = {k: v for k, v in params.items() if v not in ("", None)}
    raw = "&".join(k + "=" + urllib.parse.quote(str(p[k]), safe="-_.~") for k in sorted(p))
    return hmac.new(APP_SECRET.encode(), raw.encode(), hashlib.sha256).hexdigest()

# 1) 生成登录跳转链接，把用户 302 重定向到这里
login = {
    "app_id": APP_ID,
    "cross_site": "https://your-site.com/callback",
    "timestamp": int(time.time()),
    "nonce": secrets.token_hex(16),
}
login["sign"] = sign(login)
login_url = BASE + "/login.php?" + urllib.parse.urlencode(login)

# 2) 用户跳回 your-site.com/callback?token=xxx 后，服务器端换用户信息
def exchange(token):
    p = {"token": token, "app_id": APP_ID,
         "timestamp": int(time.time()), "nonce": secrets.token_hex(16)}
    p["sign"] = sign(p)
    url = BASE + "/api.php?action=exchange_token&" + urllib.parse.urlencode(p)
    with urllib.request.urlopen(url) as r:
        return json.loads(r.read().decode())

完整对接示例（服务端：Node.js）

const crypto = require('crypto');
const https = require('https');

const APP_ID = 'a1b2c3d4e5f60789';
const APP_SECRET = '你的AppSecret';
const BASE = 'https://your-platform.com';  // 换成你的部署域名

function sign(params) {
  const f = {};
  for (const k in params) if (params[k] !== '' && params[k] !== null) f[k] = params[k];
  const raw = Object.keys(f).sort()
    .map(k => k + '=' + encodeURIComponent(String(f[k]))).join('&');
  return crypto.createHmac('sha256', APP_SECRET).update(raw).digest('hex');
}

// 1) 生成登录跳转链接
function buildLoginUrl() {
  const p = { app_id: APP_ID, cross_site: 'https://your-site.com/callback',
    timestamp: Math.floor(Date.now() / 1000), nonce: crypto.randomBytes(16).toString('hex') };
  p.sign = sign(p);
  return BASE + '/login.php?' + new URLSearchParams(p).toString();
}

// 2) 回调拿到 token 后，服务器端换取用户信息
function exchange(token) {
  const p = { token, app_id: APP_ID, timestamp: Math.floor(Date.now() / 1000), nonce: crypto.randomBytes(16).toString('hex') };
  p.sign = sign(p);
  const url = BASE + '/api.php?action=exchange_token&' + new URLSearchParams(p).toString();
  return new Promise((resolve, reject) => {
    https.get(url, res => {
      let d = ''; res.on('data', c => d += c);
      res.on('end', () => resolve(JSON.parse(d)));
    }).on('error', reject);
  });
}

7接口三：查询用户信息

请求参数

响应示例

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "user": {
      "id": 128,
      "nickname": "小明",
      "avatar": "https://thirdqq.qlogo.cn/.../100",
      "gender": 1,
      "qq_openid": "A1B2C3D4E5F6...",
      "last_login_time": "2026-08-02 10:23:45"
    }
  },
  "timestamp": 1722585600
}

错误码

8通用响应结构

{
  "code": 200,
  "message": "说明文本",
  "data": { /* 业务数据 */ },
  "timestamp": 1722585600
}

9辅助接口