主题
9.1 JoyInside 用户体系接入指南(后端)
本文档将帮助您快速完成接入,实现用户绑定和设备绑定功能。
一、接入准备
在开始接入前,请确保您已完成以下准备工作。
1.1 前置条件
| 条件 | 说明 | 如何获取 |
|---|---|---|
| 厂商账号 | 已完成商务合作签约 | 联系商务团队开通 |
| 服务端开发能力 | 支持HTTPS接口调用 | - |
| 微信小程序 | 已上线或处于开发阶段 | 微信公众平台 |
1.2 密钥申请
接入前,您需要获取以下密钥信息:
| 密钥名称 | 说明 | 用途 | 获取方式 |
|---|---|---|---|
| accessKeyId | 访问密钥ID | 接口身份标识 | 联系技术支持申请 |
| accessKeySecret | 访问密钥密文 | 签名计算(请妥善保管) | 联系技术支持申请 |
| vendorId | 厂商唯一标识 | 区分不同厂商 | 联系技术支持申请 |
重要提示:
- accessKeySecret 相当于您的"密码",请勿在客户端代码中暴露
- 密钥一旦泄露,请立即联系技术支持重新生成
1.3 环境说明
| 环境 | API地址 | 用途 |
|---|---|---|
| 正式环境 | https://api.joyinside.com | 生产使用 |
| 测试环境 | 联系技术支持获取 | 开发调试 |
建议:开发阶段先在测试环境验证,确认无误后再切换到正式环境。
二、快速开始
本节将帮助您快速跑通最简单的接入流程。完成本节后,您将能够获取用户信息。
2.1 整体流程概览
2.2 最简接入示例(5步完成)
步骤1:准备签名参数
python
# Python示例
import time
import uuid
import hmac
import hashlib
import binascii
# 您的密钥信息(请替换为实际值)
accessKeyId = '您的accessKeyId'
accessKeySecret = '您的accessKeySecret'
# 生成认证参数
params = {
"accessVersion": "V2",
"accessTimestamp": str(int(round(time.time() * 1000))), # 当前时间戳
"accessNonce": str(uuid.uuid4()), # 随机数
"accessKeyId": accessKeyId
}
# 计算签名(详见第三章)
def generate_sign(params, secret):
lower_key_params = {k.lower(): params[k] for k in params}
sorted_params = sorted(lower_key_params.items(), key=lambda x: x[0])
joint_params = '&'.join([f'{k}={v}' for k, v in sorted_params])
h = hmac.new(secret.encode('utf-8'), joint_params.encode('utf-8'), digestmod=hashlib.md5)
return binascii.hexlify(h.digest()).decode('utf-8')
params['accessSign'] = generate_sign(params, accessKeySecret)
print(f"签名参数: {params}")步骤2:获取访问令牌
python
import requests
# 调用getToken接口
response = requests.post(
'https://api.joyinside.com/auth/getToken',
json={
**params,
'vendorId': '您的vendorId' # 或使用 botId
}
)
result = response.json()
token = result.get('accessToken')
print(f"获取到的Token: {token}")预期结果:
json
{
"accessToken": "ehuc2065edbru==",
"expireIn": 7200,
"code": 0
}步骤3:小程序拉起半屏小程序
javascript
// 微信小程序端代码
function launchHalfScreen(token) {
wx.openEmbeddedMiniProgram({
appId: 'wx1234567890abcdef', // 半屏小程序AppId(联系技术支持获取)
path: '/pages/auth/index',
extraData: {
token: token,
vendorId: '您的vendorId'
}
});
}步骤4:验证接入成功
当半屏小程序成功打开并显示用户信息时,说明接入成功!
三、核心概念说明
在开始详细接入前,理解以下概念会让您事半功倍。
3.1 签名机制
什么是签名?为什么需要签名?
签名是一种安全验证机制,用于确保请求来源可信、未被篡改。
签名的作用:
- 防篡改:任何参数变化都会导致签名验证失败
- 防重放:时间戳超过5分钟的请求会被拒绝
- 身份认证:只有持有密钥的人才能生成有效签名
3.2 Token(访问令牌)
什么是Token?
Token 是用户身份的临时凭证,类似于"入场券"。获取Token后,您可以在有效期内使用它访问其他接口。
| 属性 | 说明 |
|---|---|
| accessToken | 访问令牌,有效期2小时 |
| refreshToken | 刷新令牌,有效期7天,用于获取新的accessToken |
Token使用方式:
方式一:通过请求头传递(推荐)
Authorization: Bearer {token}方式二:通过请求体传递
json
{
"token": "{token}",
"vendorUid": "xxx"
}3.3 用户标识体系
为什么需要用户标识映射?
为了保护用户隐私,我们不直接暴露京东PIN,而是使用 openUid 作为用户标识。
标识说明:
| 标识 | 说明 | 使用场景 |
|---|---|---|
| vendorUid | 厂商侧用户唯一标识 | 由厂商自行定义和管理 |
| openUid | JoyInside平台用户标识 | 用于设备绑定等操作 |
| jd_pin | 京东用户PIN | 平台内部使用,不对外暴露 |
3.4 设备绑定
设备绑定用于建立用户与设备的关联关系,绑定后用户可以通过设备使用相关服务。
四、接入流程详解
本节详细介绍完整的接入流程,请按照顺序逐步完成。
4.1 用户绑定流程
4.2 步骤详解
步骤1:生成签名参数
为什么这样做? 签名参数是接口调用的基础,每次请求都需要携带,用于验证请求合法性。
具体操作:
python
import time
import uuid
import hmac
import hashlib
import binascii
def build_auth_params(accessKeyId, accessKeySecret):
"""
构建认证参数
Args:
accessKeyId: 访问密钥ID
accessKeySecret: 访问密钥密文
Returns:
dict: 包含签名信息的认证参数
"""
# 1. 组织基础参数
params = {
"accessVersion": "V2", # 固定值,当前版本
"accessTimestamp": str(int(round(time.time() * 1000))), # 13位时间戳
"accessNonce": str(uuid.uuid4()), # 唯一随机数
"accessKeyId": accessKeyId
}
# 2. 将key转为小写并排序
lower_key_params = {k.lower(): params[k] for k in params}
sorted_params = sorted(lower_key_params.items(), key=lambda x: x[0])
# 3. 拼接 key=value 格式
joint_params = '&'.join([f'{k}={v}' for k, v in sorted_params])
# 4. 使用HmacMD5计算签名
h = hmac.new(
accessKeySecret.encode('utf-8'),
joint_params.encode('utf-8'),
digestmod=hashlib.md5
)
sign = binascii.hexlify(h.digest()).decode('utf-8')
# 5. 添加签名到参数
params['accessSign'] = sign
return params验证方法: 打印生成的参数,确认包含以下字段:
- accessKeyId
- accessTimestamp(应为当前时间)
- accessNonce(应为UUID格式)
- accessVersion(应为"V2")
- accessSign(32位16进制字符串)
注意事项:
- 时间戳必须在当前时间前后5分钟内,否则请求会被拒绝
- 每次请求的 accessNonce 应该不同,建议使用UUID
步骤2:获取访问令牌
为什么这样做? Token 是后续所有操作的基础,是用户身份的临时凭证。
具体操作:
python
import requests
import json
def get_token(auth_params, vendorId=None, botId=None):
"""
获取访问令牌
Args:
auth_params: 认证参数(步骤1生成)
vendorId: 厂商唯一标识(与botId二选一)
botId: 设备唯一标识(与vendorId二选一)
Returns:
dict: Token信息
"""
# 构建请求参数
request_data = {**auth_params}
if vendorId:
request_data['vendorId'] = vendorId
if botId:
request_data['botId'] = botId
# 发送请求
response = requests.post(
'https://api.joyinside.com/auth/getToken',
json=request_data,
headers={'Content-Type': 'application/json'}
)
return response.json()
# 使用示例
auth_params = build_auth_params('您的accessKeyId', '您的accessKeySecret')
result = get_token(auth_params, vendorId='您的vendorId')
print(f"Token: {result.get('accessToken')}")
print(f"过期时间: {result.get('expireIn')}秒")预期结果:
json
{
"accessToken": "ehuc2065edbru==",
"expireIn": 7200,
"refreshToken": "cjekcnlsjfekncejh==",
"refreshExpireIn": 604800,
"code": 0,
"msg": ""
}验证方法:
- code 为 0 表示成功
- accessToken 应为非空字符串
使用场景选择:
| 场景 | 使用参数 |
|---|---|
| 新设备配网后注册 | vendorId |
| 设备已注册,需要调用API | botId |
| 两者同时存在 | 优先使用botId |
步骤3:小程序拉起半屏小程序
为什么这样做? 半屏小程序负责用户授权和信息收集,提供友好的用户体验。
具体操作:
javascript
// 在厂商小程序中调用
function launchAuth(token, vendorId) {
/**
* 拉起半屏小程序
*
* @param {string} token - 访问令牌
* @param {string} vendorId - 厂商标识
*/
wx.openEmbeddedMiniProgram({
appId: '半屏小程序AppId', // 请联系技术支持获取
path: '/pages/auth/index',
extraData: {
token: token,
vendorId: vendorId
},
success: function(res) {
console.log('半屏小程序打开成功');
},
fail: function(err) {
console.error('半屏小程序打开失败', err);
}
});
}验证方法: 半屏小程序应该能够正常打开并显示授权页面。
步骤4:获取用户信息
为什么这样做? 获取 openUid 用于后续设备绑定操作。
具体操作:
方式一:通过请求头传递Token(推荐)
javascript
async function getUserInfo(token, vendorUid) {
const response = await fetch('/api/v1/user/bind/info', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({
vendorUid: vendorUid
})
});
return await response.json();
}方式二:通过请求体传递Token
javascript
async function getUserInfo(token, vendorUid) {
const response = await fetch('/api/v1/user/bind/info', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
token: token,
vendorUid: vendorUid
})
});
return await response.json();
}预期结果:
json
{
"code": 0,
"message": "success",
"data": {
"openUid": "用户开放ID",
"nickname": "用户昵称",
"bindStatus": "BOUND",
"bindTime": "2026-01-01 00:00:00"
}
}步骤5:设备绑定
为什么这样做? 建立用户与设备的关联关系,用户才能通过设备使用服务。
具体操作:
python
def bind_device(token, uid, botId, requestId):
"""
绑定设备
Args:
token: 访问令牌
uid: 用户ID(openUid)
botId: 设备ID
requestId: 请求追踪ID
Returns:
dict: 绑定结果
"""
response = requests.post(
'/device/bindUser',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {token}'
},
json={
'uid': uid,
'botId': botId,
'requestId': requestId
}
)
return response.json()预期结果:
json
{
"state": "SUCCESS",
"code": 200,
"data": "用户openUid"
}五、接口文档
5.1 认证相关接口
5.1.1 获取访问令牌
接口地址:POST https://api.joyinside.com/auth/getToken
请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| accessKeyId | String | 是 | 访问密钥ID |
| accessTimestamp | String | 是 | 13位Unix时间戳 |
| accessNonce | String | 是 | 唯一随机数 |
| accessVersion | String | 是 | 固定值"V2" |
| accessSign | String | 是 | 签名 |
| vendorId | String | 否* | 厂商标识(与botId二选一) |
| botId | String | 否* | 设备标识(与vendorId二选一) |
响应参数:
| 字段名称 | 类型 | 说明 |
|---|---|---|
| accessToken | String | 访问令牌,有效期2小时 |
| expireIn | Integer | 过期时间(秒) |
| refreshToken | String | 刷新令牌,有效期7天 |
| refreshExpireIn | Integer | 刷新令牌过期时间(秒) |
| code | Integer | 状态码,0表示成功 |
| msg | String | 错误信息 |
5.2 用户相关接口
5.2.1 获取用户绑定信息
接口地址:POST /api/v1/user/bind/info
请求头:
Content-Type: application/json
Authorization: Bearer {token}请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| vendorUid | String | 是 | 厂商用户唯一标识 |
响应参数:
| 字段名称 | 类型 | 说明 |
|---|---|---|
| openUid | String | 用户开放ID |
| nickname | String | 用户昵称 |
| bindStatus | String | 绑定状态:BOUND/UNBOUND |
| bindTime | String | 绑定时间 |
5.3 设备相关接口
5.3.1 绑定用户到设备
接口地址:POST /device/bindUser
请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| uid | String | 是 | 用户ID(openUid) |
| botId | String | 是 | 设备ID |
| requestId | String | 是 | 请求追踪ID |
响应参数:
| 字段名称 | 类型 | 说明 |
|---|---|---|
| state | String | SUCCESS/FAILURE/ERROR |
| code | Number | 200成功,50x系统错误 |
| data | String | 用户ID |
5.3.2 查询设备绑定用户
接口地址:POST /device/queryBotBind
请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| botId | String | 是 | 设备ID |
| requestId | String | 是 | 请求追踪ID |
响应参数:
| 字段名称 | 类型 | 说明 |
|---|---|---|
| state | String | SUCCESS/FAILURE/ERROR |
| code | Number | 200成功,50x系统错误 |
| data | String | 绑定的用户ID |
5.3.3 用户解绑设备
接口地址:POST /device/unbindUser
请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| uid | String | 是 | 用户ID |
| botId | String | 是 | 设备ID |
| requestId | String | 是 | 请求追踪ID |
响应参数:
| 字段名称 | 类型 | 说明 |
|---|---|---|
| state | String | SUCCESS/FAILURE/ERROR |
| code | Number | 200成功,50x系统错误 |
| data | Bool | true成功/false失败 |
5.4 角色配置接口
5.4.1 为设备绑定角色
接口地址:POST /soulmate/role/botBindRole/save
请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| vendorId | String | 是 | 厂商ID |
| roleId | String | 是 | 角色ID |
| botId | String | 是 | 设备ID |
| requestId | String | 是 | 请求追踪ID |
| roleType | String | 否 | SYSTEM/CUSTOM,默认CUSTOM |
5.4.2 查询设备绑定角色
接口地址:POST /soulmate/role/botBindRole/get
请求参数:
| 字段名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| vendorId | String | 是 | 厂商ID |
| botId | String | 是 | 设备ID |
| requestId | String | 是 | 请求追踪ID |