Open API 授权接入指南

1. 概述

本文档为第三方开发者提供 Open API 平台的授权接入指南。

模式	适用场景	复杂度
Secret 令牌模式	服务器端对服务器端的 API 调用	简单
OAuth2 扫码授权模式	需要用户主动授权的第三方应用	完整

2. 接入流程概览

2.1 模式一：Secret 令牌模式（推荐用于服务端调用）

适用于服务器后端之间的 API 调用，最简单直接。

请求示例：

响应示例：

{
  "code": 0,
  "message": "success",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

获取到 accessToken 后，在调用其他 API 时携带令牌：

2.2 模式二：OAuth2 扫码授权（适用于第三方应用）

适用于需要用户主动授权才能调用的第三方应用，完整流程如下：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  第三方应用   │     │   PC端      │     │   手机端     │     │   平台服务    │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ 1.申请appCode     │                   │                   │
       │<─────────────────>│                   │                   │
       │                   │                   │                   │
       │ 2.构造授权链接     │                   │                   │
       │──────────────────>│                   │                   │
       │                   │                   │                   │
       │                   │ 3.请求授权         │                   │
       │                   │───────────────────────────────────────>
       │                   │                   │                   │
       │                   │ 4.返回二维码       │                   │
       │                   │                   │                   │
       │                   │<──────────────────────────────────────│
       │                   │                   │                   │
       │                   │ 5.显示二维码       │                   │
       │                   │<──────────────────│                   │
       │                   │                   │                   │
       │                   │                   │ 6.用户扫码         │
       │                   │                   │──────────────────>│
       │                   │                   │                   │
       │                   │                   │                   │
       │                   │                   │ 7.用户确认授权     │
       │                   │                   │──────────────────>│
       │ 10.授权成功，      │                   │                   │       
       │    重定向          │                   │                   │
       │<──────────────────────────────────────│                   │
       │                   │                   │                   │
       │ 11.用授权码换取用户信息│                │                   │
       │  (含clientSecret)  │                  │                   │
       │──────────────────>│                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
       │ 12.用secret调用API  │                 │                   │
       │<──────────────────>│                  │                   │

3. 接入前准备

3.1 申请应用信息

第三方开发者需要先向平台申请，平台将创建应用并提供以下信息：

参数	说明
`appCode`	应用唯一业务标识，用于构造授权链接

3.2 配置回调地址

需要在平台配置授权成功的回调地址（redirectUri），第三方应用需确保该地址可正常访问。

4. 授权流程详解

4.1 第一步：构造授权链接

第三方应用引导用户访问授权页面，构造如下链接：

授权发起地址：https://auth.qunjielong.com/authorize

请求参数：

参数	类型	必填	说明
`appCode`	String	是	从平台获取的应用唯一标识
`redirect_uri`	String	是	授权成功后的回调地址（需与平台配置一致）
`response_type`	String	否	固定值 `code`，默认可不传
`scope`	String	否	授权作用域，默认 `oauth_login`
`state`	String	是	状态参数，用于防止 CSRF 攻击

构造示例：

https://auth.qunjielong.com/authorize?appCode=YOUR_APP_CODE&redirect_uri=https://your-app.com/callback&response_type=code&scope=oauth_login&state=random_state_string

4.2 第二步：用户扫码授权

PC 端显示二维码，用户使用微信扫描二维码。

4.3 第三步：获取授权码

用户确认授权后，平台会：

生成 authorization_code

根据回调地址进行重定向

回调重定向格式：

{redirect_uri}?code={authorization_code}&state={state}

示例：

https://your-app.com/callback?code=auth_code_xxx&state=random_state_string

4.4 第四步：换取用户信息

第三方应用收到授权码后，调用接口换取用户信息：

接口地址：GET /open/oauth2/user/info

请求参数：

参数	类型	必填	说明
`authCode`	String	是	授权码

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "ghId": 123456,
    "ghName": "主页名称",
    "ghIntro": "主页简介",
    "ghType": 1,
    "logoUrl": "https://platform.com/logo.png",
    "clientSecret": "client_secret_xxx"
  }
}

响应字段说明：

字段	说明
`ghId`	主页 ID
`ghName`	主页名称
`ghIntro`	主页简介
`ghType`	主页类型
`logoUrl`	主页图标
`clientSecret`	客户端密钥，后续调用 API 需要用到

重要：clientSecret 是后续调用 API 的凭证，请务必安全存储。

4.5 第五步：调用 API

获得 clientSecret 后，第三方应用即可使用该密钥调用其他 API 接口。

获取 Access Token：

接口地址：GET /open/auth/token

参数	类型	必填	说明
`secret`	String	是	客户端密钥

请求示例：

响应示例：

{
  "code": 0,
  "message": "success",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

调用其他 API：

获取到 accessToken 后，在请求头或参数中携带令牌访问其他 API：

5. 错误处理

5.1 错误码说明

错误码	说明	处理建议
`0`	成功	-
`-1`	系统错误	重试或联系技术支持
`400`	参数错误	检查请求参数是否正确
`401`	认证失败	检查 secret/token 是否有效
`403`	无权访问	检查应用权限配置
`404`	资源不存在	检查请求的资源
`500`	服务器内部错误	重试或联系技术支持

6. 安全建议

6.1 State 参数校验

发起授权时传递 state 参数，回调时验证其值，防止 CSRF 攻击：

6.2 ClientSecret 安全存储

clientSecret 是调用 API 的关键凭证，必须安全存储

推荐使用加密存储，不要明文保存在本地存储或日志中

使用 HTTPS 传输，避免中间人攻击

6.3 回调地址校验

确保 redirect_uri 与在平台配置的地址完全一致，包括协议、域名和路径。

7. 技术支持

如在集成过程中遇到问题，请提供以下信息联系技术支持：

错误码和错误信息

请求的完整 URL 和参数

发起请求的时间

应用的 appCode

授权接入指引

Open API 授权接入指南#

1. 概述#

2. 接入流程概览#

2.1 模式一：Secret 令牌模式（推荐用于服务端调用）#

2.2 模式二：OAuth2 扫码授权（适用于第三方应用）#

3. 接入前准备#

3.1 申请应用信息#

3.2 配置回调地址#

4. 授权流程详解#

4.1 第一步：构造授权链接#

4.2 第二步：用户扫码授权#

4.3 第三步：获取授权码#

4.4 第四步：换取用户信息#

4.5 第五步：调用 API#

5. 错误处理#

5.1 错误码说明#

6. 安全建议#

6.1 State 参数校验#

6.2 ClientSecret 安全存储#

6.3 回调地址校验#

7. 技术支持#

Open API 授权接入指南

1. 概述

2. 接入流程概览

2.1 模式一：Secret 令牌模式（推荐用于服务端调用）

2.2 模式二：OAuth2 扫码授权（适用于第三方应用）

3. 接入前准备

3.1 申请应用信息

3.2 配置回调地址

4. 授权流程详解

4.1 第一步：构造授权链接

4.2 第二步：用户扫码授权

4.3 第三步：获取授权码

4.4 第四步：换取用户信息

4.5 第五步：调用 API

5. 错误处理

5.1 错误码说明

6. 安全建议

6.1 State 参数校验

6.2 ClientSecret 安全存储

6.3 回调地址校验

7. 技术支持