开发准备工作

客户端接口(JS SDK) 

慧家园不仅提供了后端扩展接口,同时也面向前端应用开发提供了 Html5 运行容器和 JS 接口扩展。无论是在 订阅号还是轻应用,都可以基于该前端接口进行开发。 慧家园在支持html5运行环境的基础上,还提供了调用Native能力的 JS 接口,开发者可以基于这些接口来调用Native的处理能力,实现拍照、扫描二维码、位置获取等能力。 


准备工作: 

引入js  <script src="m-platform.js?version=3.0.1.0.0&xy=https&www=smarthome2.smartdot.com&port=28000"></script>; 

js参数需要根据所在的服务器环境来定,所以在使用时需要提前联系慧点家园技术支持部门 

该js 可以从 https://smarthome2.smartdot.com:28000/m-platformjssdk/js/m-platform.js 下载,也可以直接URL引用以方便更新后引入方不需要重新下载更新;

获取当前wifi的SSID


接口介绍  

当手机是wifi网络状态的情况下,调用该接口可以获取到当前wifi的 SSID 和 BSSID (分别对应路由的名称 和 路由唯一ID); 


接口   

MPlatform.getWifiSSIDs(successCallback,failureCallback);


参数介绍 

successCallback:获取WIFI网络状态成功后的回调入口 ; 

failureCallback   :获取WIFI网络状态失败后的回调入口 ;  

注:回调的一定是是function,可以当成字符串使用,但是一定要存在这样的function 


回调返回的参数

callback 回调返回的数据为json ,数据获取样例如下:

{"ssid":"smartdot(5G)","bssid":"74:25:8a:51:07:a0"}

ssid : wifi 的名称 ,在回调里获取的方法为 data.ssid ;

bssid :wifi 的唯一ID(类似于交换机的mac ID) ,在回调里获取的方法为 data.bssid ;


实例代码         

    MPlatform.getWifiSSIDs(successCallback,failureCallback);

    function successCallback(data){
        alert(data.ssid + " : " + data.bssid);
    }

    function failureCallback(data){
        alert('失败了,没有获取成功');
    }


参考demo 在家园内访问 获取当前无线的SSID 当前的地理位置 查看demo的实现方式和原理

获取当前网络状态


接口介绍 

调用该接口可以获取到当前手机网络状态(2G、3G、4G、5G、wifi、unknown),从而方便第三方应用在用户体验上的优化;


接口  

MPlatform.getNetworkStatus(callback);


参数介绍 

callback:网络状态结果的回调入口 ; 

注:回调的一定是是function,可以当成字符串使用,但是但是一定要存在这样的function 


回调返回的参数

callback 回调返回的数据为 字符串 ,直接处理即可,分别为:

2G :表示2G网络;

3G :表示3G网络;

4G :表示4G网络;

5G :表示5G网络;(暂时用不上)

wifi :表示手机是wifi状态下;

unknown :表示无网络


实例代码         

    MPlatform.getNetworkStatus(showNetworkStatus); 

    function showNetworkStatus(result) { 

        alert(result); 

    }


参考demo 在家园内访问 获取当前网络状态 当前的地理位置 查看demo的实现方式和原理

扩展自定义系统返回键


接口介绍

该功能主要用于android系统上,用于系统虚拟键返回;

由于第三方接入的应用可能存在一次或多次的页面内跳转,造成在使用系统返回键返回时起不到返回的效果(系统返回键默认返回到上一个跳转界面,而如果是经过跳转的,那么在执行系统返回时最终还是会返回到当前界面)  

第三方有需要可使用本章介绍内容实现系统返回键的自定义;


总体实现方式和规则为:

1、先自己定义一个函数,而该函数内就是取代系统返回键操作的(点击系统返回键时触发该操作);

2、该函数必须是function定义型函数;

3、将定义好的函数提交给 慧家园管理或支持人员,慧家园方会将定好的函数在后台进行配置,从而达到点击系统返回键时调用自己的返回操作逻辑;


函数定义规则                

function maxWebView(){              

alert('您点击的系统返回键');        

}  

开发人员只需要将 maxWebView 函数提供给我们慧家园人员即可(重写的函数是一个无参函数);

窗口最大化


接口介绍   

接口可供第三方调用将当前的浏览器窗口(webview窗口)最大化 ,往往在使用该功能均是因为第三接入方有自己的页头(防止两个页头的现象);  


接口    

MPlatform.maxWindow();


实例代码           

    function maxWebView(){     
        MPlatform.maxWindow();   
    } 


参考demo   

在家园内访问 窗口最大化 当前的地理位置 查看demo的实现方式和原理

关闭当前显示窗口


接口介绍  

接口可供第三方调用关闭当前的浏览器窗口(webview窗口),该功能主要用作于把窗口最大化后,系统本身的无法提供关闭窗口的时候;

往往在使用该窗口均是因为第三接入方有自己的页头(防止两个页头的现象); 


接口   

MPlatform.closeWindow();


实例代码         

  function closeWebView(){
    MPlatform.closeWindow();
  }


参考demo  

在家园内访问 关闭当前显示窗口 当前的地理位置 查看demo的实现方式和原理

二维码调用接口


接口介绍 

接口可供第三方调用原生扫码功能,用于丰富接入应用的功能多样性等;


接口 

 MPlatform.tdcode(callback);


参数介绍 

callback:扫码结果的回调入口(会将扫到的结果放入该回调) ; 

注:回调的一定是是function,可以当成字符串使用,但是但是一定要存在这样的function 


成功回调返回的参数 

callback 回调返回的数据为 字串符 型,收到直接处理即可 ;


实例代码        

        MPlatform.tdcode(mycode);

        function mycode(result) {
           alert(result);
        }


参考demo 

在家园内访问 二维码调用接口 当前的地理位置 查看demo的实现方式和原理

调用相机或相册


接口介绍 

接口可供第三方调用原生手机拍照、照片选择的功能,用于丰富接入应用的功能多样性等; 


接口 

MPlatform.capture({edit:false,posturl:'',maxlength:1048576,type:0},successCallback,failureCallback);


参数介绍 

JSON内的结构体参数:

edit :图片是否可裁剪 (true 为可裁剪,false 为不可裁剪),该功能暂不完善,默认为false即可;

posturl :图片上传路径URL,默认为慧家园的图片库内,如果需要自己存储则需要自己构建图片URL上传地址;

maxlength :图片的大小控制(类型为 字节),该功能暂不晚上,默认填写 1048576;

type :需要使用的功能,0 标识需要使用相册和相机,1 标识只需要使用拍照 , 2 标识只需要使用相册;

successCallback:图片上传成功后的回调入口 ;

failureCallback   :图片上传失败后的回调入口 ; 

注:回调的一定是是function,可以当成字符串使用,但是一定要存在这样的function 

特别提醒:如果是自己的图片服务器,上传地址必须实现multipart方式的上传处理,否则无法接收上传数据


成功回调返回的参数

successCallback 在本实例中回调返回的数据为 JSON ,由于返回的的数据是从上传图片的接口返回的,所以如果自己定义的图片服务,那么返回数据可以根据自己的需要而定,如果自己没有图片服务器,可以可以系统本身的图片服务器,那么返回的数据格式则为JSON格式 ;

样例:

 {"code" :"000000","filepath":"http://smarthome2.smartdot.com:28000/admin_api/..... ?access_token=xxx&imgpath=xxx"}

关键词识别获取:

code : 交易识别码 ;

filepath : 图片访问、下载路径


实例代码        

    function gCapture() {
        MPlatform.capture({edit:false,posturl:'https://smarthome2.smartdot.com:28000/admin_api/jssdk/jssdk_upload_img',maxlength:1048576,type:0},captured,failed);
    }
    function captured(data) {
        alert(data.code +" : "+data.filepath);
    }
    function failed(msg) {
    }


图片上传代码示例DEMO(JAVA)

   Map<String, String> sysParamConfig = CacheUtils.getSysParamConfig();
   // 创建一个通用的多部分解析器
   CommonsMultipartResolver multipartResolver = new CommonsMultipartResolver(request.getSession().getServletContext());
   // 判断 request 是否有文件上传,即多部分请求
   if (multipartResolver.isMultipart(request)) {
    // 转换成多部分request
    MultipartHttpServletRequest multiRequest = (MultipartHttpServletRequest) request;
    // 取得request中的所有文件名
    Iterator<String> iter = multiRequest.getFileNames();
    Date dirDate = new Date();
    while (iter.hasNext()) {
     // 取得上传文件
     MultipartFile file = multiRequest.getFile(iter.next());
     if (file != null) {
      // 取得当前上传文件的文件名称
      String myFileName = file.getOriginalFilename();
      // 获取文件的后缀名
      String suffixName = myFileName.substring(myFileName.lastIndexOf("."));
      if (myFileName.trim() != "" && FileUploadUtils.isImag(myFileName)) {
       // 重命名上传后的文件名
       String nowDir = "/" + new SimpleDateFormat("yyyy").format(dirDate) + "/" + new SimpleDateFormat("MM").format(dirDate)
               + "/" + new SimpleDateFormat("dd").format(dirDate);
       String fileName = UUID.randomUUID() + suffixName;
       // 定义上传路径
       String fullFileName = sysParamConfig.get("HEAD_IMG_STORAGE_PATH");
       String path = fullFileName + "/jssdk_upload" + nowDir;
       File fileDir = new File(path);
       if (!fileDir.isDirectory()) {
        fileDir.mkdirs();
       }
       File localFile = new File(path + "/" + fileName);
       file.transferTo(localFile);
       jsonObject.element("code", "000000");
       url = sysParamConfig.get("PARAM_SERVLET_PAHT") + "/jssdk/jssdk_download_img?headImg=/jssdk_upload/" + nowDir + "/"
               + fileName;
       jsonObject.element("filepath", url);
      } else {
         jsonObject.element("code", "60x079");
         jsonObject.element("filepath", "");
      }
     }
    }
   }


图片上传代码示例(PHP)


参考demo 

在家园内访问 调用相机或相册 查看demo的实现方式和原理

获取用户当前的地理位置


接口介绍

获取用户当前的地理位置 是为第三方接入方提供的扩展性接口,用于丰富接入应用的功能多样性,如 获取当前用户的地理位置 可以帮助接入方实现位置打卡、行为轨迹图 等;


接口

MPlatform.getLocation(successCallback,failureCallback)


参数介绍

successCallback:位置获取成功后的回调入口 ;

failureCallback   :位置获取失败后的回调入口 ;

注:回调的一定是是function,可以当成字符串使用,但是但是一定要存在这样的function


成功回调返回的参数

successCallback 回调返回的数据为 JSON ;

样例:

{"longitude" :"116.35812012","latitude":"40.04323893" ....}

关键词识别获取:

longitude : 经度坐标;

latitude : 纬度坐标;

city : 坐标定位的城市名称;

address :坐标的具体位置(例如:北京市海淀区西小口路东升科技园北领地);

district : 区域(例如:海淀区);

street :街道、道路 (例如:西小口路);

country : 国家(例如:中国);

province : 省份(例如:河北省 ,如果是直辖市则如: 北京市);

buildname : 区块名称(例如:东升科技园北领地)


实例代码   

    MPlatform.getLocation(locationSucceed,locationFailed);
    
    function locationSucceed(data) {

        alert(data.longitude+" : "+data.latitude);

    }

    function locationFailed(msg){

        alert(msg);

    }


参考demo

在家园内访问 获取用户当前的地理位置 查看demo的实现方式和原理

个人详情界面


接口介绍

个人详情界面接口 是为第三方应用提供的快速查看帐号详情的入口,可以通过调用该接口快速进入某人的个人详情(目前只支持通讯录组织人员,暂不支持群组);


接口

MPlatform.showInfo(openUserId);


参数介绍

openUserId:需要快速沟通的用户ID 

注:ID帐号要包含 域 信息,如帐号是 lils ,那么在输入时追加域信息,整个帐号信息为:lils@hdkj


实例代码

    function openUserInfo(user){
        MPlatform.showInfo(user);
    }


参考demo 

在家园内访问 个人详情界面 查看demo的实现方式和原理

调取聊天(沟通)界面


接口介绍

可以打开当前用户与指定用户的聊天对话框界面, 是为第三方应用提供的快速沟通入口,可以通过调用该接口快速进入与某人的沟通(目前快速沟通入口只支持点对点,暂不支持群组);


接口

MPlatform.chatWithUser(openUserId);


参数介绍

openUserId:需要快速沟通的用户ID 

注:ID帐号要包含 域 信息,如帐号是 lils ,那么在输入时追加域信息,整个帐号信息为:lils@hdkj


实例代码

    function openChatUser(user){
        MPlatform.chatWithUser(user);
    }


参考demo  

在家园内访问 唤起聊天(沟通)界面 查看demo的实现方式和原理

人员选择器


接口介绍

人员选择器 是为第三方应用提供的通讯录选择器,可以通过调用该接口呈现完整的通讯录;人员选择器分为 人员多选 、人员单选;


接口

MPlatform.selectUser(preSelectedUsers,isMulti,successCallback,failureCallback);


参数介绍

preSelectedUsers:已选择用户,可以为多值,使用英文逗号进行分割,例如如:zhangsan@hdkj,lisi@hdkj,wangwu@hdkj,该参数主要是针对多选界面,当进行多选的时候,在选择界面下方会自动显示这些用户,单选的时候该值直接为空即可。

isMulti:true或者false。如果为true,则表示允许用户多选,否则只能单选。 

successCallback:选择成功之后的回调方法,该回调方法的参数为json数据格式,记录了用户选择的人员信息,例如:

 {users:[{userId:'zhangsan@hdkj',username:'张三'},{userId:'lisi@hdkj',username:'李四'},{userId:'zhaoliu@hdkj',username:'赵六'}]}。

failureCallback:选择失败的回调方法,暂时还没有启动。


成功回调返回参数

successCallback 回调返回的数据为 集合JSON ,其各字段分别为:

users : 为用户集合

userId : 用户唯一ID(帐号);

username : 用户真实姓名 ;


示例代码

    //调用该函数即可启动人员选择器
    function gSelectUsers(){
       MPlatform.selectUser('',false,userSelected,userFailed);
    };
    function userSelected(data) {
       var size = data.users.length;
       for(var i = 0 ; i < size ; i++) {
           alert(data.users[i].userId);
       }
    };
    function userFailed () {

    }


参考demo   

在家园内访问 人员选择器 查看demo的实现方式和原理

更多开放接口

更多开放接口正在加紧开发中,如有特殊需要,请联系慧家园技术支持支持那反馈,我们会根据产品评估确认给与您开放,谢谢支持!

订阅号-开发准备

订阅号消息通知集成 

订阅号消息通知是平台的一种扩展,旨在为用户提供信息通知服务,通常理解为第三方应用本身提供的消息服务; 

首先第三方如果要集成订阅号服务,需要先向管理员索要自己的订阅号ID和秘钥,然后调用【获取订阅号令牌】拿到该订阅号的使用权限(access_token);

然后根据自身需要实现发送不同的消息类型(每次在调用接口是均需要将令牌放入到header中,否则无法识别身份而导致无法发送);

注:如需要发送图文消息并点击图文实现单点跳转的,需要在发送消息时的访问地址内加上注入令牌的地方; 

假如推送的URL访问地址是 http://hjy.smartdot.com/content?id=123321 ,那么在集成的时候,要根据自身接收参数的需要在其URL加入令牌注入参数,从而形成新的URL :http://hjy.smartdot.com/content?id=123321&access_token=%access_token% ,而推送的URL应发送新的URL地址才能保证推送的URL能实现单点数据的接收(单点的过程需要第三方接收到身份令牌后调用身份验证接口获取合法身份信息);

同步 - 开发准备

组织结构接入: 

组织结构接入是针对第三方企业独立域的结构或组织提供的(前提条件为 独立的组织域); 

当需要组织自主接入的时候,需要在域管理后台(域独立帐号)添加组织结构接入的识别码,而后将识别码提供给同步接入的研发人员; 

研发人员需要在拿到同步识别码后调用获取同步令牌接口换取令牌并随同返回该令牌的失效时间,而该令牌将作为在未失效前的组织结构同步接口调用凭证;

产品概述


慧家园产品概述: 

慧家园产品是企业级统一连接中心,统一汇聚企业中的所有信息入口,为用户统一呈现工作重心统一所有与自身相关的工作入口,统一消息中心及时推送与自身相关的人际沟通消息及工作待办消息,统一内容中心全面且有选择的展现需要个人掌握的企业内部内容; 


订阅号概述: 

订阅号作为企业内部统一消息中心的核心模块,提供标注的规范和接口给所有需要向用户推送消息的系统使用,同时提供强制订阅及自由订阅等选项,给系统和用户创造更有效的链接及自主性; 


轻应用概述: 

轻应用作为统一工作中心的核心能力,通过完善的后台管理权限及标准的接入规范和接口,提供员工所需进行的所有工作相关入口,并可灵活提供千人千面因人而异的模块清单及安全快捷的单点登录能力;

开发准备

目前接入分三种,分别为组织结构接入(组织结构同步)、轻应用(小程序)的接入、订阅号消息通知集成;  

组织结构接入:

组织结构接入是针对第三方企业独立域的结构或组织提供的(前提条件为 独立的组织域);

当需要组织自主接入的时候,需要在域管理后台(域独立帐号)添加组织结构接入的识别码,而后将识别码提供给同步接入的研发人员;

研发人员需要在拿到同步识别码后调用获取同步令牌接口换取令牌并随同返回该令牌的失效时间,而该令牌将作为在未失效前的组织结构同步接口调用凭证;


订阅号消息通知集成

订阅号消息通知是平台的一种扩展,旨在为用户提供信息通知服务,通常理解为第三方应用本身提供的消息服务;

首先第三方如果要集成订阅号服务,需要先向管理员索要自己的订阅号ID和秘钥,然后调用【获取订阅号令牌】拿到该订阅号的使用权限(access_token);

然后根据自身需要实现发送不同的消息类型(每次在调用接口是均需要将令牌放入到header中,否则无法识别身份而导致无法发送);

注:如需要发送图文消息并点击图文实现单点跳转的,需要在发送消息时的访问地址内加上注入令牌的地方;

假如推送的URL访问地址是 http://hjy.smartdot.com/content?id=123321 ,那么在集成的时候,要根据自身接收参数的需要在其URL加入令牌注入参数,从而形成新的URL :http://hjy.smartdot.com/content?id=123321&access_token=%access_token% ,而推送的URL应发送新的URL地址才能保证推送的URL能实现单点数据的接收(单点的过程需要第三方接收到身份令牌后调用身份验证接口获取合法身份信息);




轻应用集成:

 轻应用(H5)集成是嵌入方式,是为将开发好的轻应用引入到慧家园中并实现从慧家园直接进入轻应用中而不需要在进行二次登录,实现门户入口;在整个集成过程如下:

 首先准备轻应用的入口地址并提交到管理人员,有管理人员为其加入到系统域并授权使用范围(可使用的人员),在配置入口地址的时候,需要在入口地址上配好客户端注入身份令牌(access_token)的地方,例如:  

1、我轻应用的入口地址为 http://www.smartdot.com/auth ,那么提交到慧家园中的则为 http://www.smartdot.com/auth?access_token=%access_token% ,轻应用接收access_token参数并进行令牌身份确认等后续操作;  

 2、请用接收到的access_token是经过 encode 后的(防止第三方应用接收时出现特殊符号乱码),所以在后续使用时需要先将其decoder再使用; 

 然后调用身份令牌确认接口来验证令牌的合法性和令牌的持有人从而实现轻应用的接入与单点。  

订阅号消息状态(计划消息)

计划消息是为了第三方对消息状态进行变更而提供的,使用场景如下:
1、如果推出去的消息是【待办】,当本条待办处理完毕可以将其改为【已办】标记 (此功能目前在扩展中,暂不支持项目使用);
2、如果推出去的消息处理完毕,为了防止在手机上显示而出现视觉误差,可以调用该接口将处理完的数据从手机上删除;

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/sendGraphicScheduleMsg

请求方式

POST

请求 Content-Type

application/json

请求自定义Header

参数 示例值 必填 参数描述
access_token GKZz8ZQbfTXE0amIxDTd9XIqrYthPmQaitRIGwTqbcmZFh0drhCjPAzVe6cSMUoyCmfEMkdL9KRenPEV2gA8nE5LfqhGgLlH7nGYhHkrLP0= 必填 订阅号身份令牌

请求Body参数

{
    "receiver": "lijq@hdkj",
    "msg_info": {
        "msg_only_id": "3c6d55fbb2fb4316df44c595064a93260bf7d3fe",
        "msg_schedule_type": "0",
        "msg_schedule": ""
    }
}
receiver : 接收人,多个接收人以英文 逗号( , )分割;
msg_only_id :第三方报文的唯一ID(推送时的报文唯一ID),处理数据以该报文ID为依据;
msg_schedule_type :计划消息类型 (0 标识需要将该条报文数据删除 ,1 标识需要往本条数据上戳章【1的功能暂时未在产品上做】);
msg_schedule :当 msg_schedule_type 为 1 时,本字段为戳章的内容,如【已办】,当 msg_schedule_type 为 0 时本字段没有没有用处;

请求Query参数

参数 示例值 必填 参数描述

响应参数

参数 参数描述
code 响应码
unsubscription_user (失败的用户)未订阅账户
error_user (失败的用户)不存在的帐号

成功响应示例

{
    &quot;code&quot;: &quot;000000&quot;,
    &quot;unsubscription_user&quot;: &quot;&quot;,
    &quot;error_user&quot;: &quot;&quot;
}

失败响应示例

{
    &quot;code&quot;: &quot;60x079&quot;
}

获取令牌身份信息(access_token验证)接口

该接口主要用于第三方接入时的身份验证 ;
当第三方接入时,需要先提供一个入口地址,需要在入口地址上配置需要注入access_token的位置,当客户端点击该入口时会自动将身份标识注入进去,第三方接收到 身份令牌后调用该接口验证合法性和用户身份信息;
入口地址示例:http://www.smartdot.com/auth/token?access_token=%access_token% ;
终端会默认将 %access_token% 注入(为了防止编码问题,在注入的时候默认将其 encode ,第三方接收后如需要调用其它接口时需要先将其 decoder),注入后的URL示例为:
http://www.smartdot.com/auth/token?access_token=mtQB9Ux6ys%2bNYrojZ%2baGU3IqrYthPmQaitRIGwTqbcmZFh0drhCjPEdAxQm7uftexpmjo2CL2hu%2fKvnspVu95gictXHDYyHV

接口URL

https://m-platform.smartdot.com/admin_api/api/org/orguser_current_userinfo

请求方式

POST

请求 Content-Type

multipart/form-data

请求自定义Header

参数 示例值 必填 参数描述
access_token mtQB9Ux6ys+NYrojZ+aGU3IqrYthPmQaitRIGwTqbcmZFh0drhCjPEdAxQm7uftexpmjo2CL2hu/KvnspVu95gictXHDYyHV 必填 身份令牌

请求Body参数

参数 示例值 必填 参数描述

响应参数

参数 参数描述
code 状态码
userEntry 用户载体(实体对象)
userEntry.birthday 出生日期
userEntry.contactUser 此字段在本接口内无作用
userEntry.domain 所属域
userEntry.duty 职位
userEntry.email 邮箱
userEntry.extended_field_msg 扩展字段
userEntry.fax 传真
userEntry.landline 座机
userEntry.m_desc 个人签名
userEntry.m_id 唯一ID
userEntry.mobile 手机号
userEntry.order_num 排序号
userEntry.parent_id 所属部门ID
userEntry.parent_name 所属部门名称
userEntry.part_time 兼职部门
userEntry.roleId 用户角色
userEntry.roleName 角色名称
userEntry.sex 性别
userEntry.station 工位位置
userEntry.trueNamePinyin 姓名拼音
userEntry.true_name 真实姓名
userEntry.upVersion 用户版本号
userEntry.user_from 用户来源
userEntry.user_id 登录帐号
userEntry.user_short_id 短号
userEntry.zip 分机号

成功响应示例

{
    "code": "000000",
    "userEntry": {
        "birthday": "",
        "contactUser": 0,
        "domain": "",
        "duty": "产品研发经理",
        "email": "lils@smartdot.com",
        "extended_field_msg": "",
        "fax": "",
        "landline": "8093",
        "m_desc": "",
        "m_id": "lils@hdkj",
        "mobile": "13810808723",
        "order_num": "202",
        "parent_id": "8d6656dc42544bdabc34f9df80c3f5f1",
        "parent_name": "移动产品研发部",
        "part_time": "",
        "roleId": 0,
        "roleName": "",
        "sex": "男",
        "station": "",
        "trueNamePinyin": "",
        "true_name": "李连顺",
        "upVersion": 205,
        "user_from": "hdjy",
        "user_id": "lils@hdkj",
        "user_short_id": "",
        "zip": ""
    }
}

失败响应示例

{
    "code": "60x079"
}

订阅号推送图片消息

调用该接口可以往订阅号内发送【图片消息】

在发送文件时,可以直接选择发送文件的可访问地址,也可以调用文件素材上传接口现将文件传输到服务器上,发送时只需要标注素材实体身份(素材ID)即可。

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/sendimagemsg?receiver=xiely@hdkj&msg_img_url=a4acbb5c-cbba-4dd3-8a8b-ca4f9b1939b6&msg_img_name=a4acbb5c-cbba-4dd3-8a8b-ca4f9b1939b6.png&msg_only_id=1111111111122222222

请求方式

POST

请求 Content-Type

multipart/form-data

请求自定义Header

参数 示例值 必填 参数描述
access_token JXwR24OU4x27O3h1IANmuQXO2NPOIvU8R9zB+vINF5IDFg+D8syHkzAVRCHu6IatcqFR88OTB42q/AdO19ah2gR4XljZYcuM0kElv8PWwRU= 必填 订阅号身份令牌

请求Body参数

参数 示例值 必填 参数描述

请求Query参数

参数 示例值 必填 参数描述
receiver xiely@hdkj 必填 消息接收人,多个以逗号分割
msg_img_url a4acbb5c-cbba-4dd3-8a8b-ca4f9b1939b6 必填 图片素材ID 或 图片url地址
msg_img_name a4acbb5c-cbba-4dd3-8a8b-ca4f9b1939b6.png 必填 图片显示名称(带有图片格式)
msg_only_id 1111111111122222222 必填 发送方图片的唯一标记(作为后续的撤回使用,暂可为空)

响应参数

参数 参数描述
code 响应码
unsubscription_user (失败的用户)未订阅账户
error_user (失败的用户)不存在的帐号

成功响应示例

{
    &amp;quot;code&amp;quot;: &amp;quot;000000&amp;quot;,
    &amp;quot;unsubscription_user&amp;quot;: &amp;quot;&amp;quot;,
    &amp;quot;error_user&amp;quot;: &amp;quot;&amp;quot;
}

失败响应示例

{
    &amp;quot;code&amp;quot;: &amp;quot;60x079&amp;quot;
}

订阅号推送文本消息

调用该接口可以往订阅号内发送【文本类型消息】,但是该文本消息不支持html标签

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/sendtextmsg?msg_content=你好? 我不好 那谁好??&receiver=liuyun@hdkj,huwei@hdkj&msg_only_id=3322222222222221

请求方式

POST

请求 Content-Type

application/x-www-form-urlencoded

请求自定义Header

参数 示例值 必填 参数描述
access_token ly2f0BQrRG4LUgrQilCwTSyt7jsImtQ8+JkwVdlDFZhCvMf2VmyWCQIMvQhQwwNJG0aY1BKsOtO1QT/IQQXZie62xm9gmYx7DC7ir4o/VMY= 必填 订阅号身份令牌

请求Body参数

参数 示例值 必填 参数描述

请求Query参数

参数 示例值 必填 参数描述
msg_content 你好?\n我不好\n那谁好?? 必填 发送的消息内容
receiver liuyun@hdkj,huwei@hdkj 必填 消息接收人,多个以逗号分割
msg_only_id 3322222222222221 必填 发送方图片的唯一标记(作为后续的撤回使用,暂可为空)

响应参数

参数 参数描述
code 响应码
unsubscription_user (失败的用户)未订阅账户
error_user (失败的用户)不存在的帐号

成功响应示例

{
    &quot;code&quot;: &quot;000000&quot;,
    &quot;unsubscription_user&quot;: &quot;&quot;,
    &quot;error_user&quot;: &quot;&quot;
}

失败响应示例

{
    &quot;code&quot;: &quot;60x079&quot;
}

订阅号推送文件消息

调用该接口可以往订阅号内发送【文件类型消息】,常见文件类型均支持。

在发送文件时,可以直接选择发送文件的可访问地址,也可以调用文件素材上传接口现将文件传输到服务器上,发送时只需要标注素材实体身份(素材ID)即可。

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/sendfilemsg?receiver=xiely@hdkj&msg_file_url=a4acbb5c-cbba-4dd3-8a8b-ca4f9b1939b6&msg_file_name=huawei.png&msg_file_size=20662&msg_only_id=123123123142323233

请求方式

POST

请求 Content-Type

multipart/form-data

请求自定义Header

参数 示例值 必填 参数描述
access_token JXwR24OU4x27O3h1IANmuQXO2NPOIvU8R9zB+vINF5IDFg+D8syHkzAVRCHu6IatcqFR88OTB42q/AdO19ah2gR4XljZYcuM0kElv8PWwRU= 必填 订阅号身份令牌

请求Body参数

参数 示例值 必填 参数描述

请求Query参数

参数 示例值 必填 参数描述
receiver xiely@hdkj 必填 消息接收人,多个以逗号分割
msg_file_url a4acbb5c-cbba-4dd3-8a8b-ca4f9b1939b6 必填 文件素材ID 或 文件url地址
msg_file_name huawei.png 必填 文件显示名称(带有文件格式)
msg_file_size 20662 必填 文件大小(以字节为单位)
msg_only_id 123123123142323233 必填 发送方图片的唯一标记(作为后续的撤回使用,暂可为空)

响应参数

参数 参数描述
code 响应码
unsubscription_user (失败的用户)未订阅账户
error_user (失败的用户)不存在的帐号

成功响应示例

{
    &amp;quot;code&amp;quot;: &amp;quot;000000&amp;quot;,
    &amp;quot;unsubscription_user&amp;quot;: &amp;quot;&amp;quot;,
    &amp;quot;error_user&amp;quot;: &amp;quot;&amp;quot;
}

失败响应示例

{
    &amp;quot;code&amp;quot;: &amp;quot;60x079&amp;quot;
}

订阅号推送单图文消息

所谓图文消息,实际上一种消息的可外链的消息展示形式;
可以对该消息进行封装(类似微信的腾讯新闻),图文包含 标题、链接 等基础信息,也包括了 图片、内容 等自由扩展显示的;

如果通知消息URL需要核实用户身份,那么需要在URL中添加 access_token=%access_token% 参数,当客户端点击该URL时,系统会自动将 %access_token% 标识的位置注入成真实的用户身份令牌(access_token),接入方可以根据此 access_token 获取用户合法性以及真正的身份信息。

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/sendSingleMsg

请求方式

POST

请求 Content-Type

application/json

请求自定义Header

参数 示例值 必填 参数描述
access_token GKZz8ZQbfTXE0amIxDTd9XIqrYthPmQaitRIGwTqbcmZFh0drhCjPAzVe6cSMUoyCmfEMkdL9KRenPEV2gA8nE5LfqhGgLlH7nGYhHkrLP0= 必填 订阅号身份令牌

请求Body参数

{
	"receiver": "huwei@hdkj",
	"msg_info": {
		"msg_title": "测试数据,收到请忽落",
		"msg_content": "您有一个报销单未审批,请及时处理,谢谢!-没有传图片",
		"msg_only_id":"3c6d55fbb2fb4316df44c595064a93260bf7d3fe",
		"msg_schedule_type":"-1",
		"msg_img": "https://pics2.baidu.com/feed/3c6d55fbb2fb4316df44c595064a93260bf7d3fe.jpeg",
		"msg_schedule":"",
		"msg_ios_url": "http://www.baidu.com?access_token=%access_token%",
		"msg_android_url": "http://www.baidu.com?access_token=%access_token%",
		"msg_pc_url": "http://www.baidu.com?access_token=%access_token%",
		"msg_open_way":"0",
		"msg_system_back":"0",
		"msg_system_back_js":"rewrite_back()"
	}
}
receiver :接收人ID,多个帐号以英文逗号(,)分割
msg_title : 消息标题
msg_content :消息内容
msg_only_id :报文在推送方的唯一ID (19-11-18日新增参数,版本往上兼容),如想从手机上清除该消息需借助该字段
msg_schedule_type :计划消息状态类型,默认为 -1 (功能完善中...)
msg_img :图文消息的主题图ID或URL(可以通过素材上传获取素材ID 或 直接输入图片的URL地址)
msg_schedule :计划消息状态词 (目前该字段作为预留扩展字段,留作产品后期使用项目定制)
msg_ios_url : 消息在苹果手机上打开的URL地址
msg_android_url : 消息在安卓手机上打开的URL地址
msg_pc_url : 消息在电脑上打开的URL地址
msg_open_way : URL默认打开方式,0为默认不全屏,1为默认全屏(内置浏览器默认全屏)
msg_system_back : 是否使用系统返回键,1为使用系统返回,0为不使用系统返回,当为0时点击系统返回键触发lite_app_system_back_js内的函数
msg_system_back_js :点击系统返回键时需要调用的js函数

响应参数

参数 参数描述
code 响应码
unsubscription_user (失败的用户)未订阅账户
error_user (失败的用户)不存在的帐号

成功响应示例

{
    &amp;quot;code&amp;quot;: &amp;quot;000000&amp;quot;,
    &amp;quot;unsubscription_user&amp;quot;: &amp;quot;&amp;quot;,
    &amp;quot;error_user&amp;quot;: &amp;quot;&amp;quot;
}

失败响应示例

{
    &amp;quot;code&amp;quot;: &amp;quot;60x079&amp;quot;
}

订阅号文件素材上传

在调用消息发送时(图片消息、文件消息、图文消息),如果素材没有URL可访问地址,可调用该接口先将素材上传到家园服务器,比如:图片、语音、视频、文件等实体文件,还包括多图文这种组合的消息。上传成功后,会得到服务器返回的materialid,该materialid用来表示文件体,在发送消息时直接使用materialid即可。

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/materialupload

请求方式

POST

请求 Content-Type

multipart/form-data

请求自定义Header

参数 示例值 必填 参数描述
access_token dEvfDDVUb492q20GvplF1Cyt7jsImtQ8+JkwVdlDFZjiq7ON+nI5AoZC3jr1UPYmTVDrVEF0H7zg02gsPyajmQF56hPzfdYV8S0B+3QFuRo= 必填 身份标记

请求Body参数

参数 示例值 必填 参数描述
material - 必填 需要上传的文件(file类型)

响应参数

参数 参数描述
code 响应码
materialid 素材ID

成功响应示例

{
    "code": "000000",
    "materialid": "c1f8a47e-eac9-44e7-afd5-8a3e25776e01"
}

失败响应示例

{
    "code": "60x079"
}

获取订阅号操作令牌

该接口主要用于第三方订阅号推送接入时的身份验证 ;
当第三方接入时,有移动平台提供给第三方一套订阅号的APPID 和 秘钥(sercret),第三方根据上述两个信息调用该接口换取令牌信息,而该令牌信息是发送订阅号消息的凭证

接口URL

https://m-platform.smartdot.com/admin_api/api/servicenumbermsg/getaccesstoken?service_no_id=B4w496B0E5G5P173&service_no_secret=E6bBH96jA7Wwg7Iq

请求方式

POST

请求 Content-Type

multipart/form-data

请求Body参数

参数 示例值 必填 参数描述

请求Query参数

参数 示例值 必填 参数描述
service_no_id B4w496B0E5G5P173 必填 订阅号ID(APPID)
service_no_secret E6bBH96jA7Wwg7Iq 必填 订阅号秘钥(Secret)

响应参数

参数 参数描述
code 响应码
access_token 身份token
expires_in token失效时间

成功响应示例

{
    "code": "000000",
    "access_token": "dEvfDDVUb492q20GvplF1Cyt7jsImtQ8+JkwVdlDFZjiq7ON+nI5AoZC3jr1UPYmTVDrVEF0H7zg02gsPyajmQF56hPzfdYV8S0B+3QFuRo=",
    "expires_in": 1574848714922
}

失败响应示例

{
    "code": "60x079"
}

获取同步操作令牌

在使用同步前,需要先向系统人员索要用于同步的 key 和 secret (自己的key和secret不要泄漏,否则会造成当前域内的数据混乱) ,然后调用该接口获取到同步身份令牌;
在获取组织域同步令牌时,会同步返回当前域组织结构的根目录ID,所有的组织结构都要以此为根节点进行操作,否则将导致同步的组织结构无法展现;

接口URL

https://m-platform.smartdot.com/admin_api/api/sync/getsynctoken?system_code=javaoa_sync&system_secret=Q1nS4BG7R5mpo0fe

请求方式

POST

请求 Content-Type

application/x-www-form-urlencoded

请求Body参数

参数 示例值 必填 参数描述

请求Query参数

参数 示例值 必填 参数描述
system_code javaoa_sync 必填 同步 key
system_secret Q1nS4BG7R5mpo0fe 必填 同步秘钥

响应参数

参数 参数描述
code 状态码
access_token 唯一操作token,用于同步后续身份
expires_in 超时截至时间(超过该时间令牌自动失效,需要重新获取)
dept_root_dir 跟节点ID

成功响应示例

{
    "code": "000000",
    "access_token": "3f9bcc4f-3d69-49e9-8771-095659a22209",
    "dept_root_dir": "96a6fdfeb39a413a8579d221cab937dd",
    "expires_in": 1573548087808
}

失败响应示例

{
    "code": "60x079"
}

同步人员(添加、修改、删除)

同步人员操作,根据操作标记操作,本接口暂不做业务处理(接收什么数据处理什么数据)
批量数据操作中,当有一条出现问题那么整个批量均会回滚,避免数据错乱

接口URL

https://m-platform.smartdot.com/admin_api/api/sync/syncuser

请求方式

POST

请求 Content-Type

application/json

请求自定义Header

参数 示例值 必填 参数描述
access_token 99b37695-469f-45c3-a603-c396a2493171 必填 身份令牌

请求Body参数

{"opcode":"0",//opcode操作码,0增加、1修改、2删除
	"data":[{
		"user_id": "lisi", //帐号
		"true_name": "李四",//姓名
		"order_num":"11",//排序号
		"parent_id":"013d987ec6af45ddafdb7b57eac457d5", //所属部门ID
		"mobile":"13800000000",//手机号
		"landline":"010-8629312", //座机
		"duty":"专员", //职务
		"sex":"男",//性别
		"email":"63726371@qq.com"//邮箱
	}]
}
opcode:操作码 --- 0增加、1修改、2删除
user_id :帐号
true_name :姓名
order_num :排序号
parent_id :所属部门ID
mobile :手机号
landline :座机
duty :职务
sex :性别
email :邮箱

请求Query参数

参数 示例值 必填 参数描述

响应参数

参数 参数描述
msg 失败的错误信息
code 状态码

成功响应示例

{
    "msg": "add success",
    "code": "000000"
}

失败响应示例

{
    "code": "60x079"
}

同步部门(添加、修改、删除)

同步部门操作,根据操作标记操作,本接口暂不做业务处理(接收什么数据处理什么数据);
批量数据操作中,当有一条出现问题那么整个批量均会回滚,避免数据错乱

接口URL

https://m-platform.smartdot.com/admin_api/api/sync/syncdept

请求方式

POST

请求 Content-Type

Array

请求自定义Header

参数 示例值 必填 参数描述
access_token 0ac2c71d-10f4-46be-87d0-2a5d014469e5 必填 身份令牌

请求Body参数

{
	"opcode": "0",//操作码,0增加、1修改、2删除
	"data": [
		{
			"dept_id": "013d987ec6af45ddafdb7b57eac457d5",//当前部门ID
			"dept_name": "总裁办",//当前部门ID
			"order_num": "1",//当前部门的排序号
			"parent_id": "96a6fdfeb39a413a8579d221cab937dd"//父级部门ID,如为一级部门时父级部门从获取身份时拿取
		}
	]
}
opcode:操作码,0增加、1修改、2删除
dept_id:当前部门ID
dept_name:当前部门ID
order_num:当前部门的排序号
parent_id:级部门ID,如为一级部门时父级部门从获取身份时拿取

请求Query参数

参数 示例值 必填 参数描述

响应参数

参数 参数描述
msg 失败的错误信息
code 状态码

成功响应示例

{
    &quot;msg&quot;: &quot;add success&quot;,
    &quot;code&quot;: &quot;000000&quot;
}

失败响应示例

{
    &quot;code&quot;: &quot;60x079&quot;
}