应用标准接入协议

文档目标

本文档用于描述得力云平台云端应用服务接入的通用标准方式、通信协议以及具体的接口定义,不涉及具体某种类型应用的业务操作协议。

适用范围

本文档用于说明得力云平台对外提供的应用服务接入方式,帮助和指导云端应用服务开发人员正确接入云平台。

相关术语

术语 解释
智能设备 是指任何一种具有计算处理能力的设备、器械或者机器,智能设备通过网络与云平台连接,实现设备和云端软件服务的集成
云平台 各种智能设备和应用服务接入的基础服务平台,为智能设备和云端应用进行接入和数据交换提供支撑
应用服务 为智能设备提供增值服务的云端软件应用

应用接入设计

  • 应用注册

任何云端应用服务需要提前在得力云平台进行注册,注册时需要提供以下信息:

1.   应用服务名称
2.   应用服务图标
3.   应用服务效果截图(至少4张)
4.   App端访问的URL地址
5.   Web端访问的URL地址
6.   平台服务器回调的WebHook地址
7.   联系人信息
8.   可以支持的设备产品型号列表

其中: 第4项App访问地址是指通过得力手机App打开应用是访问的链接地址,第5项是后台Web管理端访问的链接地址,第6项是指平台主动通知应用服务时的回调WebHook接口地址。

注意: 目前得力云平台并未对外开放注册,所以云端开发者需要将相关信息提交给平台管理人员,由平台管理人员备案注册

应用注册完成后,平台会提供分配给应用的唯一的appIdappKey。后续平台与服务之前的通信将通过该信息进行身份识别和签名。同时,应用在审核发布后,也会出现在得力App的应用列表中供用户查看安装。

  • 应用安装

应用服务可以通过以下两种途径被用户安装使用:

1.   通过App应用市场或,用户搜索然后点击安装;
2.   通过智能设备扫码绑定时,用户选择可以配套使用的应用服务;

对于第二种方式,平台会根据应用注册时提供的支持设备产品型号列表进行筛选。

不论哪种方式,应用安装成功后,即出现在用户App的应用列表中,点击应用即可访问注册时提供的URL地址。

  • 应用授权

用户登录APP之后,通过App访问云端应用服务的Web页面时,云端应用会加载得力云JS SDK的初始化API进行应用授权验证,验证通过后,应用即可通过JS SDK提供的用户API接口获取当前用户的相关信息,并返回应用界面资源。 整个授权流程如下:

下一章节会对接口进行具体说明。

  • 其他说明

出于灵活性考虑,APP内所有云端应用都应基于HTML5网页开发,除非经过授权,云端应用无法直接访问平台内的数据,但允许应用通过平台提供的JS SDK开放的接口访问原生APP提供的部分功能和接口。

具体JS SDK提供的功能列表见《第三方云应用JS-SDK API说明》文档

应用服务接口

为了满足应用服务的业务需求,平台提供了一系列的接口方便应用与设备、平台以及终端App用户进行信息交互。

通信协议

考虑到云端应用服务的多样性,所有云端应用服务统一采用HTTP协议+JSON数据交换格式与平台API Gateway服务网关进行通信,由平台根据请求类型的不同进行消息路由。 同样,应用服务提供的Web Hook回调接口也采用相同的方式处理。

下面分别就应用服务WebHook回调接口和平台开放的API Gateway接口进行详细说明。

WebHook回调接口

如果需要推送消息给应用服务,必须统一调用应用服务注册的WebHook回调URL地址完成。平台目前仅支持HTTP/HTTPS协议的回调地址。

平台调用WebHook回调接口统一采用POST方式发起请求,请求参数采用JSON格式数据提交,消息示例如下:

{
    "mid": "消息ID", 
    "from": "消息发布者ID", 
    "to": "应用服务ID", 
    "time": 操作时间(秒), 
    "action": 操作指令, 
    "data": {具体消息内容 }
}

各参数说明如下:

参数 类型 描述
mid 字符串 消息ID,用来标识一次消息请求上下文,内容由请求方自定义,建议采用类似时间戳等唯一信息,方便调试跟踪。
from 字符串 消息发布者ID。包括:设备ID、应用服务ID或者平台system
to 字符串 应用服务ID
time 整型 消息发布时间,精确到秒
action 整型 消息指令。不同指令代表不同的消息操作类型
data JSON 可选,具体的消息内容

注意:所有未标注为"可选"状态的信息都是必填的,当可选信息为空时,平台默认是不会传递的。

出于安全考虑,平台发送给应用服务的回调请求会进行数字签名,应用服务可对签名进行验证,防止非法请求。签名的计算方式如下:

sig = MD5(action + from + to + appKey + time)

其中签名用的appKey是由应用服务注册时平台自动生成。sig生成后放到HTTP的请求头部(Request Header)中,与请求参数一同发送给应用服务。

为了确保WebHook接口调用请求能成功的送达应用服务,平台会对请求失败的情况按照一定的规则进行重试(最多尝试次数为30次,每次尝试时间间隔会根据次数递增)。平台视为请求失败的情况包括:HTTP连接失败或超时、HTTP状态为5XX6XX等。

对于其他情况,平台不会视为请求失败,也不会重发。但业务上来讲,也存在成功或失败两种情况。对于业务处理成功的情况,应用应返回HTTP状态码200,并将响应结果封装在Response Body中,格式按具体指令要求定义;对于业务处理失败的情况(例如参数错误、权限问题等),应用应返回HTTP状态码4XX,并将具体错误消息封装在在Response Body中,格式建议为字符串。

目前平台消息推送的通用WebHook请求有如下几种:

  • 应用安装400

通过该指令平台通知应用服务某用户组织安装了此应用。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID", 
    "action": 400, 
    "time": 1503025335, 
    "data": {
        "org_id": "用户组织ID",
        "name": "组织名称",
        "logo": "组织logo URL地址或空",
        "org_admin": {
            "user_id": "管理员ID", 
            "name": "姓名", 
            "empno": "工号或空", 
            "avatar": "头像URL或空"
        }
    }
}

各参数说明如下:

参数 类型 描述
org_id 字符串 应用绑定组织ID
name 字符串 组织名称
logo 字符串 可选,组织LOGO图片URL,如果未设置则为空
org_admin JSON 组织超级管理员信息,包括:
user_id:管理员用户ID,
name:管理员姓名,
empno:可选,管理员组织工号,非设置则为空,
avatar:可选,管理员头像URL,未设置则为空
  • 应用卸载401

通过该指令通知应用服务某用户组织停用了或者删除了此应用,该指令与400对应。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID", 
    "action": 401, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID",
        "clear": true|false
    }
}

各参数说明如下:

参数 类型 描述
org_id 字符串 卸载该应用的目标组织ID
clear Boolean true表示应清除组织数据,否则不清除。一般来讲,除非组织被解散导致应用自动删除,组织数据都不需要清除。
  • 设备绑定402

通过该指令平台通知应用服务某用户组织绑定一台新设备。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID", 
    "action": 402, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID", 
        "device_id": "设备ID", 
        "name": "设备名称", 
        "status": 0|1,
        "product": {
            "model": "产品型号", 
            "name": "产品名称", 
            "type": "产品类型", 
            "icon": "产品图标URL地址", 
            "features": [ {
                "type": "特征类型",
                "value": "特征参数值",
            }],
            "properties": [{
                "name": "参数名",
                "text": "参数显示文本",
                "type": "参数值类型",
                "default_value": "参数默认值",
                "values": [{
                        "value": "1", 
                        "text": "值1"
                }]
            }]
        }
    }
}

各参数说明如下:

参数 类型 描述
org_id 字符串 设备所绑定组织ID
device_id 字符串 设备ID
name 字符串 设备名称
status 整型 设备状态,0表示离线,1表示在线
product JSON 产品信息。包括:
model:产品型号,
name:产品名称,
type:产品类型,
icon:可选,产品图标URL,未设置则为空,
features:可选,产品特征参数列表,不同产品类型不同,未设置则为空。包括:
type: 特征参数类型,例如考勤方式check_type,
value: 对应特征参数值(例如指纹考勤fp等)

properties:可选,产品可配置属性列表,不同产品类型不同,未设置则为空。包括:
name:可配置参数名,
text: 可配置参数显示文本;
type: 可配置参数值类型,目前仅支持列表类型,固定为list
default_value: 参数默认值;
values: 当type为list时,参数可设置的可选值列表,列表中每个值包含有value和text两个参数,其中value表示可设置的值,text表示对应值的显示文本。

注意,相同产品型号的设备,product配置信息是一样的。因此,应用应单独维护产品配置信息,每次有新的设备绑定时,对应产品型号的配置信息做更新操作,确保所有相同产品型号设备的产品配置信息是一致的,且始终与平台保持更新。

  • 设备解绑403

通过该指令平台通知应用服务某用户组织解绑了一台现有设备。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID",
    "action": 403, 
    "time": 1503025335, 
    "data": {
        "device_id": "设备ID",
        "org_id": "组织ID",
    }
}

各参数说明如下:

参数 类型 描述
org_id 字符串 设备所绑定组织ID
device_id 字符串 设备ID
  • 设备状态更新404

通过该指令平台通知应用服务某台现有设备的上下线状态。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID",
    "action": 404, 
    "time": 1503025335, 
    "data": {
        "device_id": "设备ID", 
        "name": "设备名称", 
        "status": 0|1
    }
}

各参数说明如下:

参数 类型 描述
device_id 字符串 设备ID
name 字符串 设备名称
status 整型 设备状态,0表示离线,1表示在线
  • 设备消息转发405

平台收到来自设备的指令300的消息请求后,如果验证消息无误,会通过该指令转发到云应用,但消息内容不变。

转发消息示例如下:

{
    "mid": "消息ID", 
    "from": "设备ID", 
    "to": "应用服务ID", 
    "action": 405, 
    "time": 1503025335, 
    "data": {
        "cmd": "业务操作命令", 
        "payload": {}
 }
}
  • 用户组织更新推送406

对于部分开放了组织通信录访问权限的云端应用,一旦用户组织发生了人员或部门信息变动,会通过该指令主动通知云端应用来进行数据同步。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID", 
    "action": 406, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID", 
        "target": "org|dept|user|perm"
    }
}

各参数说明如下:

参数 类型 描述
org_id 组织ID
target 更新目标类型。包括:
org:组织信息,
dept:部门,
user:用户,
perm:权限

注意: 仅在注册应用服务时授权了通信录同步功能的应用才会收到该同步信息。

  • 用户事件推送407

云端应用可能需要根据用户的一些状态或者位置状态变化来执行相应的操作,例如考勤机的极速打卡需要了解用户WIFI/蓝牙/GPS等变化信息。 应用需要先通过API Gateway指令注册用户事件监听,监听成功后,平台会使用该指令将用户的相关事件信息推送给应用。 推送消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID",  
    "action": 407, 
    "time": 1503025335, 
    "data": {
        "user_id": "用户ID", 
        "event": "用户事件", 
        "event_data": {}
    }
}

各参数说明如下:

参数 类型 描述
user_id 字符串 用户ID
event 字符串 用户事件,目前包括的事件有:
sign_in:用户登入,
sign_off:用户退出,
wifi:用户Wifi更新,
ble:用户蓝牙更新,
gps:用户GPS位置更新
event_data JSON 可选,跟event相关,不同event信息不同
  • eventsign_insign_off 时,event_data为空;

  • eventgps时,event_data格式如下:

{
    "lat":"38.6518",
    "lng":"104.07642"
}
  • eventwifible时,event_data格式如下:
{
    "sid":"wifi或者蓝牙设备标示ID",
}
  • 微信消息转发408

平台收到来自微信的消息请求后,会通过该指令转发到云应用,消息内容会原样存放在data中。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "system", 
    "to": "应用服务ID", 
    "action": 408, 
    "time": 1503025335, 
    "data": {
        "cmd": "微信操作指令",
        "payload": {...}
    }
}

各参数说明如下:

参数 类型 描述
cmd 字符串 微信操作指令:用户扫码完成user_scan、接收微信消息receive_message
payload JSON 可选,跟cmd相关,不同cmd信息不同
  • cmduser_scan时,payload格式如下:
{
    "ticket": "获取的二维码ticket,凭借此ticket可以在有效时间内换取二维码",
    "user_id": "用户ID",
    "scene_id": "场景值ID"
}
  • cmdreceive_message时,payload格式如下:
{
    "from_user_id": "发送用户ID",
    "create_time": 1503025335,
    "msg_type": "文本消息text",
    "content": "消息内容"
}
  • 应用数据请求409

为了满足与其他信息系统(例如其他云应用或云平台体系之外的其他应用系统)的业务集成需求,云应用服务需要对外开放一些具体业务的自定义数据请求接口,平台通过该指令可以向应用转发对这些接口服务的调用。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "system/请求应用ID", //如果是云应用则为应用ID,否则固定为system
    "to": "应用服务ID", 
    "action": 409, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID", 
        "cmd": "请求命令",
        "payload": {...}
    }
}

各参数说明如下:

参数 类型 描述
org_id 字符串 数据所在组织ID。应用数据请求必须限制在某个具体的组织内。
cmd 字符串 应用数据请求指令,由云应用提供可支持的命令集。
payload JSON 可选,跟cmd相关,不同cmd信息不同。

API Gateway接口

除了WebHook的方式被动接收平台推送的消息外,应用服务也可以通过调用平台提供的公共API Gateway网关接口,主动发起消息请求。

目前平台开放允许应用服务发起消息请求的类型主要有如下几种:

1.   设备消息推送
2.   用户消息推送
3.   平台数据访问
4.   平台事件注册

得力云平台统一提供了RESTful API 风格的统一网关地址处理应用服务请求, 所有消息统一采用POST方式发起HTTP请求,请求参数格式采用JSON格式(HTTP请求中的Content-Type设置为application/json),HTTP Body具体格式如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "目标ID", 
    "action": 消息指令, 
    "time": 1503025335, 
    "data": {请求内容 }
}

请求内容和格式与WebHook回调接口基本一致,通过action来区分不同的消息类型,消息内容封装在data里面,平台要求为JSON数据格式。另外,所有HTTP请求均需携带数字签名并附在HTTP请求头部,计算方式与WebHook一致,如下:

sig = MD5(action + from + to + appKey + time)

注意: 对于发送给设备和用户App的请求,由于是异步消息处理,同步响应结果仅表示平台接收结果,不代表目标设备或用户响应结果。

响应结果统一为以下JSON数据格式:

{
    "code": 错误码, 
    "msg": "错误消息描述", 
    "time": 响应时间, 
    "data": {响应内容 }
}

错误码定义请参考平台统一错误码

  • 设备信息推送500

通过该指令应用服务可主动推送消息到设备。平台收到消息后,如果消息验证成功,将通过指令301转发到设备。

请求参数如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "设备ID",
    "action": 500, 
    "time": 1503025335, 
    "data": {
        "cmd": "应用自定义消息命令", 
        "payload": {}
    }
}

请求各参数说明如下:

参数 类型 描述
cmd 字符串 应用内自定义消息命令
payload JSON 可选,自定义命令的关联参数,可为空

由于设备消息属于异步消息,平台会立刻返回推送结果,表示是否送达。如果设备不在线,平台会直接返回消息无法送达。

响应示例如下:

{
    "code": 102, 
    "msg": "设备未注册或已离线", 
    "time": 1503025335, 
}
  • 用户消息推送501

通过该指令应用服务可对指定用户或部门人员列表发起消息推送,推送消息目前仅支持文本。

推送消息示例如下:

{ 
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 501, 
    "time": 1503025335, 
    "data": {
        "org_id": "用户组织ID",
        "user_ids": [通知人员列表],
        "dept_ids": [通知部门列表], 
        "type": "消息类型", 
        "payload": {...}, 
        "priority": 1
    }
}

请求参数说明如下:

参数 类型 描述
org_id 字符串 用户组织ID
user_ids 数组 消息通知的人员ID列表
dept_ids 数组 消息通知的部门ID列表。该部门下所有用户都会收到消息
type 字符串 消息类型:TEXT/文本、RICH_TEXT/富文本
payload JSON 消息内容,
priority 整型 消息重要程度,1-3级,3级最高,默认设置为1即可
  • typeTEXT时,payload格式如下:
{
    "message": "消息内容"
}
  • typeRICH_TEXT时,payload格式如下:
{
    "title": "消息标题",
    "message": "消息内容",
    "href": "消息链接或空"
}

平台响应数据格式如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335, 
    "data": {
        "user_ids": [...... ]
    }
}

响应各参数说明如下:

参数 类型 描述
user_ids 数组 可选,推送失败的用户ID列表
  • 代办事项推送502

通过该指令应用服务可对指定用户或部门人员列表发起代办事项推送,代办事项除了文本消息外,还包含有相应的操作入口。 推送消息示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 502, 
    "time": 1503025335, 
    "data": {
        "task_id": "代办事项ID", 
        "org_id": "用户组织ID",
        "user_ids": [...... ], 
        "dept_ids": [...... ], 
        "title": "消息标题", 
        "content": "消息内容", 
        "priority": 1, 
        "link": "消息链接URL", 
        "actions": [
            {
                "action": "拒绝", 
                "link": "reject?id=v", 
                "silent": true
            }, 
            {
                "action": "同意", 
                "link": "agree?id=v", 
                "silent": false
            }
        ]
    }
}

请求参数说明如下:

参数 类型 描述
task_id 字符串 应用内代办事项唯一ID,请保证组织内代办事项ID的唯一性
org_id 字符串 用户组织ID
title 字符串 消息标题
user_ids 数组 消息通知的人员ID列表
dept_ids 数组 消息通知的部门ID列表。该部门下所有用户都会收到消息
content 字符串 消息内容,可支持基础的HTML标签的富文本
priority 整型 消息重要程度,1-3级,3级最高
link 字符串 可选,消息点击链接地址, 使用相对路径,APP会自动按照应用注册url进行拼接。
actions 字符串 代办事项的快捷操作入口,可设置最多两个入口。各参数定义如下:
action:快捷操作名称,
link:快捷操作HTTP链接,
silent:是否静默操作,即不跳转页面(默认false)

平台响应示例如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335, 
    "data": {
        "userids": [...... ]
    }
}

响应参数说明如下:

参数 类型 描述
user_ids 数组 可选,推送失败的用户ID列表
  • 代办事项状态更新503

应用服务通过该指令可更新之前推送的代办事项状态。

推送消息示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 503, 
    "time": 1503025335, 
    "data": {
        "task_id": "代办事项ID", 
        "org_id": "用户组织ID",
        "status": 1,   
        "update_time": 1503025335
    }
}

请求各参数说明如下:

参数 类型 描述
cmd 字符串 todo_update表示代办事项状态更新
task_id 字符串 应用内代办事项ID
status 整型 完成状态:
0-未完成
1-已完成
2-已取消
update_time 整型 更新时间(秒)

平台响应数据格式如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335
}
  • 扫码事件注册504

出于某些特殊需求,第三方应用服务可以生成自定义的二维码信息,并通过该指令注册到平台。在有效期内,得力APP扫描到该自定义二维码可自动跳转到应用服务,并以参数形式转发该二维码信息到应用服务。 请求参数如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 504, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID", 
        "qrcode": "二维码文本信息", 
        "expire": "失效时长(秒)",
    } 
}

请求各参数说明如下:

参数 类型 描述
org_id 字符串 组织ID
qrcode 字符串 应用服务生成的二维码信息,应保证全局唯一
expire 整型 失效时长,秒为单位。如果是-1,则表示永久有效

平台返回如下默认响应:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335, 
}

如果注册成功,使用得力APP扫描该二维码时,会自动跳转打开应用服务,并在HTTP头部携带参数_D_from_D_data,其中_D_from的值为qrCode_D_data的值是注册时的二维码信息(即请求参数qrcode的值)。

  • 用户事件注册505

应用服务通过该指令可注册监听用户的相关状态和位置变化事件。注册成功后,平台会在事件发生时通过WebHook推送指令407将用户数据推送给应用服务。 请求参数如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 505, 
    "time": 1503025335, 
    "data": {
        "event": "用户事件", 
        "org_id": "用户组织ID", 
        "user_ids": [
            //用户ID列表
        ]
    }
}

请求各参数说明如下:

参数 类型 描述
event 字符串 用户事件,具体事件列表参考指令407
org_id 字符串 用户所在组织ID
userids 数组 需要监听事件的用户ID列表

平台响应数据格式如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335
}
  • 用户事件注销506

该指令与指令505对应,应用服务可取消注册用户事件。取消完成后,平台将不再推送相应的用户事件到应用服务。 请求示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 506, 
    "time": 1503025335, 
    "data": {
        "event": "用户事件", 
        "org_id": "用户组织ID", 
        "user_ids": [
            //用户ID列表
        ]
    }
}

请求参数说明与505完全一致。 平台响应数据格式如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335
}
  • 组织信息同步507

对于开放了组织通信录访问权限的云端应用,一旦用户组织绑定了此类应用,应用可主动通过该接口同步组织信息。 后续如果收到平台推送过来的组织更新指令406,应用也应根据最近更新时间进行增量同步操作,保持组织通信录的一致。 请求同步消息示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 507, 
    "data": {
        "org_id": "用户组织ID", 
        "update_time": -1, 
        "target": "org|dept|user|perm", 
        "size": 100
    }
}

请求各参数说明如下:

参数 类型 描述
org_id 字符串 同步的组织ID
update_time 整型 上次增量更新的时间戳,精确到毫秒
target 字符串 同步的目标:组织信息、部门、用户、权限。如果需要都同步,需要分别调用
size 整型 本次增量同步的更新数量,单次限制最大300条。

平台收到请求后,如果授权通过,将根据请求的target不同响应不同。

  • 如果target是组织信息,则仅响应组织的最新信息,数据格式如下:
{
    "code": 0, 
    "msg":"",
    "time": 1503025335, 
    "data": {
        "target": "org", 
        "update_time": 1503025335, 
        "org": {
            "org_id": "用户组织ID",
            "name": "组织名称",
            "logo": "组织logo URL地址或空",
            "org_admin": {
                "user_id": "管理员ID", 
                "name": "姓名", 
                "empno": "工号或空", 
                "avatar": "头像URL或空"
            }
        }
    }
}
  • 如果target是部门,则仅响应部门的更新信息,数据格式如下:
{
    "code": 0, 
    "msg":"",
    "time": 1503025335, 
    "data": {
        "target": "dept", 
        "size": 100, 
        "update_time": 1503025335, 
        "depts": [
            {
                "dept_id": "1", 
                "ext_id": "外部ID",
                "name": "部门1", 
                "manager_id": "部门主管ID", 
                "pid": 0
            }, 
            {
                "dept_id": "2", 
                "delete": true
            }
        ]
    }
}
  • 如果target是用户,则仅响应用户的更新信息,响应数据格式如下:
{
    "code": 0, 
    "msg":"",
    "time": 1503025335, 
    "data": {
        "target": "user", 
        "size": 100, 
        "update_time": 1503025335, 
        "users": [
            {
                "user_id": "用户ID", 
                "ext_id": "外部ID",
                "name": "用户姓名", 
                "empno": "工号或空", 
                "seqno": "组织内序号",
                "avatar": "头像URL或空", 
                "dept_ids": ["所在部门ID1", "所在部门ID2"],
                "deptinfo": [
                    {"dept_id": "部门ID", "title": "部门职称"}
                ]
            }, 
            {
                "user_id": "用户ID", 
                "delete": true
            }
        ]
    }
}
  • 如果target是权限,则响应管理员的全量数据,响应数据格式如下:
{
    "code": 0, 
    "msg":"",
    "time": 1503025335, 
    "data": {
        "target": "user", 
        "size": 100, 
        "perms": [
            {
                "user_id": "用户ID", 
                "admin": false,
                "su": true
            }
        ]
    }
}

各响应参数说明如下:

参数 类型 描述
target 字符串 更新的内容:部门(dept)或用户(user)
size 整型 本次更新的条目数
update_time 整型 本次更新的时间戳,精确到毫秒
depts 数组 可选,部门列表,如果无更新,则返回空。包括:
dept_id:部门ID,
ext_id:可选,部门外部系统ID,仅用于和第三方系统对接使用,
name:部门名称,
manager_id:部门主管ID,
pid:上级部门ID,如果没有,则为空,
delete:删除标志,如果是true,表示该部门需要被删除
users 数组 可选,组织人员列表,如果无更新,则返回空。 包括:
user_id:用户ID,
ext_id:可选,用户外部系统ID,仅用于和第三方系统对接使用,
name:用户姓名,
empno:可选,工号或空,
seqno:组织内序号,由系统按用户加入组织顺序生成,组织内唯一,
avatar:可选,用户头像URL,
dept_ids:所在部门列表,
deptinfo:用户相关的部门信息,
delete: 删除标志,如果是true,标识该用户需要被删除
perms 数组 可选,管理员列表,每次均返回全量数据。 包括:
user_id:用户ID,
admin:是否是管理员,
su:是否是超级管理员

注意,仅在注册应用服务时授权了通信录同步功能的应用才会收到该同步信息。

  • 设备信息查询508

云端应用通过该指令实时查询绑定设备的相关信息。 请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 508, 
    "data": {
        "device_id": "设备ID"
    }
}

各参数说明如下:

参数 类型 描述
device_id 字符串 查询的目标设备ID

响应结果与指令402一致。

  • 用户授权认证509

    对于某些第三方应用服务,如果需要对用户在服务器端进行再次身份认证,可通过此接口与平台通信完成。验证通过后会同时获取用户的基本信息。 请求参数如下:
{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 509, 
    "time": 1503025335, 
    "data": {
        "user_id": "用户ID", 
        "client_type": "授权类型",
        "client_id": "授权客户端id",
        "token": "用户token",
        "org_id": "1233123"
    } 
}

各参数说明如下:

参数 类型 描述
user_id 字符串 进行授权验证的用户ID
client_type 字符串 请求授权的客户端类型,可选。包括:app-第三方应用授权,device-设备登陆,server-得力APP云应用授权。缺省为app
client_id 字符串 请求授权的客户端ID。针对app场景请提供第三方应用ID( 注意,如果client_id为空,将视为得力APP云应用token验证,与server相同 ),针对device场景,则需要提供设备SN;其他场景不需要提供。
token 字符串 登录获得的授权token
org_id 字符串 组织ID,可选,如果只验证用户token,可不提供

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {
        "user_id": "用户ID", 
        "name": "姓名", 
        "avatar": "头像URL或空",
        "admin": true //仅在org_id存在的情况下返回,表示是否组织内该应用的管理员

    }
}

其中code等于0则表示认证成功,其它情况(109等)均视为Token认证失败。

  • 微信消息推送510

通过该指令应用服务可主动发送消息到微信。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 510, 
    "time": 1503025335, 
    "data": {
        "cmd": "微信操作指令",
        "payload": {
            // 消息指令参数
        }
    }
}

各参数说明如下:

参数 类型 描述
cmd 字符串 微信操作指令:关键字订阅subscribe、发送微信消息send_message、上传素材upload_file、获取二维码get_qr_code
payload JSON 可选,跟cmd相关,不同cmd信息不同
  • cmdsubscribe时,payload格式如下:
{
    "matching_method": "全匹配0、正则匹配1、开始2、存在3、结尾4",
    "matching_key": "关键字,多个以,隔开"
}
  • cmdsend_message时,payload格式如下:
{
    "to_user_id": "接收用户ID",
    "msg_type": "文本消息text、图文消息image",
    "content": "消息内容",
    "media_id": "图文消息时必传"
}
  • cmdupload_file时,payload格式如下:
{
    "media_type": "图片image、声音voice、录像video、缩略图thumb、文件file",
    "file_type": "资源类型",
    "file_name": "资源名称",
    "file_ext": "资源后缀",
    "file_url": "资源下载地址"
}
  • cmdget_qr_code时,payload格式如下:
{
    "scene_id": "场景ID",
    "expire_seconds": "单位秒,最大30天,默认为最大"
}
  • cmdget_all_media时,payload格式如下:
{
    "type": "素材的类型,图片(image)、视频(video)、语音 (voice)、图文(news)",
    "offset": "从全部素材的该偏移位置开始返回,0表示从第一个素材 返回",
    "count": "返回素材的数量,取值在1到20之间"
}

平台响应数据格式如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {...}
}
  • 当请求参数cmdsubscribe时,返回data格式如下:
{
    "subscribe_id": "订阅ID"
}
  • 当请求参数cmdsend_message时,返回data为空
  • 当请求参数cmdupload_file时,返回data格式如下:
{
    "type": "图片image、声音voice、录像video、缩略图thumb、文件file",
    "media_id": "资源ID",
    "thumb_media_id": "缩略图ID",
    "created_at": "创建时间戳"
}
  • 当请求参数cmdget_qr_code时,返回data格式如下:
{
    "ticket": "获取的二维码ticket,凭借此ticket可以在有效时间内换取二维码",
    "expire_seconds": "单位秒,最大30天,默认为最大",
    "url": "二维码地址"
}
  • 当请求参数cmdget_all_media时,返回data格式如下:
{
    "total_count": 10,
    "item_count": 1,
    "item": [
        {
           "media_id": "微信多媒体ID",
           "name": "多媒体名称",
           "update_time": 1503025335,
           "url":"访问URL"
        },
        ...
    ]
}
  • 短信发送511

用户注册、密码找回时的短信发送接口。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 511, 
    "time": 1503025335, 
    "data": {
        "mode": 1,
        "region": "86",
        "mobile": "13400000000"
    }
}

各参数说明如下:

参数 类型 描述
mode 数字 1注册/2密码找回/3短信登录
region 字符串 可选,手机号区域,默认86
mobile 字符串 手机号

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335
}
  • 用户注册512

用户注册接口,需先调用短信发送接口。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 512, 
    "time": 1503025335, 
    "data": {
        "region": "86",
        "mobile": "13400000000",
        "password": "MD5(密码明文)",
        "veri_code": "123456"
    }
}

各参数说明如下:

参数 类型 描述
region 字符串 可选,手机号区域,默认86
mobile 字符串 手机号
password 字符串 MD5(密码明文)
veri_code 字符串 短信验证码

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {
        "user_id": "355672617635545088"
    }
}

如果手机号码已注册或短信验证码错误会返回响应的错误码。

  • 用户密码重置513

用户密码如果丢失,可通过短信验证码重置密码,需先调用短信发送接口。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 513, 
    "time": 1503025335, 
    "data": {
        "region": "86",
        "mobile": "13400000000",
        "password": "MD5(新密码明文)",
        "veri_code": "123456"
    }
}

各参数说明如下:

参数 类型 描述
region 字符串 可选,手机号区域,默认86
mobile 字符串 手机号
password 字符串 MD5(新密码明文)
veri_code 字符串 短信验证码

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335
}

如果手机号码未注册或短信验证码错误会返回响应的错误码。

  • 用户密码修改514

用户密码修改接口,需先调用短信发送接口。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 514, 
    "time": 1503025335, 
    "data": {
        "user_id": "355672617635545088",
        "password": "MD5(旧密码明文)",
        "new_password": "MD5(新密码明文)"
    }
}

各参数说明如下:

参数 类型 描述
user_id 字符串 用户ID
password 字符串 MD5(旧密码明文)
new_password 字符串 MD5(新密码明文)

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335
}

如果手机号码未注册或旧密码验证错误会返回响应的错误码。

  • 用户登录515

用户登录接口,通过本接口校验用户登录帐户信息。支持密码登录短信验证码登录两种方式。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 515, 
    "time": 1503025335, 
    "data": {
        "mode": 1,
        "region": "86",
        "mobile": "13400000000",
        "password": "MD5(密码明文)"
    }
}

各参数说明如下:

参数 类型 描述
mode 整型 可选,1密码登录/2短信登录,默认是1
region 字符串 可选,手机号区域,默认86
mobile 字符串 手机号
password 字符串 密码或验证码。如果是密码登录,请使用MD5(密码明文)进行加密处理;

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {
        "user_id": "355672617635545088",
        "token": "用户token",
        "expire": 过期时间(UTC毫秒数)
    }
}

如果手机号码或者密码错误,会返回相应的错误码。应用获得的用户token,可再次通过指令509进行失效验证。

  • 应用消息推送516

应用通过该指令可以向其他应用请求或推送消息。消息会由平台转发为指令409通过webhook推送到目标应用。

通知消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "目标应用服务ID", 
    "action": 516, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID",
        "cmd": "目标应用自定义消息命令",
        "payload": {}
    }
}

各参数说明如下:

参数 类型 描述
org_id 字符串 请求的组织ID。应用之间的调用必须限制在某个组织内
cmd 字符串 目标应用支持的自定义消息命令
payload 字符串 自定义命令的关联参数,可为空

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {
        //409响应结果,格式为JSON
    }
}

其中,data字段返回的内容是目标应用响应的数据结果,格式必须为JSON。

  • 用户信息查询517

应用通过该指令可通过手机号码查询平台注册用户。请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 517, 
    "time": 1503025335, 
    "data": {
        "region": "86",
        "mobile": "13400000000" //完整的手机号码
    }
}

如果找到对应的用户信息,则平台返回响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {
        "user_id": "355672617635545088",
        "name": "张三",
        "avatar" : "头像URL或空"
    }
}

如果没有匹配的用户信息,则data返回为空。

  • 应用安装请求518

为了满足某些特定应用集成的需要,应用可以通过该指令向平台发起其他应用的安装请求,请求时需要提供请求管理员用户ID和目标组织ID。

请求消息示例如下:

{
    "mid": "消息ID", 
    "from": "应用服务ID", 
    "to": "system", 
    "action": 518, 
    "time": 1503025335, 
    "data": {
        "user_id": "管理员ID",
        "org_id": "组织ID",
        "app_id": "目标应用服务ID"
    }
}

各参数说明如下:

参数 类型 描述
user_id 字符串 申请安装应用的组织管理员用户ID
org_id 字符串 申请安装应用的目标组织ID
app_id 字符串 申请安装的目标应用ID

平台返回默认响应如下:

{
    "code": 0, 
    "msg": "", 
    "time": 1503025335,
    "data": {
        "admin": true //是否是目标应用的管理员
    }
}

如果用户没有安装应用的权限,会返回相应的错误。如果应用已安装,会返回成功,admin字段会标示用户是否拥有已安装应用的管理权限。

  • 组织用户信息查询519

应用可以通过本指令随时向平台查询组织内用户的个人信息。 请求示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 519, 
    "time": 1503025335, 
    "data": {
        "user_id": "用户ID",
        "org_id": "用户所在组织ID"
    }
}

其中各参数说明如下:

参数 类型 描述
user_id 字符串 查询的目标用户ID
org_id 字符串 查询目标组织ID

如果数据校验正确,平台会同步返回响应如下:

{
    "code": 0,
    "msg": "响应成功",
    "time": 1535516959,
    "data": {
        "user_id": "用户ID", 
        "ext_id": "外部ID",
        "name": "用户姓名", 
        "empno": "工号或空", 
        "seqno": "组织内序号",
        "avatar": "头像URL或空", 
        "dept_ids": ["所在部门ID1", "所在部门ID2"],
        "deptinfo": [
            {"dept_id": "部门ID", "title": "部门职称"}
        ]
    }
}
  • 产品信息查询520

云应用可通过本指令查询某个产品型号的配置参数信息。请求示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 520, 
    "time": 1503025335, 
    "data": {
        "model": "产品型号",
    }
}

其中各参数说明如下:

参数 类型 描述
model 字符串 查询的目标产品型号

如果数据校验正确,平台会同步返回响应如下:

{
    "code": 0,
    "msg": "响应成功",
    "time": 1535516959,
    "data": {
        "model": "产品型号", 
        "name": "产品名称", 
        "type": "产品类型", 
        "icon": "产品图标URL地址", 
        "features": [ {
            "type": "特征类型",
            "value": "特征参数值",
        }],
        "properties": [{
            "name": "参数名",
            "text": "参数显示文本",
            "type": "参数值类型",
            "default_value": "参数默认值",
            "values": [{
                "value": "1", 
                "text": "值1"
            }]
        }],
        "firmware": { //参考103指令
            "version": "固件最新版本号", 
            "upgrade_type": "升级方式",  
            "file_path": "固件升级文件URL地址", 
            "checksum": "升级文件的MD5值",
            "update_time": 1541156953447,
            "description": "升级说明"
        }
    }
}
  • 组织信息查询521

云应用可通过本指令查询某个组织的基本信息。请求示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "action": 521, 
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID",
    }
}

其中各参数说明如下:

参数 类型 描述
org_id 字符串 查询的目标组织ID

如果组织存在且已安装该应用,则平台会同步返回响应如下:

{
    "code": 0,
    "msg": "响应成功",
    "time": 1535516959,
    "data": {
        "org_id": "用户组织ID",
        "name": "组织名称",
        "logo": "组织logo URL地址或空",
        "org_admin": {
            "user_id": "管理员ID", 
            "name": "姓名", 
            "empno": "工号或空", 
            "avatar": "头像URL或空"
        }
    }
}

响应结果内容与指令400完全一致。如果组织ID不存在或者应用未安装到该组织,则会返回对应的错误码。

  • APP版本信息查询522

平台支持APP升级发布的功能,注册到平台的APP,可以通过本指令以及平台分配的AppKey查询最新可升级的版本信息。

查询最新APP升级版本的请求示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 522, 
    "data": {
        "app_key": "软件key"
    }
}

如果AppKey存在,则平台会同步返回最新可升级响应如下:

{
    "code": 0,
    "msg": "响应成功",
    "time": 1535516959,
    "data": {
        "version": "1.1.0",
        "upgrade_type": "force",
        "url": "http://download.delicloud.com/app/third/xxxx.apk",
        "checksum": "9336ebf25087d91c818ee6e9ec29f8c1",
        "description": "解决了安卓4.4系统无法安装的问题",
        "update_time": 1527212643680
    }
}

各响应参数说明如下:

参数 类型 描述
version 字符串 APP最新版本
upgrade_type 字符串 升级类型,包括强制升级force和普通升级normal
url 字符串 APP最新升级文件下载地址
checksum 字符串 APP升级文件的MD5完整性校验值
description 字符串 升级说明
update_time 长整型 版本更新时间戳(毫秒)
  • 用户行为数据上报600

云端应用需要在应用内涉及到关键业务流程中埋点,将相关行为信息上报至云平台,具体上报内容由平台与应用开发商共同协商决定。

上报数据请求示例如下:

{
    "mid": "消息ID", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 600, 
    "data": {
        "user_id": "用户ID", 
        "org_id": "组织ID", 
        "app_id": "应用ID", 
        "device_id": "设备ID", 
        "event": "事件类型", 
        "event_time": 事件时间戳,
        "event_data": {
            //事件具体内容
        }
    }
}

其中各参数说明如下:

参数 类型 描述
user_id 字符串 事件发生的目标用户ID,如果与用户无关,不返回
org_id 字符串 事件发生的目标组织ID,如果与组织无关,不返回
app_id 字符串 事件发生的应用ID,如果与应用无关,不返回
device_id 字符串 事件发生的设备ID,如果与设备无关,不返回
event 字符串 事件类型,不同的事件类型不同。需要平台和应用一同确认
event_time 长整型 事件发生的UTC时间戳,精确到毫秒
event_data JSON 事件所产生的数据

接入环境

应用服务接入分测试环境和发布环节两种:

1.  测试环境:  http://t.cloudapp.delicloud.com/gateway
2.  正式环境:  https://cloudapp.delicloud.com/gateway