统一移动端子服务上架及开放接口文档 V1.1

一、概述

本文档用于第三方子服务接入统一移动端底座（APP或者小程序）的相关资料、配置说明，可帮助第三方开发者快速理解打通底座的用户体系，同时方便统一第三方子服务的权限、配置体系。

二、名词解释

序号	使用名词	名词解析
1	底座	与“子服务”呼应，用于提供一个底层容器并集成通用的鉴权、底座功能，包括不限于：APP、小程序
2	子服务	集成在底座的子服务，通过接入底座鉴权体系打通不同系统的用户，展示对应服务功能
3	上架	特指子服务接入底座，通过上架实现子服务在底座的展示入口
4	鉴权	用于打通底座和子服务两者的用户体系，目前通过子服务接入底座的一次性鉴权code实现

三、流程图

四、前置资料准备和数据配置（子服务上架）

子服务上架务必先确保本身子服务是可访问的，并且提供logo、展示名称、子服务基本信息！！！

4.1 上架子服务

请提前准备好以下子服务资料：

序号	资料	备注和说明
1	服务图标（用于在子服务列表展示对应图标）	长宽比1：1，建议200*200像素，png格式，背景为透明，大小小于200K
2	服务名称（用于在子服务列表展示对应名字）	20个字符串，不能含有特殊字符
3	访问地址	H5子服务：提供子服务的H5访问地址还有是否需要其他配置
-	-	1、子服务提供的访问地址不能含有code\phone\userName\appId等关键词参数
-	-	2、如H5子服务域名为第一次上架到对应小程序的，需要配合完成小程序业务域名添加
-	-	具体操作步骤：1、拿到小程序业务域名校验文件；2、将该文件放到子服务的域名根目录下并确保该文件可以正常访问；3、告知有操作小程序后台权限的人将对应域名添加到小程序后台的业务域名列表。
-	-	3、需要拉起微信支付的务必确保已具备拉起条件！最少小程序已绑定带微信支付或者组合支付功能的商户号
-	小程序子服务	小程序访问路径+小程序appId(上架小程序子服务)\小程序原始ID（上架APP子服务）
4	其他信息	发布渠道：上架到对应环境的小程序还是APP或者两者都需要
-	-	是否需要企业认证：需要企业认证才能打开，否则会提示需要认证
-	-	上架到哪个项目、是否需要指定人可见
-	-	如需要上架APP的，是否显示展示APP原生顶部导航栏

4.2 子服务访问权限

请联系对应移动端底座人员拿到对应底座（APP的为下载链接、下载码，小程序可以通过搜索小程序名字）。

小程序登录会自动注册、APP需要通过注册入口注册账号，而后通过访问对应项目子服务获取入口，部分有权限的子服务需要联系移动端底座人员新增用户权限（一般提供手机号即可）。

五、H5子服务单点鉴权

5.1 如何获取

通过小程序、APP子应用打开的H5页面地址会自动拼接一个子服务的一次性code到参数里，可以通过获取对应键名的值拿到对应code，从而调用相关接口获取需要的数据。

注意，此code为一次性鉴权使用，调用过鉴权接口不可以再次使用。

5.2 如何使用

从4.1拿到的code，根据业务逻辑需要，一般用于获取用户信息、token等，具体需要与后台逻辑同步。

拿到code后调用：移动端域名/api/residential-oauth/oauth/getByCloudCode?code=****** 示例：https://spums-uat.icloudcity.com/api/residential-oauth/oauth/getByCloudCode?code=12354

鉴权通过后拿到用户信息。

对应移动端后端接口域名可以通过打开子服务地址拼接的endpoint字段获取。示例：拿到的endpoint为https://spums-uat.icloudcity.com/api，则对应单点接口为 https://spums-uat.icloudcity.com/api/residential-oauth/oauth/getByCloudCode

请求方式：GET

返回数据参考：

json

{
    "code": 200,
    "success": true,
    "data": {
        "user_name": "用户名",
        "account": "137XXXX2333",
        "phone": "137XXXX2333"
    },
    "msg": "操作成功"
}

六、H5子服务对接底座能力

6.1 通用类

	小程序	APP
引入底座jssdk	引入微信的jssdk:`https://res.wx.qq.com/open/js/jweixin-1.6.0.js`后可以拿到wx对象	引入APP的jssdk:`https://onewo-space-public-pro.obs.cn-south-1.myhuaweicloud.com/js/onewo-js-bridge/JSBridge.1.1.0.js`后 `const jsbridge = new JSBridge();`
扫码	调用： `wx.miniProgram.navigateTo({` `url: /subPages/action/pages/scanCode?h5Url=${encodeURIComponent(当前地址)}` `});` 扫码成功后返回scanResult	调用： `jsbridge.scanQRCode(resString => {` `const res = JSON.parse(resString);` `if (res.code === 0) { resolve(res); } else { reject(res); }` `});`
获取当前位置	调用： `wx.miniProgram.navigateTo({` `url: /subPages/action/pages/getLocation?h5Url=${encodeURIComponent(当前地址)}` `});` 返回lat=${lat}&lon=$	调用： `jsbridge.getLocation(resString => {});` 返回高德坐标
拨打号码	调用： `wx.miniProgram.navigateTo({` `url: '/subPages/action/pages/makePhoneCall?callPhone=' + 手机号` `});`	调用： `jsbridge.baseRequest('callNumber', { content: Number(phone) });`

6.2 特殊底座功能

6.2.1 小程序

拉起微信支付

相关商户已配置完成、子服务生成拉起微信支付需要的入参前提下，子服务通过调用：

wx.miniProgram.navigateTo({
    url: `/subPages/action/pages/wxPay?h5Url=&package=&timeStamp=&nonceStr=&signType=&paySign=`
});

跳转到小程序支付页面，支付成功返回 payResult=success，失败返回 payResult=fail。

如需openId，入口地址加参数 needOpenid=1。

通用参数说明

键名	键值
h5Url	支付拉起后返回的页面
package	微信支付package（需encodeURIComponent）
timeStamp	时间戳
nonceStr	随机串（需encodeURIComponent）
signType	签名类型
paySign	签名（需encodeURIComponent）

6.2.2 APP

切换原生导航栏显隐

隐藏：jsbridge.hideNaviBar(resString => {});
显示：jsbridge.showNaviBar(resString => {});

关闭浏览器

jsbridge.closeWeb(resString => { });

6.2.3 移动端消息推送

如何配置订阅和推送消息

1、移动端配置后台，进行子服务新增并且上架到对应项目

2、如果是小程序模板推送，小程序后台需要配置消息推送一系列前置条件

接收消息配置、申请小程序模板、提供小程序模板对应字段。

注意！对应消息模板的详细内容里的字段key需要保存留底

3、门户的系统配置入口

第一步：门户系统管理，新增一个应用管理，记录对应的应用id跟应用密钥（消息推送接口鉴权需要）

第二步：进入门户系统管理，找到"开发配置-消息推送配置"功能

第三步：点击"新增"按钮

第四步：选择需要配置推送的子服务（单选），如员工认证、物品借用等

第五步：选择该规则生效的项目（支持多选），只有已上架该子服务的项目才会出现在可选列表中

第六步：配置推送渠道，可选择APP极光推送、微信服务消息、微信服务号推送中的一种或多种

第七步：根据所选渠道填写对应参数（APP包名/小程序/服务号及AK、SK参数）

第八步：保存配置，此时对应消息管理新增一条对应消息配置，记录对应的消息推送configKey

注意：每个需要推送的子服务都需要单独创建一条推送规则。

4、接口触发微信小程序消息卡片

4-1消息对接

POST请求： ${spup_host}/api/open/smartpark-notification/inform/sendMq

4-1-1 APP消息推送（目前为极光推送）

json

// 请求体：Json格式
{
  "configKey": "FvIscJlSD2pPHDJK4sXXXX",
  "content": "【XX】申请加入【XXX有限公司】",
  "jumpUrl": "",
  "receiveObjList": [
    "15986794XXX",
    "17833706XXX",
    "18824322XXX"
  ],
  "title": "办公助手"
}

configKey	配置生成的唯一字符串
content	推送消息的内容
jumpUrl	跳转地址
title	消息标题
receiveObjList	接收人手机号码集合

4-1-2 微信小程序消息推送

json

// 请求体：Json格式
{
  "configKey": "FvIscJlSD2pPHDJK4sXXXX",
  "data": {
    "thing19": {
      "value": "办公助手"
    },
    "thing18": {
      "value": "xxx"
    },
    "date3": {
      "value": "2025-11-06"
    },
    "thing5": {
      "value": "您提交的认证申请未通过，点击查看详情"
    },
    "phrase1": {
      "value": "未通过"
    }
  },
  "page": "subPages/qifu/pages/main/main?parkCode=i3538&appId=EmployeeCertification",
  "projectCode": "i1717393353338",
  "receiveObjList": [
    "13723482193"
  ],
  "templateId": "9dECAaEmyJUIjLx7CuEyW5ZZPZQ5SNOrqzpYV_wFnZM"
}

configKey	配置生成的唯一字符串
data	微信模版需要的数据，请务必确保跟小程序后台对应模板的字段保持一致！
page	跳转的小程序对应页面地址
projectCode	推送项目编码
templateId	小程序模板id
recpeiveObjList	接收人手机号码集合

4-2消息结果查询

POST请求： ${spup_host}/api/open/smartpark-notification/informRecord/page

请求参数：

current	当前页
size	条数
configKey	配置key
pushType	推送类型
receiveObj	接收对象

返回结果实例：

json

{
  "code": 200,
  "success": true,
  "data": {
    "records": [
      {
        "id": "1984059829950590977",
        "pushType": "wechat",
        "configKey": "FvIscJlSD2pPHDJK4s65KK",
        "receiveObj": "0",
        "result": "{\"errcode\":43101,\"errmsg\":\"user refuse to accept the msg rid: 69040750-2504ea65-6d480452\"}",
        "createTime": "2025-10-31 08:48:19"
      }
    ],
    "total": 20,
    "size": 1,
    "current": 1,
    "pages": 20
  },
  "msg": "操作成功"
}

七、常见问题

1. 子服务已经配置完成但是在对应移动端看不到这个子服务 / 查询服务号失败

确保用户已经登录移动端
登录PC后台检查：
- 是否已经上架对应子服务
- 可见范围是否包含当前账号
- 发布渠道是否匹配（仅APP/仅小程序/两者）

2. 子服务无法在小程序侧打开，提示无法打开报错

确保子服务域名已添加到小程序业务域名，并放置校验文件。调试模式仅用于开发，正式必须配置业务域名。

3. 子服务无法打开，提示没有认证

关闭子服务认证开关
确保用户已完成园区认证
已提交申请≠认证通过

4. 子服务已经打开但是鉴权不通

检查地址栏是否有code
code为一次性，不可重复使用

5. 点击子服务或者扫码提示“查询服务号失败”

检查对应项目是否已上架该子服务
检查当前用户是否在可见范围

6. 小程序登录后需要更换登录手机号

微信首页下拉，删除小程序重新进入
我的 → 清除缓存 → 重新登录

7、小程序一次性模板配置了也推送了为什么我没收到消息

一般小程序消息推送异常可以通过

1、通过4-2消息结果查询对应调用执行结果看一下是不是推送成功，相关错误日志抛出是什么

2、如果1步骤里报错，需要挨个查看哪里异常怎么处理，下面是一些常见错误和处理办法

报错信息	定位	处理办法
`user refuse to accept the msg`	用户没有点击同意授权接收消息	需要用户在弹窗授权时点击订阅同意
`argument invalid!****`	模板参数不准确，可能为空或者不满足规则	检查传入的dat数据，包括是否传对key和值，值长度、值格式是否符合要求
`invalid template_id`	模板 ID 复制错误	检查对应小程序是否有对应的模板id，模板id是否0跟o、1跟l混淆等

统一移动端子服务上架及开放接口文档 V1.1 ​

一、概述 ​

二、名词解释 ​

三、流程图 ​

四、前置资料准备和数据配置（子服务上架） ​

4.1 上架子服务 ​

4.2 子服务访问权限 ​

五、H5子服务单点鉴权 ​

5.1 如何获取 ​

5.2 如何使用 ​

六、H5子服务对接底座能力 ​

6.1 通用类 ​

6.2 特殊底座功能 ​

6.2.1 小程序 ​

拉起微信支付 ​

6.2.2 APP ​

切换原生导航栏显隐 ​

关闭浏览器 ​

6.2.3 移动端消息推送 ​

如何配置订阅和推送消息 ​

1、移动端配置后台，进行子服务新增并且上架到对应项目 ​

2、如果是小程序模板推送，小程序后台需要配置消息推送一系列前置条件 ​

3、门户的系统配置入口 ​

4、接口触发微信小程序消息卡片 ​

4-1消息对接 ​

4-2消息结果查询 ​

七、常见问题 ​

1. 子服务已经配置完成但是在对应移动端看不到这个子服务 / 查询服务号失败 ​

2. 子服务无法在小程序侧打开，提示无法打开报错 ​

3. 子服务无法打开，提示没有认证 ​

4. 子服务已经打开但是鉴权不通 ​

5. 点击子服务或者扫码提示“查询服务号失败” ​

6. 小程序登录后需要更换登录手机号 ​

7、小程序一次性模板配置了也推送了为什么我没收到消息 ​

统一移动端子服务上架及开放接口文档 V1.1

一、概述

二、名词解释

三、流程图

四、前置资料准备和数据配置（子服务上架）

4.1 上架子服务

4.2 子服务访问权限

五、H5子服务单点鉴权

5.1 如何获取

5.2 如何使用

六、H5子服务对接底座能力

6.1 通用类

6.2 特殊底座功能

6.2.1 小程序

拉起微信支付

6.2.2 APP

切换原生导航栏显隐

关闭浏览器

6.2.3 移动端消息推送

如何配置订阅和推送消息

1、移动端配置后台，进行子服务新增并且上架到对应项目

2、如果是小程序模板推送，小程序后台需要配置消息推送一系列前置条件

3、门户的系统配置入口

4、接口触发微信小程序消息卡片

4-1消息对接

4-2消息结果查询

七、常见问题

1. 子服务已经配置完成但是在对应移动端看不到这个子服务 / 查询服务号失败

2. 子服务无法在小程序侧打开，提示无法打开报错

3. 子服务无法打开，提示没有认证

4. 子服务已经打开但是鉴权不通

5. 点击子服务或者扫码提示“查询服务号失败”

6. 小程序登录后需要更换登录手机号

7、小程序一次性模板配置了也推送了为什么我没收到消息