指令集概述

平台指令集是为了满足设备、平台以及应用三者之间相互的通信需要而设计。不同的指令集面向的通信目标不同，如下图所示：

设备->平台: 1xx指令
平台->设备: 2xx指令
平台->应用: 4xx指令
应用->平台: 5xx指令
设备-->>应用: 300/405指令
应用-->>设备: 500/301指令

所有的指令采用统一的JSON数据格式定义，指令消息结构如下：

{
    "mid": "消息ID", 
    "from": "发送方ID",
    "to": "接收方ID",
    "time": 时间戳, 
    "action": 指令,
    "data": {
        ......
    }
}
请求参数 格式 必传 参数说明
mid 字符串 Y 消息ID，长度不超过32位，用于唯一标示一条消息。如果消息存在上下文，也可以使用消息ID进行上下文标示，不同的消息应使用不同的mid
from 字符串 Y 消息的发送方ID
to 字符串 Y 消息的接受方ID
time 整型 Y 消息发送的时间戳(秒)
action 整型 Y 平台指令，不同的指令代表不同的业务
data JSON对象 N 平台指令关联的业务数据，不同的平台指令数据结构不同

如果发送方或平台方是平台系统，则使用固定字符串system代替，否则应使用在平台注册的发送方和接受方的唯一ID来标示。

所有指令消息中值为NULL的信息（一般是可选字段信息），平台会自动将其从序列化JSON字符串中去除。另外，协议在未来升级过程中会保持向下兼容性，但不排除增加新的字段信息。

设备->平台指令1xx

以下指令都是设备向平台发起请求的指令。设备通过与平台主动的指令交互，完成设备数据的上报或者平台设备数据的查询等操作。

网络正常的情况下，所有设备发送给平台的1xx指令请求都会及时返回响应结果。如果设备超过30s未收到响应结果，建议尝试重发指令请求。

平台响应结果中会固定携带响应错误码code和错误描述msg。如果平台处理正常，则code返回0，否则返回具体的错误代码和错误描述。

1xx指令可能返回的错误代码如下：

错误代码 错误消息 错误原因
104 请求已过期 请求时间time不正确，未与平台完成时间同步。指令100除外
105 请求已被封禁 设备行为异常，平台已禁止设备访问
106 不支持的操作指令 平台禁止设备使用该指令action
108 服务器繁忙 平台内部错误，一般是请求处理出现了未知异常。遇到该错误，请联系平台运维人员

个别指令特定的错误代码单独在指令响应中说明。

时间同步100

指令功能

通过本指令设备可获取平台当前的系统时间，并通过更新到本地使设备与平台保持相对一致的系统时间，避免因为时间不一致导致的业务问题。

建议所有接入平台的智能设备，至少在每次接入平台时，都先通过指令100进行一次时间同步。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 0, 
    "action": 100
}

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307375,
    "action": 100, 
    "data": {
        "code": 0,
        "msg": ""
    }
}
平台响应结果中的time字段即表示当前平台的时间（精确到秒），设备可直接使用该时间作为本地时间。如果设备需要更精确的时间同步，请使用开放的NTP服务，例如ntp1.aliyun.com；

设备状态上报101

指令功能

通过本指令，设备可将设备本地状态数据上报到平台，便于平台和设备所有者及时了解设备的最新状态。

设备应在每次接入平台时，或者本地状态数据发生变化时，都应主动触发上报。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 101,
    "data" : {
        "product_version": "1.0.0",
        "gps": "30.59276,114.30525",
        "mac": "00-01-6C-06-A6-29",
        "local_ip": "192.168.0.3",
        "connect_type": "wifi",
        "simulator": false,
        "status": 0,
        "status_code": "0",
        "status_msg": "正常",
        "properties": {
            "k_1": "v_1",
            "k_2": "v_2"
        }
    }
}
请求参数 格式 必传 参数说明
product_version 字符串 Y 设备当前固件的版本
gps 字符串 N 设备当前的GPS坐标，请返回WGS84坐标系的坐标位置。
local_ip 字符串 N 设备局域网内的ip地址
mac 字符串 N 设备网卡MAC地址
connect_type 字符串 N 设备当前接入网络的方式。包括:cable、wifi、4g等
simulator 字符串 N 是否模拟器，默认是false。
status 整型 Y 设备当前的工作状态: 0-正常；1-警告但可用；2-故障不可用；3-升级；默认是0。
status_code 字符串 N status对应的设备状态码。当status非0时返回的异常状态代码，由设备自定义。
status_msg 字符串 N status_code对应的设备状态描述
properties 字符串键值对 N 设备自定义的属性

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 101, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备状态查询102

指令功能

通过本指令设备可向平台主动查询设备在平台的相关产品配置、组织绑定状态信息。

建议设备在每次接入平台时主动调用该指令同步平台设备信息。另外，为了确保长期在线设备与平台数据的同步，建议设备接入平台后定时调用该指令进行同步操作，建议至少30分钟一次。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 102
}

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 102, 
    "data": {
        "code": 0,
        "msg": "",
        "status": 1,
        "name": "3960CT测试设备",
        "icon": "http://file.delicloud.com/product/3960CT.jpg",
        "last_access": 1561391999,
        "bound": true,
        "organization": {
            "org_id": "123513772057952257",
            "name": "得力集团",
            "logo": "组织logo"
        },
        "product_version": "1.1.0",
        "app_ids": ["492731092441235453"]
    }
}
响应参数 格式 必传 参数说明
status 整型 N 已废弃字段，用于标示设备是否被禁用
name 字符串 Y 设备名称。默认是产品名称，用户可设置自定义名称
icon 字符串 Y 设备对应的产品图标URL
bound Boolean Y 是否已绑定到组织。true表示已绑定，否则未绑定
organization JSON对象 N 设备绑定的组织基本信息，如果未绑定则不返回。包括:
org_id: 组织ID；
name: 组织名称；
product_version 字符串 N 设备当前可升级的最新固件版本。如果没有可升级版本，则不返回
last_access 整型 N 设备上次接入时间（精确到秒), 初次接入为0
app_ids JSON数组 Y 设备绑定的应用ID列表，目前仅支持同一时刻绑定1个应用

设备升级固件查询103

指令功能

本指令可用于设备向平台查询指定版本的固件信息。如果请求中未包含查询版本信息，则默认查询设备最新可升级版本的信息。

目前平台支持两种模式的固件升级：自动升级和手动升级。两种模式推荐的升级流程示意如下：

自动升级

对于使用自动升级模式的设备，升级过程中无用户确认过程，在设备通过指令102检测到有新版本固件时，即可调用指令103获取最新固件版本信息，并在固件下载完成后按照本地升级策略自动启动升级流程。

participant 管理员 as admin
participant 平台 as platform
participant 设备 as device

admin-->platform: 发布新固件

device->platform: 102指令查询平台设备状态
platform->device: 返回设备最新固件版本
device--device: 版本比对
Note left of device: 如果一致，则终止后续103指令

device->platform: 103指令查询最新可升级固件
platform->device: 返回升级固件信息

device--device: 下载固件
device->platform: 108指令上报下载进度
Note left of device: 持续上报，直到下载结束

device--device: 设备端等待用户确认（可选，部分设备支持）
Note left of device: 本地持续等待用户确认（策略自定义）

device-->device: 启动本地升级
device->platform: 108指令上报本地升级进度

Note left of device: 持续上报，直到升级结束

device-->device: 设备重启
device->platform: 101指令上报升级后固件版本

手动升级

对于使用用户手动升级模式的设备，设备仅在收到指令206后方可启动升级流程。为了提高升级效率，设备可以通过定时调用指令102和指令103提前下载固件到本地，在正式开始升级时节省固件下载的时间。

participant 管理员 as admin
participant 用户 as user
participant 平台 as platform
participant 设备 as device

admin-->platform: 发布新固件

device->platform: 102指令查询平台设备状态
platform->device: 返回设备最新固件版本
device--device: 版本比对
Note left of device: 如果一致，则终止后续103指令

device->platform: 103指令查询最新可升级固件
platform->device: 返回升级固件信息

device--device: 预先下载固件（可选&推荐）
device-->platform: 108指令上报下载进度
Note left of device: 持续上报，直到下载结束
platform-->user: 同步设备下载进度

user->platform: 手动发起设备升级
platform->device: 206指令通知设备升级
device--device: 下载固件
Note left of device: 如果固件下载未完成，则继续执行下载流程直到结束

device--device: 设备端等待用户确认（部分设备支持）
Note left of device: 本地持续等待用户确认（策略自定义）

device-->device: 启动本地升级
device->platform: 108指令上报本地升级进度
platform-->user: 同步设备升级进度
Note left of device: 持续上报，直到升级结束
device-->device: 设备重启
device->platform: 101指令上报升级后固件版本

注意

  1. 下载新固件包的时间，为了避免大量设备同时下载固件造成并发压力，不允许设备采用类似定时更新的机制，而是采用例如凌晨00:00～05:00这个时间段内的随机时间点；
  2. 设备升级会打扰用户的正常使用，对于自动升级设备，建议不要在用户使用高峰时间段内升级，而选择午夜凌晨等非用户使用时间段内下载升级包及触发本地升级过程；
  3. 设备在下载和升级固件的过程中，应支持通过指令108向平台上报升级进度；
  4. 基于设备硬件配置和升级风险不同，不同类型的设备可结合实际情况对推荐升级流程进行适当的自定义调整；

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 103,
    "data": {
        "version": "1.1.0"
    }
}
请求参数 格式 必传 参数说明
version 字符串 N 当前查询的固件版本号，如果未输入，则默认查询最新设备可升级的固件版本信息

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 103, 
    "data": {
        "code": 0,
        "msg": "",
        "version": "1.1.0",
        "upgrade_type": "force",
        "file_path": "http://file.delicloud.com/xxx.zip",
        "checksum": "4c56ff4ce4aaf9573aa5dff913df997a",
        "size": 1231,
        "update_time": 1555307488,
        "description": "解决了设备xx指令响应不正确的问题"
    }
}
响应参数 格式 必传 参数说明
version 字符串 Y 设备当前可升级的最新固件版本。
upgrade_type 字符串 Y 升级方式。兼容1.0平台协议，包括强制升级force和常规升级normal。2.0默认全部返回force。
file_path 字符串 Y 最新版本的HTTP下载地址
checksum 字符串 Y 固件的MD5值，用于下载后文件完整性校验。
size 整型 Y 文件的尺寸大小，单位是字节。
update_time 整型 Y 发布时间戳（精确到秒）
description 字符串 N 固件发布说明

设备主动解绑104

指令功能

通过本指令，设备可主动向平台发起主动解除组织绑定的请求，解除绑定后的设备可再次绑定新组织进行激活操作。

如果设备没有单独解除绑定的功能，那么当设备恢复出厂设置（reset）时，同时发送104指令解绑组织。

解除绑定成功后，平台会自动清理设备在绑定组织的关联数据，且该操作不可逆，请务必谨慎使用。

设备解绑成功后，平台会通过指令203异步通知设备解绑操作的执行结果，设备应当以203指令的响应作为解绑成功与否的判断依据，104的响应结果仅表示该操作请求平台已收到。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 104,
    "data": {
        "org_id": "325584307028705280"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 当前绑定的组织ID

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 104, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备异常告警105

指令功能

通过本指令，设备可向平台主动上报设备的各种异常状态和状态说明。该指令为售后指令，售后工程师可根据设备上报的异常告警消息对设备进行远程售后服务。

注意，该指令并非日志上报指令，请设备开发者仅在设备出现严重异常时上报，避免频繁调用该指令触发平台封禁机制。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 105,
    "data": {
        "code": 100,
        "msg": "网络Ping丢包率:80%"
    }
}
请求参数 格式 必传 参数说明
code 整型 Y 自定义异常告警代码
msg 字符串 Y 自定义异常告警消息

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 105, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备场景触发上报106 *

指令功能

对于支持通过设备端触发场景事件的设备类型，可通过本指令主动上报触发的场景事件消息以及对应的消息内容。所有上报的场景事件都需要提前通过平台进行预定义。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 106,
    "data": {
        "scene": "场景事件",
        "payload": {
           ...... 
        }
    }
}
请求参数 格式 必传 参数说明
scene 字符串 Y 设备触发的场景事件，事件名称由平台预定义。
payload JSON对象 N 场景数据对象，不同的场景的数据对象内容不同，由平台预定义给出。

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 106, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备行为数据采集107 *

指令功能

通过本指令设备可直接向平台数据中心上报设备本地行为数据，用于后续运营分析，具体设备可上报的行为事件及数据由平台预定义。

与106指令不同，该指令仅用于设备数据采集，不关联任何业务流程和操作。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 107,
    "data": {
        "event": "设备事件",
        "payload": {
            ......
        }
    }
}
请求参数 格式 必传 参数说明
event 字符串 Y 设备事件，事件名称由平台预定义。
payload JSON对象 N 事件数据对象，不同设备事件的数据对象内容不同，由平台预定义给出。

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 107, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备升级状态上报108 *

指令功能

设备进入升级状态后，可通过本指令向平台及时上报设备升级的状态变化。该指令一般与指令103和指令206配合使用。

注意，为了避免上报过于频繁，建议设备控制上报频率，例如2s/次，或根据进度变化进行上报。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 108,
    "data": {
        "version":"1.1.0",
        "step": 0,
        "status": 0,
        "progress": 80,
        "error": ""
    }
}
请求参数 格式 必传 参数说明
version 字符串 Y 当前设备升级的版本号
step 整型 Y 升级阶段。包括：0-等待用户确认，1-下载固件；2-本地升级。
其中，状态0是可选状态，仅在设备支持二次确认时使用。另外，出于体验性考虑，建议设备端在设计时优先考虑将等待用户确认放在固件下载完成之后。
status 整型 Y 升级状态。0-执行中；1-执行成功；2-执行失败；3-主动取消；
progress 整型 N 升级进度[0～100]。对于支持进度显示的设备，可在升级过程中返回升级进度百分值。
error 字符串 N 执行失败的错误消息。该信息仅在status为2时上传。

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 108, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

设备数据备份109 *

指令功能

设备可以通过本指令将本地一些重要的数据保存到云端，防止数据丢失。一般可用于设备本地重置等操作时，备份重要业务数据或用户配置。

每台设备在云端可存储的数据空间有限，如果超出限额，请求将会被拒绝。具体配额根据产品类型由管理员配置，默认1M

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 109,
    "data": {
        "key": "checkin-data-20190701",
        "value": "...",
        "expire": -1
    }
}
请求参数 格式 必传 参数说明
key 字符串 Y 需要存储的数据唯一键，不同的数据应该使用不同键，否则会被覆盖
value 字符串 Y 需要存储的数据值。如果是其他格式的数据，请先做转换。单个值的长度不要超过256k。如果将value设置为空，则视为删除操作
expire 整型 N 过期时间（秒）。缺省是-1，表示永不过期。数据如果过期，会被平台自动清理。

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 109, 
    "data": {
        "code": 0,
        "msg": ""
    }
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
120 存储空间超出限额 设备存储数据超出平台配额上限

设备数据恢复110 *

指令功能

该指令对应指令109，支持设备从云端下载之前存储在平台的未过期的设备数据。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 110,
    "data": {
        "key": "checkin-data-20190701"
    }
}
请求参数 格式 必传 参数说明
key 字符串 Y 数据KEY，与指令109上传的key保持一致

响应示例

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 110, 
    "data": {
        "code": 0,
        "msg": "",
        "value": "..."
    }
}
响应参数 格式 必传 参数说明
value 字符串 N 数据字符串。与指令109上传的value一致。如果key不存在，value则返回空

文字语音转换120*

指令功能

支持设备向平台提供文字索取语音文件url。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "system",
    "time": 1555307375, 
    "action": 120,
    "data": {
        "source_txt": "小明",
        "accept_type": "audio/mp3"
    }
}
请求参数 格式 必传 参数说明
source_txt 字符串 Y 待转换的原始文本，UTF-8编码，不允许超过64个汉字
accept_type 字符串 N 期待响应的格式，暂时只支持 "audio/mp3"，非必要字段

响应示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375,
    "action": 120,
    "data": {
        "code": 0,
        "msg": "",
        "source_txt": "小明",
        "content_type": "audio/mp3",
        "url": "http://xxxx/yy"
    }
}
响应参数 格式 必传 参数说明
source_txt 字符串 Y 待转换的原始文本，UTF-8编码，不允许超过64个汉字
content_type 字符串 Y 标准媒体类型 "audio/mp3"
url 字符串 Y 媒体url

平台->设备指令2xx

以下指令都是平台发送给设备的指令。平台通知这些指令对设备进行远程控制或同步平台的设备状态数据。

所有平台下发的2xx指令，设备在收到后都应及时给出确认响应。

远程设备控制200

指令功能

通过本指令，平台可对设备进行远程命令下发，实现远程控制，便于故障发生时进行远程售后处理。平台预留的设备远程控制命令cmd如下：

除了平台预留的命令之外，设备也可以自行实现更多远程控制命令已满足远程售后的需求。

1.日志查询log

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "log",
        "payload": {
            "day": "2019-04-16",
            "time_begin": "08:00",
            "time_end": "13:50"
        }
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令
payload JSON对象 N 命令对应的消息体，不同的命令消息体不同
day 字符串 Y 请求的日志日期，精确到天，格式：yyyy-MM-dd
time_begin 字符串 Y 查询的开始时间，精确到分钟，格式为HH:mm
time_end 字符串 Y 查询的结束时间，精确到分钟，格式为HH:mm

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "log", 
        "payload": {
            "day": "2019-04-16",
            "logs": "[08:00] Blalalala......"
        }
    }
}
响应参数 格式 必传 参数说明
cmd 字符串 Y 固定为log
payload JSON对象 Y 响应结果消息体
day 字符串 Y 与请求日志日期一致
logs 字符串 Y 日志字符串，包括日志时间和固件日志内容。注意，如果设备在查询时间段的日志过多，为了避免丢包，建议将日志拆分为多个响应返回。

2.设备重启reboot

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "reboot"
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "reboot" 
    }
}
设备回复200指令后，即可开始重启设备。

3.设备重连reconnect

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "reconnect"
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "reconnect"
    }
}
设备回复200指令后，即可断开连接开始重新连接平台。

4.设备自检health

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 200,
    "data": {
        "cmd": "health"
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 设备远程控制命令

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "health",
        "payload": {
            "passed": true,
            "details": "ok" 
        }
    }
}
响应参数 格式 必传 参数说明
cmd 字符串 Y 固定为health
payload JSON对象 Y 响应结果消息体
passed Boolean Y 是否自检通过。true表示通过，false表示不通过
details 字符串 N 自检详情。不同设备可根据实际自检项目返回检查明细结果

固件新版本通知202

指令功能

平台可通过本指令向设备发布新的固件版本。设备收到该指令消息后启动本地下载程序开始升级，并通过指令108更新升级进度。

注意，对于支持下载和升级过程分离的设备(推荐支持)，在收到本指令完成下载后，应通过指令108上报下载进度，并等待接收指令206后再启动升级流程。对于下载升级一体化的设备，则在完成下载后自动启动升级流程。

该指令并未实现，已废弃。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 202,
    "data": {
        "version": "1.1.0",
        "file_path": "http://file.delicloud.com/xxx.zip",
        "checksum": "4c56ff4ce4aaf9573aa5dff913df997a",
        "size": "1231",
        "update_time": 1555307488,
        "description": "解决了设备xx指令响应不正确的问题"
    }
}
请求参数 格式 必传 参数说明
version 字符串 Y 设备当前可升级的最新固件版本。
file_path 字符串 Y 最新版本的HTTP下载地址
checksum 字符串 Y 固件的MD5值，用于下载后文件完整性校验。
size 整型 Y 文件的尺寸大小，单位是字节。
update_time 整型 Y 发布时间戳（精确到秒）
description 字符串 N 固件发布说明

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 202
}

设备绑定更新通知203

指令功能

当设备与组织的绑定关系在平台发生变化时，平台会通过本指令通知设备更新绑定状态，包括设备通过指令104主动解绑，以及用户在终端APP上对设备进行绑定和解绑操作，都会触发平台发送本指令。

设备如果从组织解绑，逻辑上应该清理本地历史数据。但为了确保意外操作时设备本地重要数据不丢失，建议设备先通过指令109将缓存业务数据上传云端备份。另外为了尽可能避免用户数据丢失，建议设备仅在重新绑定到一个新组织时，触发本地历史数据清理动作。

考虑到网络消息存在丢失的可能性，设备应定时通过指令102查询平台的绑定状态，并对比本地绑定状态进行状态变更处理，避免平台与设备本地的绑定状态不一致，导致业务处理发生异常。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 203,
    "data": {
        "org_id": "411549919082446848",
        "name": "测试组织",
        "status": 0
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 设备关联的组织ID
name 字符串 Y 组织名称
status 整型 Y 绑定状态。0-已解绑，1-已绑定

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 203
}

设备应用关联通知204

指令功能

用户在绑定设备时，可以自行选择设备关联的应用系统（例如，一个考勤机型号可以有多家供应商提供的考勤应用系统支持），因此在设备绑定成功后，平台会通过本指令将当前关联的应用系统基本信息返回给设备。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 204,
    "data": {
        "app_id": "411549919082446848",
        "name": "测试应用",
        "icon": "http://file.delicloud.com/testapp.jpg",
        "status": 0
    }
}
请求参数 格式 必传 参数说明
app_id 字符串 Y 设备关联的应用ID。该应用ID可应用到指令300的to字段
name 字符串 N 应用名称，仅在绑定时返回
icon 字符串 N 应用图标URL，仅在绑定时返回
status 整型 Y 绑定状态，与指令203状态一致。如果设备与组织解绑，与应用的绑定状态也会自动解除绑定。

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 204
}

用户授权登录通知205

指令功能

对于某些特殊设备，出于安全或者业务需要，需要用户授权认证才能够正常使用，平台通过该指令可实时将用户授权状态信息返回给设备。

一旦授权成功，设备后端应用服务器即可将用户授权token等信息通过指令509发送给平台进行二次校验，完成设备登录操作。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 205,
    "data": {
        "user_id": "534417825331150848", 
        "org_id": "385097921973977088",
        "name": "测试用户", 
        "mobile": "13801234567", 
        "avatar": "http://file.delicloud.com/avatar/534417825331150848.jpg", 
        "expire": 1555381099, 
        "token": "9e0968df5433e10c709eab51ed6231c6",
        "status": 0
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 授权登录用户ID
org_id 字符串 Y 授权用户当前默认选择的组织ID
name 字符串 Y 授权登录用户姓名
mobile 字符串 Y 授权登录用户手机账户
avatar 字符串 N 授权登录用户的头像URL
expire 整型 N 授权Token的过期时间戳(秒)
token 字符串 N 授权的Token
status 整型 Y 授权状态。0-用户已扫码待确认状态，1-则表示用户确认授权成功，2-表示授权失败。

仅在status等于1的情况下，平台才会返回token以及相关的过期时间expire信息。

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 205
}

设备升级通知206 *

指令功能

对于支持用户手动控制升级的设备，当用户确认升级时，平台会向设备发送本指令通知。设备收到通知后，如果设备判断通知升级的版本可升级，应立刻调用指令103查询设备固件信息，启动升级流程。

设备升级过程中，应通过指令108向平台实时上报升级进度。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 206,
    "data": {
        "version": "1.1.0"
    }
}
请求参数 格式 必传 参数说明
version 字符串 Y 通知设备升级的最新固件版本

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 206
}

设备->应用指令3xx

以下指令都是设备与关联的线上应用系统通过平台交互的业务指令。通过这些指令，设备可以与应用系统完成具体业务场景下的信息交互。

设备推送消息到应用300

指令功能

设备通过该指令可向线上应用系统发送业务场景下的数据请求以及响应结果。指令300是一个通用的设备应用交互指令，所有从设备端发起与应用的交互都通过该指令完成，具体的交互内容可完全由设备及应用自定义设计。

该指令的to请设置为目标应用系统的ID，如果设备本地未保存，请设置为空字符串即可。

该指令消息发送到平台后，平台会将指令转换为指令405并转发给关联的线上应用系统，进行后续业务响应处理。

注意，平台可以针对不同的cmd进行配置管理，实现消息分流和自动应答等高级功能，具体配置请与平台管理员联系。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "411549919082446848",
    "time": 1555307375, 
    "action": 300,
    "data": {
        "cmd": "checkin",
        "payload": {
            "users":[
                {
                    "user_id":"450940540930752512",
                    "check_type":"fp",
                    "check_time":1557211726
                }
            ]
        }
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 设备发起的自定义业务请求命令
payload JSON对象 N 具体的业务请求数据。根据cmd的不同结构不同，由设备与应用协商自定义

响应示例

对于配置为“平台自动ack”的cmd，平台在收到消息后会及时通过指令301返回确认消息，避免设备因为超时未获得响应重复上传。

{
    "mid": "123456",
    "from": "system", 
    "to": "3960CT_1A45678910", 
    "time": 1555307488,
    "action": 301,
    "data": {
        "cmd": "checkin"
    }
}

否则，由应用系统根据实际业务协议设计进行指令301的响应。

设备接收应用消息301

指令功能

所有来自应用系统通过指令500发送给设备的消息，平台会自动转换为本指令下发给设备。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 301,
    "data": {
        "cmd": "user_sync",
        "payload": {
            ......
        }
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 应用下发到设备的自定义业务指令
payload JSON对象 N 具体的业务请求数据。根据cmd的不同结构不同，由设备与应用协商自定义

响应示例

如果设备需要对应用消息作出响应，请使用指令300发送。 其中，如果设备不支持该应用指令(例如固件版本太低，不支持某些新功能等)，请通过命令cmd_not_support进行响应，示例如下：

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "411549919082446848", 
    "time": 1555307488,
    "action": 300,
    "data": {
        "cmd": "cmd_not_support",
        "payload": {
            "src_cmd": "user_sync"
        }
    }
}

注意：同一个业务上下文的请求和响应，请确保使用相同的mid。

平台->应用指令4xx

以下指令都是平台推送消息到应用系统的指令。通过这些指令，平台可向应用推送应用关注的平台数据变化，或向应用请求业务数据。

平台统一采用POST方式向应用注册的webhook地址发起请求，请求中会携带平台消息的签名信息，便于应用进行消息合法性验证。 签名的计算方式如下:

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

其中签名用的appKey是由应用注册到开发者平台时获得。sig生成后放到HTTP的请求头部（Request Header）中，与请求参数一同发送给应用服务。

平台推送是否成功以应用返回的HTTP状态码作为确认依据。如果应用返回的HTTP状态码是200，则视为推送成功，否则视为失败。如果推送失败，平台会根据预定义的重发规则进行消息定时重发，直到应用返回正确的响应或者重发次数达到上限。

请注意，为了避免大量重发无效的消息，应用应该仅在业务逻辑处理失败，且希望平台对消息进行补发的时候返回错误响应！

组织设备绑定402

指令功能

当应用关联的硬件设备被绑定到云平台的用户组织时，平台会通过本指令向应用推送绑定的设备和组织信息。

为了确保应用中存储的是设备最新的数据，建议在设备绑定完成后通过指令508主动更新应用中的设备数据。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 402,
    "data": {
        "org_id": "385097921973977088",
        "device_id": "3960CT_1A45678910"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 设备绑定的组织ID。如果需要查询组织详情，请使用指令506
device_id 字符串 Y 设备ID。如果需要查询设备详情，请使用指令508

响应示例

同步返回HTTP状态码200即可，无其他要求。

组织设备解绑403

指令功能

与指令402对应，当设备与某个用户组织解绑时，会通过本指令通知应用解绑的设备和组织信息。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 403,
    "data": {
        "org_id": "385097921973977088",
        "device_id": "3960CT_1A45678910"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 设备绑定的组织ID。
device_id 字符串 Y 设备ID。

响应示例

同步返回HTTP状态码200即可，无其他要求。

设备上下线通知404

指令功能

当平台检测到设备的上下线状态发生变化时，会通过本指令通知应用。应用也可以通过指令508主动查询设备的在线状态数据。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 404,
    "data": {
        "device_id": "3960CT_1A45678910",
        "online": true
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 设备ID。
online 整型 Y 是否在线：true-在线，false-离线

响应示例

同步返回HTTP状态码200即可，无其他要求。

设备数据推送405

指令功能

设备推送消息给应用的指令300会在平台被转换为本指令，然后转发到应用。

如果应用需要对设备消息进行响应，请使用指令500。

请求示例

{
    "mid": "123456", 
    "from": "3960CT_1A45678910",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 405,
    "data": {
        "cmd": "checkin",
        "payload": {
            ......
        }
    }
}
具体请求的内容说明请参考指令300。

响应示例

同步返回HTTP状态码200即可，无其他要求。

组织更新通知406

指令功能

当组织信息发生变化时，平台会通过本指令向开放了组织数据同步权限的应用推送更新通知。

如果target是org，应用可通过指令506查询组织的最新信息。如果是其他的组织对象更新，可通过指令507发起对应的组织信息增量同步操作。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 406,
    "data": {
        "org_id": "385097921973977088",
        "target": "org"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 发生变化的组织ID。
target 字符串 Y 发生变化的数据对象类型。包括:
org: 组织更新，包括组织基本信息更新、组织解散等；
dept: 组织架构更新，包括添加部门、更新部门信息以及删除部门等；
member: 组织成员变更，包括添加成员、更新成员信息、删除成员以及成员所属部门变更等；
member.role: 成员角色变更，包括成员角色添加、角色移除等；

响应示例

同步返回HTTP状态码200即可，无其他要求。

场景触发动作推送407 *

指令功能

当某个预设用户场景发生时，根据预设的规则，平台会自动触发相应的动作，并通过本指令将场景的数据发送给应用进行后续工作。 例如用户在早上10点进入公司的场景事件发生时，可向考勤应用推送一个打卡的动作，并附带当前的用户场景信息。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 407,
    "data": {
        "cmd": "checkin",
        "payload": {
            "...": "..."
        }
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 平台预设场景发生时，应用触发的动作指令。
payload JSON对象 Y 平台预设场景发生时，场景相关的数据。

响应示例

同步返回HTTP状态码200即可，无其他要求。

设备数据更新408

指令功能

当平台检测到设备的基础数据发生了变化，包括设备名称、版本、工作/升级状态等等，平台会通过本指令通知应用。应用如果关注设备数据的变化，可通过指令508获取设备的最新数据。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 408,
    "data": {
        "device_id": "3960CT_1A45678910"
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 设备ID。

响应示例

同步返回HTTP状态码200即可，无其他要求。

应用数据请求409

指令功能

对于某些已授权访问指定组织数据的集成型应用，可通过指令516向平台发起应用数据请求，平台收到该请求后会转换为本指令发给目标应用，平台会将目标应用的处理结果同步转发给请求应用。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 409,
    "data": {
        "org_id": "385097921973977088",
        "cmd": "checkin_query",
        "payload": {
            ......
        }
    }
}

具体请求参数的定义请参考指令516。

响应示例

同步返回HTTP状态码200，并按照如下标准JSON数据格式将响应结果放在HTTP Body中。

{
    "code": 0, //0表示成功
    "msg": "错误描述",
    "data": {
        ......
    }
}
其中，响应错误code和msg由应用自定义。为了避免与平台错误码冲突造成歧义，请勿使用3位数（1～999）以内的错误码。

产品配置更新410 *

指令功能

当应用关联的设备产品型号配置在平台发生更新时，平台会通过本指令通知应用。应用可通过指令520主动查询最新的产品配置信息。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 410,
    "data": {
        "model": "3960CT"
    }
}

响应示例

同步返回HTTP状态码200即可，无其他要求。

组织网盘上传通知411 *

指令功能

应用通过js-sdk上传文件到组织网盘后，平台会通过本指令异步将上传结果通知到应用。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 411,
    "data": {
        "task_id": "2a2ae2dbcce4",
        "status": 0,
        "netdisk_path": "文件存储在组织网盘的绝对路径",
        "code": "错误代码",
        "msg": "错误描述"
    }
}
请求参数 格式 必传 参数说明
task_id 字符串 Y 上传任务ID，上传文件时同步返回给应用
status 整型 Y 上传状态。0-正在上传，1-上传成功，2-上传失败
netdisk_path 字符串 Y 文件存储在组织网盘的绝对路径
code 整型 N 错误代码。仅当status为2时返回
msg 字符串 N 错误描述。仅当status为2时返回

响应示例

同步返回HTTP状态码200即可，无其他要求。

应用授权登录通知412 *

指令功能

对于一些通过得力E+APP管理的应用，如果存在独立的应用终端，且需要进行用户登录授权时，例如云打印产品下的虚拟打印，当用户通过得力E+APP扫描登录二维码时，平台会通过本指令向应用实时通知登录授权的状态。

请求示例

{
    "mid": "123456", 
    "from": "system",
    "to": "411549919082446848",
    "time": 1555307348, 
    "action": 412,
    "data": {
        "sessionid": "12345",
        "user_id": "534417825331150848", 
        "org_id": "385097921973977088",
        "name": "测试用户", 
        "mobile": "13801234567", 
        "avatar": "http://file.delicloud.com/avatar/534417825331150848.jpg", 
        "status": 0
    }
}
请求参数 格式 必传 参数说明
sessionid 字符串 Y 与应用授权二维码中包含的sessionid一致，用于唯一标示授权终端会话
user_id 字符串 Y 授权登录用户ID
org_id 字符串 Y 授权用户当前默认选择的组织ID
name 字符串 Y 授权登录用户姓名
mobile 字符串 Y 授权登录用户手机账户
avatar 字符串 N 授权登录用户的头像URL
status 整型 Y 授权状态。0-用户已扫码待确认状态，1-则表示用户确认授权成功，2-表示授权失败。

响应示例

同步返回HTTP状态码200即可，无其他要求。

应用->平台指令5xx

以下指令是外部应用系统与平台通信的指令。通过这些指令，应用系统可以调用平台的功能，获取相关的业务数据以及与接入平台的智能设备通信。

所有应用请求消息请统一采用POST方式发起HTTP请求，且HTTP请求中的Content-Type应设置为application/json。另外，所有HTTP请求均需携带数字签名sig并附在HTTP请求头部，计算方式与平台4xx指令一致，如下:

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

平台收到5xx指令请求后，会同步返回处理的结果。如果请求出现异常，平台会通过响应结果中的code和msg返回具体的错误类型。

5xx指令可能返回的错误如下：

错误代码 错误消息 错误原因
100 请求数据异常 请求参数不正确或消息体过大
101 请求签名不正确 签名验证失败
104 请求已过期 请求时间time不正确，应用服务器时间与平台时间有较大误差
105 请求已被封禁 请求过于频繁等原因导致平台禁止了应用的请求
106 不支持的操作指令 应用未授权使用该指令
108 服务器繁忙 平台内部错误，请联系平台运维人员
111 应用不存在 通过应用IDto无法找到应用信息
112 应用已禁用 平台已禁止应用访问

个别指令特定的错误代码单独在指令响应中说明。

设备数据推送500

指令功能

当硬件设备绑定激活后，其关联的线上应用系统可以通过本指令向设备发送自定义的业务消息。平台会将该指令消息转换为指令301推送给设备。

注意，由于设备网络的不确定性，本指令消息并不能保证一定送达设备。如果应用需要确保消息送达，应结合指令300与设备实现自定义消息确认机制。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "3960CT_1A45678910",
    "time": 1555307375, 
    "action": 500,
    "data": {
        "cmd": "user_sync",
        "payload": {
            "...": "..."
        }
    }
}
请求参数 格式 必传 参数说明
cmd 字符串 Y 应用下发到设备的自定义业务指令
payload JSON对象 N 具体的业务请求数据。根据cmd的不同结构不同，由设备与应用协商自定义

响应示例

{
    "code": 0, 
    "msg": "处理成功", 
    "time": 1503025335
}

组织消息推送501

指令功能

应用通过本指令可向指定得力E+注册组织内的成员推送通知消息。推送消息需要应用预先向平台申请注册消息模版，审核通过后方可使用。

消息模版申请时除了消息文本之外，还可以额外附带一个消息链接地址，用于消息后处理的业务逻辑。组织成员点击该链接跳转时，APP会在HTTP请求头中附带当前E+注册用户ID(user_id)和登录token(token)信息，应用可通过指令509进行安全性校验。

注意，消息推送并不能保证100%送达用户。另外，如果是APP推送，在用户未激活的情况下也无法送达。

如果应用想向指定注册用户发送消息通知，请使用指令530。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 501,
    "data": {
        "client_id": "eplus_app",
        "org_id": "385097921973977088",
        "member_ids": [1, 2],
        "v1_member_ids": ["324970481749004307", "324970546749012311"],
        "push_type": 0,
        "template": "dmt_12345",
        "params": {
            "name": "得力智能产品发布会"
        }
    }
}
请求参数 格式 必传 参数说明
client_id 字符串 N 消息发送的终端APPID。如果未设置，则视为发送给E+APP。终端APPID由平台管理并分配给应用
org_id 字符串 Y 推送目标组织ID
member_ids 数组 N 推送消息的目标成员组织内的ID列表
v1_member_ids 数组 N 已废弃字段，与member_ids含义一致。在1.0平台用于唯一标示组织人员，出于兼容性考虑保留
push_type 整型 Y 推送方式。0-APP推送，1-短信
template 字符串 Y 发送通知消息的模板代码。所有模板必须在平台审核通过方可使用。模版示例: * 欢迎各位参加{name}，现场会有礼品赠送，先到先得！*
params JSON对象 N 模版消息自定义变量的值，KV结构。如果消息模版包含链接，则链接中使用的参数值也应包含在内

响应示例

{
    "code": 0, 
    "msg": "处理成功", 
    "time": 1503025335, 
    "data": {
        "member_ids": [1],
        "v1_member_ids": ["324970481749004307"]
    }
}
响应参数 格式 必传 参数说明
member_ids 数组 N 推送失败的组织成员ID列表
v1_member_ids 数组 N 已废弃字段，与member_ids含义一致。仅当请求时使用该字段标示人员时返回

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
121 消息模板不可用 通过template查找模板失败或未通过审核
122 消息发送限流 发送消息频率已达配置上限

自定义扫码注册504

指令功能

对于某些特殊的设备，其业务场景中会生成自定义的二维码，通过本指令可将该二维码信息注册到平台。注册成功后，通过得力E+APP可扫描该二维码并进行识别，自动跳转到设备应用界面进行处理。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 504,
    "data": {
        "qr_code": "https://mp.weixin.qq.com/a/wjSDsjkjfsdf23SAIIIdsadada~~",
        "org_id": "385097921973977088",
        "device_id": "3960CT_1A45678910",
        "expire": 3600
    }
}
请求参数 格式 必传 参数说明
qr_code 字符串 Y 自定义设备二维码文本
org_id 字符串 Y 设备所在组织ID
device_id 字符串 Y 设备ID
expire 整型 Y 二维码过期时间，单位是秒。

响应示例

{
    "code": 0, 
    "msg": "处理成功", 
    "time": 1503025335
}

组织成员授权认证505

指令功能

对于使用得力E+用户Token登录应用系统的场景，为了验证用户身份的有效性，应用系统可通过本指令使用用户在组织内的成员信息进行Token认证。如果认证通过，平台会同步返回用户作为组织内成员的基本信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 505,
    "data": {
        "org_id": "457515783040270336", 
        "member_id": 1, 
        "v1_member_id": "457515783040270336", 
        "token": "dfcf8d75b777c98516d3f2a29778e55ec4ca4238a0b923820dcc509a6f75849b",
        "client_id": "eplus_app"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 得力E+用户所在组织的ID
member_id 整型 N 组织人员在组织内部的唯一编号
v1_member_id 字符串 N 已废弃字段，和member_id定义一致，在1.0平台用于唯一标示一个组织人员，出于兼容性考虑保留。注意，仅当member_id不存在时，平台才会使用本字段信息
token 字符串 Y 用户登录获得的授权token
client_id 字符串 Y 登录该token的终端ID。
如果token来自得力E+APP，请设置为eplus_app，如果来自得力E+Web，请设置为eplus_web，其他情况请设置为用户登录时的终端ID。如果未设置，默认为视为eplus_app

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "member_id": 1,
        "v1_member_id": "457515783040270336",
        "user_id": "457515783040270336",
        "name": "小智",
        "employee_num": "A1234",
        "member_type": 0,
        "avatar": "http://file.delicloud.com/avatar/457515783040270336.jpg",
        "dept_ids": ["419806093141606400"], 
        "roles": ["admin"],
        "ext_id": "11111"
    }
}
响应参数 格式 必传 参数说明
member_id 整型 Y 组织人员在组织内部的唯一编号。
v1_member_id 字符串 Y 已废弃字段，在1.0平台用于唯一标示一个组织人员，出于兼容性考虑保留。
user_id 字符串 Y 得力E+注册用户ID
name 字符串 Y 用户在组织内的名称
employee_num 字符串 N 员工工号
member_type 整型 Y 人员类型。包括：0-成员；1-访客
avatar 字符串 N 人员头像URL
dept_ids JSON数组 N 当前用户在组织中的部门ID列表
roles JSON数组 N 当前用户在组织中的角色列表。如果未设置，则视为普通组织成员
ext_id 字符串 N 外部系统对接ID，仅在系统对接时使用

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
109 用户token无效 token不存在或已过期等

组织信息查询506

指令功能

应用可通过本指令查询指定组织的基本信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 506,
    "data": {
        "org_id": "385097921973977088"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 组织ID

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "org_id": "385097921973977088",
        "type": 0,
        "name": "测试组织",
        "industry": {
            "base": "IT",
            "category": "互联网/信息技术",
            "item": "游戏"
        },
        "owner": {
            "member_id": 1,
            "v1_member_id": "366596556425740288",
            "user_id": "457515783040270336",
            "name": "小智",
            "employee_num": "A1234",
            "avatar": "http://file.delicloud.com/avatar/457515783040270336.jpg"
        },
        "deleted": false
    }
}
响应参数 格式 必传 参数说明
org_id 字符串 Y 组织ID
type 整型 N 组织类型。包括: 0-组织组织；1-个人组织
name 字符串 N 组织名称
industry 字符串 N 组织行业 base: 基础信息（已弃用）; category:行业大类; item:行业小类
owner JSON对象 N 组织所有者信息。具体各字段的说明请参考507指令人员同步部分
deleted Boolean N 组织是否已删除，缺省是false。如果返回值是true，则说明组织已解散，仅返回org_id，应用需要将与该组织相关的数据做清理，例如解绑所有关联设备等。

组织数据增量同步507

指令功能

对于某些涉及组织内部人员业务逻辑处理的应用系统，当应用关联的设备绑定到组织后，应用可通过本指令主动增量同步组织的相关数据，包括组织部门信息、成员信息以及角色权限等。

另外，当平台通过指令406通知组织信息更新时，应用也可以触发本指令进行增量同步更新。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 507,
    "data": {
        "org_id": "385097921973977088",
        "target": "dept",
        "update_time": "-1",
        "size": 100
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 组织ID
target 字符串 Y 本次同步的组织数据类型，与指令406一致。注意，如果target是org，请使用指令506
update_time 字符串 Y 上次增量更新的最后时间戳，精确到毫秒，第一次同步请使用"-1"。
size 整型 Y 本次增量同步的更新请求数量，一次最多300条。

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "target": "dept",
        "update_time": "1557821981123",
        "size": 2,
        "payload": [

        ]
    }
}
响应参数 格式 必传 参数说明
target 字符串 Y 本次同步的组织数据类型，与请求一致
update_time 字符串 Y 本次增量同步数据的最大时间戳，用于下次增量同步的请求参数
size 整型 Y 本次增量同步返回的条目数，与payload条目数一致
payload JSON数组 Y 按照时间戳条件返回的增量更新数据列表

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
110 组织不存在或已解散 通过org_id找不到组织信息

针对不同的target, 平台返回的数据格式不同。包括：

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "target": "dept",
        "update_time": "1557821981123",
        "size": 2,
        "payload": [
            {
                "dept_id": "457515783040270336",
                "name": "测试部门1",
                "pid": "0",
                "ext_id": "11111",
                "manager_ids": [1],
                "v1_manager_ids": ["457515783040270336"],
                "update_time": "1555307375122"
            }, {
                "dept_id": "457515783040435345",
                "deleted": true,
                "update_time": "1557821981123"
            }
        ]
    }
}
响应参数 格式 必传 参数说明
dept_id 字符串 Y 组织部门ID
name 字符串 N 部门名称
pid 字符串 N 父级部门ID，如果是顶级部门，则pid为0
ext_id 字符串 N 外部系统的部门ID，仅在系统对接时使用
manager_id JSON数组 N 部门主管ID，对应成员的member_id
v1_manager_id JSON数组 N 已废弃，兼容1.0平台的部门主管ID，对应成员的v1_member_id
deleted Boolean N 是否是删除操作，缺省是false。如果返回值是true，则视为部门被删除，除dept_id外，其他信息不返回。
update_time 字符串 Y 数据更新时间戳 
{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "target": "member",
        "update_time": "1557821981123",
        "size": 2,
        "payload": [
            {
                "member_id": 1,
                "v1_member_id": "366596556425740288",
                "user_id": "457515783040270336",
                "name": "小智",
                "employee_num": "A1234",
                "member_type": 0,
                "avatar": "http://file.delicloud.com/avatar/457515783040270336.jpg",
                "ext_id": "11111",
                "ext_extra_info": {},
                "dept_ids": ["457515783040270336"],
                "title": "销售代表",
                "update_time": "1555307375122"
            }, {
                "member_id": 2,
                "v1_member_id": "375322828781293569",
                "deleted": true,
                "update_time": "1557821981123"
            }
        ]
    }
}
响应参数 格式 必传 参数说明
member_id 整型 Y 组织人员在组织内部的唯一编号。
v1_member_id 字符串 Y 已废弃字段，在1.0平台用于唯一标示一个组织人员，出于兼容性考虑保留。
user_id 字符串 N 对应的得力E+注册用户ID。仅在组织成员是得力E+注册用户时返回
name 字符串 N 用户在组织内的名称
employee_num 字符串 N 员工工号
member_type 整型 N 人员类型。包括：0-成员；1-访客
avatar 字符串 N 人员头像URL
ext_id 字符串 N 外部系统对接ID，仅在系统对接时使用。
ext_extra_info 字符串 N 外部系统对接写入的自定义人员业务信息，请参考这里。
dept_ids JSON数组 N 已废弃字段，成员所属部门ID列表。
title 职称 N 成员在企业组织内的职称
deleted Boolean N 是否是删除操作，缺省是false。如果返回值是true，则视为人员从组织移除，除member_id外，其他信息不返回。
update_time 字符串 Y 数据更新时间戳 
{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "target": "member.role",
        "update_time": "1557821981123",
        "size": 2,
        "payload": [
            {
                "member_id": 1,
                "v1_member_id": "366596556425740288",
                "role": "admin",
                "update_time": "1555307375122"
            },{
                "member_id": 2,
                "v1_member_id": "375322828781293569",
                "role": "admin",
                "deleted": true,
                "update_time": "1557821981123"
            }
        ]
    }
}
响应参数 格式 必传 参数说明
member_id 整型 Y 组织人员在组织内部的唯一编号。
v1_member_id 字符串 Y 已废弃字段，在1.0平台用于唯一标示一个组织人员，出于兼容性考虑保留。
role 字符串 Y 组织成员的角色标示。
deleted Boolean N 是否是删除操作，缺省是false。如果返回值是true，则表示成员角色被移除。

组织成员角色是组织成员权限的集合，包括：平台预定义组织角色和应用自定义业务角色两大类。 其中，平台预定义角色如下：

角色 角色说明
su 组织所有者，能够管理组织内的所有资源，是组织内最高权限所有者
admin 组织管理员，除了不能管理组织基本信息、解散组织、设置管理员之外，其他权限与组织所有者一致

设备信息查询508

指令功能

应用可通过本指令查询指定关联设备的平台注册信息，包括设备名称、产品型号、固件版本、工作/升级状态以及是否在线等等。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 508,
    "data": {
        "device_id": "3960CT_1A45678910"
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 设备唯一ID

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "device_id": "3960CT_1A45678910",
        "model": "3960CT",
        "name": "前台考勤机",
        "product_version": "1.0.0",
        "online": true,
        "status": 0,
        "status_code": "",
        "status_msg": "",
        "bound": false,
        "upgrade_info": {
            "version": "1.1.0",
            "step":0,
            "status": 0,
            "progress": 80,
            "error": "",
            "time": 1555306395
        },
        "extra_properties": {
            "ip": "117.150.193.255",
            "mac": "00-01-6C-06-A6-29",
            "gps": "30.59276,114.30525",
            "connect_type": "wifi",
            "local_ip": "192.168.0.3"
        }
    }
}
响应参数 格式 必传 参数说明
device_id 字符串 Y 设备唯一ID
model 字符串 Y 设备对应的产品型号。产品配置查询请使用指令520
name 字符串 Y 设备当前设置的名称
product_version 字符串 N 设备固件版本号
online Boolean Y 设备在线状态。true表示在线，否则是离线
status 整型 Y 设备工作状态。与指令101一致
status_code 字符串 N 设备状态码。与指令101一致
status_msg 字符串 N 设备状态描述。与指令101一致
bound Boolean Y 是否已绑定到组织。true表示已绑定，否则是未绑定
upgrade_info JSON对象 N 仅在设备处于升级状态时返回，参数与指令108一致，time表示设备上报升级状态的时间
extra_properties JSON对象 Y 更多设备的自定义属性，每个设备根据其硬件功能不同，可返回不同的自定义属性列表

用户授权认证509

指令功能

对于使用得力E+用户Token登录应用系统的场景，为了验证用户身份的有效性，应用系统可通过本指令进行Token认证。如果认证通过，平台会同步返回用户的基本信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 509,
    "data": {
        "user_id": "457515783040270336", 
        "token": "dfcf8d75b777c98516d3f2a29778e55ec4ca4238a0b923820dcc509a6f75849b",
        "client_id": "411549919082446848"
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 得力E+用户ID
token 字符串 Y 用户登录获得的授权token
client_id 字符串 N 登录该token的终端ID。根据token的来源设置不同：
如果token来自得力E+APP，请设置为eplus_app；
如果token来自得力E+Web，请设置为eplus_web；
其他情况请设置为用户登录时的终端ID；
如果未设置，默认视为eplus_app。

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "user_id": "457515783040270336",
        "name": "小智",
        "avatar": "http://file.delicloud.com/avatar/457515783040270336.jpg"
    }
}
响应参数 格式 必传 参数说明
user_id 字符串 Y 用户ID
name 字符串 Y 用户姓名。
avatar 字符串 N 用户头像URL

响应结果仅包含当前用户在得力E+的个人注册基本信息，如果需要查询用户更多的开放个人信息，请使用指令526。如果应用想查询用户在某个组织内的信息，则请使用指令519。

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
109 用户token无效 token不存在或已过期等

获取组织授权令牌510

指令功能

管理员可通过本指令获取组织资源授权访问令牌，通过分享令牌给第三方，可临时授权第三方以管理员的名义对组织进行受限操作，例如加入组织等。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 510,
    "data": {
        "org_id": "385097921973977088", 
        "admin_id": "457515783040270336",
        "token_type": 0
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 需要进行受限访问的组织ID
admin_id 字符串 Y 授权第三方访问组织资源的管理员用户ID
token_type 整型 Y 授权令牌类型。包括：0-用户加入组织

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "token": "c4ca4238a0b923820dcc509a6f75849b",
        "expire": "1555481029000"
    }
}
响应参数 格式 必传 参数说明
token 字符串 Y 组织生成的临时授权访问令牌
expire 字符串 Y 令牌过期时间(毫秒)

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
103 权限不足 用户并非管理员，无法进行授权
110 组织不存在或已解散 通过org_id找不到组织信息

发送验证码511

指令功能

对于支持使用得力E+账户注册登录操作的外部应用系统，可使用本指令发送短信验证码进行相关操作。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 511,
    "data": {
        "region": "86", 
        "mobile": "1381234567",
        "mode": 1
    }
}
请求参数 格式 必传 参数说明
region 字符串 N 手机号区域编码，默认是86，表示中国
mobile 字符串 Y 手机号码。得力E+默认使用手机号码作为登录账户
mode 整型 Y 验证码类型。包括：1-注册,2-密码找回,3-短信登录

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
116 账户已注册 发送注册短信，如果该账户已注册时返回
117 账户未注册 发送密码找回短信，如果该账户未注册时返回
127 验证码发送太频繁 验证码发送次数超出限制

账户注册512

指令功能

应用可通过本指令直接向得力E+注册新的用户账户。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 512,
    "data": {
        "region": "86", 
        "mobile": "1381234567",
        "password": "c4ca4238a0b923820dcc509a6f75849b",
        "veri_code": "789012"
    }
}
请求参数 格式 必传 参数说明
region 字符串 N 手机号区域编码，默认是86，表示中国
mobile 字符串 Y 手机号码。得力E+默认使用手机号码作为登录账户
password 字符串 N 用户密码的MD5值，如果为空，则之后可以使用指令533设置密码
veri_code 字符串 Y 注册验证码。使用指令511获取

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375, 
    "data": {
        "user_id": "355672617635545088"
    }
}
响应参数 格式 参数说明
user_id 字符串 注册新用户在得力E+中的唯一ID

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
116 账户已注册 账户已注册
118 短信验证码错误 验证码输入错误或已过期

账户重置513

指令功能

应用可通过本指令重置某用户的密码，便于用户密码丢失时恢复使用。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 513,
    "data": {
        "region": "86", 
        "mobile": "1381234567",
        "password": "c4ca4238a0b923820dcc509a6f75849b",
        "veri_code": "789012"
    }
}
请求参数 格式 必传 参数说明
region 字符串 N 手机号区域编码，默认是86，表示中国
mobile 字符串 Y 手机号码。得力E+默认使用手机号码作为登录账户
password 字符串 Y 用户重置新密码的MD5值
veri_code 字符串 Y 重置验证码。使用指令511获取

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
117 账户未注册 账户未注册
118 短信验证码错误 验证码输入错误或已过期

密码修改514

指令功能

应用可通过本指令修改得力E+用户的密码。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 514,
    "data": {
        "user_id": "355672617635545088", 
        "password": "c4ca4238a0b923820dcc509a6f75849b",
        "new_password": "351e07728ece5c08c65c057b5ceef049"
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 当前得力E+用户ID
password 字符串 Y 原始密码的MD5值
new_password 字符串 Y 修改后密码的MD5值

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
115 账户或密码错误 原密码输入错误
119 用户不存在 通过user_id找不到用户信息

账户登录515

指令功能

应用可通过本指令进行得力E+用户登录操作。登录成功后，会返回当前应用场景下用户登录后的授权信息。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 515,
    "data": {
        "mode": 1, 
        "region": "86", 
        "mobile": "1381234567",
        "password": "c4ca4238a0b923820dcc509a6f75849b"
    }
}
请求参数 格式 必传 参数说明
mode 整型 Y 登录方式。1-密码登录；2-短信登录
region 字符串 N 手机号区域编码，默认是86，表示中国
mobile 字符串 Y 手机号码。得力E+默认使用手机号码作为登录账户
password 字符串 Y 用户密码的MD5值

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "user_id": "355672617635545088",
        "token": "c4ca4238a0b923820dcc509a6f75849b",
        "expire": "1555481029000"
    }
}
响应参数 格式 参数说明
user_id 字符串 注册新用户在得力E+中的唯一ID
token 字符串 登录验证通过后的授权Token
expire 字符串 过期时间(精确到毫秒)

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
115 账户或密码错误 密码登录模式下，如果账户不存在或密码输入错误
118 短信验证码错误 短信登录模式下，如果短信验证码输入错误或已过期

应用请求516

指令功能

对于已获得组织授权许可的集成应用，可以通过本指令请求组织下关联的其他应用系统开放的业务API，用于系统集成。平台接收到该指令后会转换为指令409推送给目标应用。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "459053187953852416",
    "time": 1555307375, 
    "action": 516,
    "data": {
        "org_id": "385097921973977088",
        "cmd": "checkin_query", 
        "payload": {
            "...": "..."
        }
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 请求查询的目标组织ID。本指令仅支持查询某个指定组织范围的开放接口数据
cmd 字符串 Y 目标应用to开放调用的自定义业务指令
payload JSON对象 N 业务指令对应的请求参数

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "...": "..."
    }
}

其中，data包括了指令409请求的HTTP响应消息体。

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
113 应用请求失败 应用接口不可访问或请求异常

账户查询517

指令功能

应用使用本指令可通过用户手机号码查询用户是否已注册。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 517,
    "data": {
        "region": "86", 
        "mobile": "1381234567"
    }
}
请求参数 格式 必传 参数说明
region 字符串 N 手机号区域编码，默认是86，表示中国
mobile 字符串 Y 手机号码。得力E+默认使用手机号码作为登录账户

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "user_id": "355672617635545088"
    }
}
响应参数 格式 必传 参数说明
user_id 字符串 N 用户ID, 仅在用户存在时返回

如果用户并未注册，则data为空。

账户注销518

指令功能

应用可通过本指令对已登录的用户进行注销操作，注销后登录的授权Token将自动失效。

v2.0协议不推荐继续使用该指令，建议直接使用得力E+用户SDK模块集成到应用APP。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 518,
    "data": {
        "user_id": "355672617635545088",
        "token": "39e4813fa000ad14324167321fec912d698d51a19d8a121ce581499d7b701668"
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 需要注销登录的用户ID
token 字符串 Y 需要注销登录的用户Token

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

用户组织信息查询519

指令功能

应用通过本指令可查询指定得力E+用户在特定组织内的人员信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 519,
    "data": {
        "user_id": "457515783040270336",
        "org_id": "459053187953852416"
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 用户在得力E+的注册用户ID
org_id 字符串 Y 人员所在组织ID

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "member_id": 1,
        "v1_member_id": "457515783040270336",
        "user_id": "457515783040270336",
        "name": "小智",
        "employee_num": "A1234",
        "member_type": 0,
        "avatar": "http://file.delicloud.com/avatar/457515783040270336.jpg",
        "dept_ids": ["419806093141606400"], 
        "roles": ["admin"],
        "ext_id": "11111"
    }
}
响应参数 格式 必传 参数说明
member_id 整型 Y 组织人员在组织内部的唯一编号。
v1_member_id 字符串 Y 已废弃字段，在1.0平台用于唯一标示一个组织人员，出于兼容性考虑保留。
user_id 字符串 Y 得力E+注册用户ID
name 字符串 Y 用户在组织内的名称
employee_num 字符串 N 员工工号
member_type 整型 Y 人员类型。包括：0-成员；1-访客
avatar 字符串 N 人员头像URL
dept_ids JSON数组 N 当前用户在组织中的部门ID列表
roles JSON数组 N 当前用户在组织中的角色列表。如果未设置，则视为普通组织成员
ext_id 字符串 N 外部系统对接ID，仅在系统对接时使用

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
110 组织不存在或已解散 通过org_id找不到组织信息
114 用户不属于组织 用户不是组织成员

产品信息查询520

指令功能

应用可根据本指令查询指定产品型号的平台配置信息。建议在收到指令410时，主动调用本指令更新产品配置信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 520,
    "data": {
        "model": "3960CT"
    }
}
请求参数 格式 必传 参数说明
model 字符串 Y 产品型号，产品的唯一标示

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "model": "3960CT",
        "name": "指纹考勤机3960CT",
        "icon" : "http://file.delicloud.com/product/3960CT.jpg",
        "status": 1,
        "product_group_code": "KQ",
        "properties": [
            {
                "code": "check_type",
                "title": "打卡方式",
                "value": "fa,fp"
            },
            {
                "...": "..."
            }
        ]
    }
}
响应参数 格式 必传 参数说明
model 字符串 Y 产品型号
name 字符串 Y 产品名称
icon 字符串 Y 产品图标URL
status 整型 Y 产品上架状态，0-未上架；1-已上架；2-已下架
product_group_code 字符串 Y 产品分类的code， 例如KQ-考勤机， MJ-门禁机， QD-签到机
properties JSON对象 N 产品配置的业务属性列表。各属性值说明如下：
code:属性键；
title: 属性名称；
value:自定义属性值

产品的自定义业务属性由开发者通过开发者平台自定义，平台无格式限制。

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
124 产品不存在 通过model找不到产品信息

APP版本查询522

指令功能

对于通过得力E+进行终端APP发布的应用系统，可通过本指令查询已发布的最新版本信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 522,
    "data": {
        "app_key": "411549919082446848.ios"
    }
}
请求参数 格式 必传 参数说明
app_key 字符串 Y app终端ID，用于唯一标示某个应用的特定终端APP

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "version": "1.1.0",
        "upgrade_type": "force",
        "url" : "http://file.delicloud.com/app/xxxx.apk",
        "size": 13456,
        "checksum": "9336ebf25087d91c818ee6e9ec29f8c1",
        "description": "解决了安卓4.4系统无法安装的问题",
        "update_time": 1555481029
    }
}
响应参数 格式 必传 参数说明
version 字符串 Y 最新app发布版本
upgrade_type 字符串 Y 升级类型，包括强制升级force和普通升级normal
url 字符串 Y app下载地址
size 整型 Y app新版本的字节大小
checksum 字符串 Y app新版本的md5校验和，用于完整性校验
description 字符串 N app新版本的发布说明
update_time 整型 Y 发布时间，精确到秒

当可升级版本不存在时，data不返回。

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
123 app终端不存在 通过app_key找不到app终端信息

设备绑定523 *

指令功能

对于某些通过独立APP接入设备的业务场景，可通过本指令主动将设备绑定到用户在得力E+中的个人组织，用于统一管理。

注意，如果设备不支持直接接入云平台进行注册，应用需要在绑定之前通过指令528将设备信息提前注册到平台，否则绑定会发生错误。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 523,
    "data": {
        "device_id": "XD10_1234567890",
        "user_id": "355672617635545088",
        "force_bind": true
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 设备唯一ID
user_id 字符串 Y 绑定设备的得力E+注册用户ID。每个E+用户都会默认拥有一个唯一的个人组织
force_bind Boolean N 是否强制绑定，缺省值是false。如果设置为true，则不论设备是否已绑定到其他个人组织，都会强行绑定到新的个人组织

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "org_id": "459053187953852416"
    }
}
响应参数 格式 必传 参数说明
org_id 字符串 Y 绑定的用户个人组织ID

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
126 设备已绑定 设备已绑定到别的用户组织，不能重复绑定。该异常仅在force_bind为false时抛出

设备解绑524 *

指令功能

与指令523对应，应用可主动解除已绑定到得力E+用户个人组织的设备。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 524,
    "data": {
        "device_id": "XD10_1234567890",
        "user_id": "355672617635545088"
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 设备唯一ID
user_id 字符串 Y 解绑设备的用户ID

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
107 设备未绑定激活 该设备并未绑定到用户个人组织

设备升级固件查询525 *

指令功能

该指令与指令103类似，通过该指令应用系统可主动查询指定设备最新可升级的固件版本信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 525,
    "data": {
        "device_id": "3960CT_1A45678910"
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 设备ID

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "version": "1.1.0",
        "file_path": "http://file.delicloud.com/xxx.zip",
        "checksum": "4c56ff4ce4aaf9573aa5dff913df997a",
        "size": 1231,
        "update_time": 1555307488,
        "description": "解决了设备xx指令响应不正确的问题"     
    }
}
响应内容说明与指令103一致。

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
102 设备未注册 通过device_id找不到设备信息

用户信息查询526 *

指令功能

应用可通过本指令向云平台查询指定得力E+注册用户开放查询的用户属性信息。

目前得力E+开放查询的属性列表请点击这里。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 526,
    "data": {
        "user_id": "355672617635545088",
        "properties": ["age", "hobbies"]
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 得力E+注册用户ID
property 字符串 Y 需要查询的用户属性键名称

响应示例

{
    "code": 0,
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "age": [{
            "value": 18,
            "update_time": "1555307375123"
        }, {
            "value": 17,
            "update_time": "1555201312678"
        }],
        "hobbies": []
    }
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
119 用户不存在 通过user_id找不到用户信息

用户信息上报527 *

指令功能

应用可通过本指令上报用户在应用场景中产生的用户信息资料。

应用上报的自定义用户属性信息，默认情况下是不公开的（通过指令526无法查询），如果允许开放给其他应用服务使用，那么需要由平台管理员配置。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 527,
    "data": {
        "user_id": "355672617635545088",
        "properties": [
            {
                "property": "age",
                "value": 18
            },
            {
                "property": "hobbies",
                "value": "篮球、读书、唱歌"
            }
        ]
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 得力E+注册用户ID
properties JSON数组 Y 用户在应用场景中的自定义属性信息列表。属性内容定义如下：
property: 属性键，字符串类型;
value: 属性值，可以是字符串、整型等基本类型。

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
119 用户不存在 通过user_id找不到用户信息

设备信息上报528 *

指令功能

对于不直接接入平台网关的设备（例如类似微打等通过独立APP直连接入的设备），一旦设备信息发生变化，应用应通过本指令将设备信息上报到平台。

如果设备未注册，则平台会自动注册，否则会自动更新设备信息。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 528,
    "data" : {
        "sn": "3960CT_1A45678910",
        "model": "3960CT",
        "product_version": "1.0.0",
        "gps": "30.59276,114.30525",
        "mac": "00-01-6C-06-A6-29",
        "connect_type": "wifi",
        "status": 0,
        "status_code": "0",
        "status_msg": "正常"
    }
}
请求参数 格式 必传 参数说明
sn 字符串 Y 设备ID
model 字符串 Y 设备的产品型号
product_version 字符串 Y 设备当前固件的版本
gps 字符串 N 设备当前的GPS坐标，请返回WGS84坐标系的坐标位置。
mac 字符串 N 设备网卡MAC地址
connect_type 字符串 N 设备当前接入网络的方式。包括:cable、wifi、4g等
simulator 字符串 N 是否模拟器，默认是false。
status 整型 Y 设备当前的工作状态: 0-正常；1-警告但可用；2-故障不可用；3-升级；默认是0。
status_code 字符串 N status对应的设备状态码。当status非0时返回的异常状态代码，由设备自定义。
status_msg 字符串 N status_code对应的设备状态描述

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
123 产品不存在 通过model找不到产品信息

网盘文件上传529 *

指令功能

应用通过本指令可以将应用内产生的组织业务文件上传到组织网盘进行保存。每个应用在组织网盘都会有一定指定的根目录，所有上传文件都会在该根目录下。

上传网盘文件是一个相对耗时的操作，指令执行完成后会立刻返回上传任务的任务ID，后续平台会通过指令411异步通知上传结果。

本指令暂不支持

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 529,
    "data": {
        "org_id": "385097921973977088",
        "file_name": "考勤报表20190101.xlsx",
        "file_url": "http://file.delicloud.com/考勤报表20190101.xlsx",
        "upload_path": "/201901/reports"
    }
}
请求参数 格式 必传 参数说明
org_id 字符串 Y 组织网盘所在组织ID
file_name 字符串 Y 文件名
file_url 字符串 Y 文件的网络下载地址。平台会通过该地址下载文件源文件
upload_path 字符串 N 上传到组织网盘应用根目录的相对路径。如果未指定，则会自动保存到组织网盘应用的根目录

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "task_id": "2a2ae2dbcce4",
        "netdisk_path": "/kq/201901/reports/考勤报表20190101.xlsx"
    }
}
响应参数 格式 必传 参数说明
task_id 字符串 Y 上传任务ID。后续平台会通过指令411异步返回该任务的上传进度
netdisk_path 字符串 Y 文件存储在组织网盘的绝对路径

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
125 组织网盘未开通 组织管理员并未开启网盘功能

用户消息推送530 *

指令功能

应用通过本指令可向指定得力E+注册用户推送通知消息。推送消息需要应用预先向平台申请注册消息模版，审核通过后方可使用。

消息模版申请时除了消息文本之外，还可以额外附带一个消息链接地址，用于消息后处理的业务逻辑。用户点击该链接跳转时，APP会在HTTP请求头中附带当前E+注册用户ID(user_id)和登录token(token)信息，应用可通过指令509进行安全性校验。

注意，消息推送并不能保证100%送达用户。另外，如果是APP推送，在用户未激活的情况下也无法送达。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 530,
    "data": {
        "client_id": "eplus_app",
        "user_ids": ["324970546749012311", "355672617635545088"],
        "push_type": 0,
        "template": "dmt_12345",
        "params": {
            "name": "早会签到"
        }
    }
}
请求参数 格式 必传 参数说明
client_id 字符串 N 消息发送的终端APPID。如果未设置，则视为发送给E+APP。终端APPID由平台管理并分配给应用
user_ids 数组 Y 推送消息的目标E+用户ID列表
push_type 整型 Y 推送方式。0-APP推送，1-短信
template 字符串 Y 发送通知消息的模板代码。所有模板必须在平台审核通过方可使用。模版示例: * 欢迎各位参加{name}，现场会有礼品赠送，先到先得！*
params JSON对象 N 模版消息自定义变量的值，KV结构。如果消息模版包含链接，则链接中使用的参数值也应包含在内

响应示例

{
    "code": 0, 
    "msg": "处理成功", 
    "time": 1503025335, 
    "data": {
        "user_ids": ["324970546749012311"]
    }
}
响应参数 格式 必传 参数说明
user_ids 数组 N 推送失败的用户ID列表。如果都推送完成，则不返回

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
121 消息模板不可用 通过template查找模板失败或未通过审核
122 消息发送限流 发送消息频率已达配置上限

设备固件升级531 *

指令功能

应用可通过本指令控制设备启动固件升级流程，平台收到该指令请求后会将请求转换为指令206下发给设备。该指令一般与指令525配合使用。

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 531,
    "data": {
        "device_id": "3960CT_1A45678910",
        "version": "1.1.0"
    }
}
请求参数 格式 必传 参数说明
device_id 字符串 Y 目标升级设备ID
version 字符串 Y 请求设备升级的固件版本号

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
102 设备未注册 通过device_id找不到设备信息

检查用户密码是否为空532 *

指令功能

检查用户密码是否为空， 如果用户密码为空，那么可以使用指令533初始化用户密码

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 532,
    "data": {
        "user_id": "4894023842304293"
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 用户id

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375,
    "data": {
        "empty_password": true
    }
}
响应参数 格式 必传 参数说明
empty_password Boolean Y 用户密码是否为空

初始化用户密码533 *

指令功能

如果用户注册时（使用指令512注册用户）初始密码为空，那么可以使用本指令初始化用户密码

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 533,
    "data": {
        "user_id": "4894023842304293",
        "password": "rdaesfdsfdsfdsdsfdsfdsfd"
    }
}
请求参数 格式 必传 参数说明
user_id 字符串 Y 用户id
password 字符串 Y 用户密码的MD5值

响应示例

{
    "code": 0, 
    "msg": "处理成功",
    "time": 1555307375
}

除基本的错误外，本指令额外可能返回如下错误：

错误代码 错误消息 错误原因
128 密码已设置 用户注册时的初始密码不为空

设备重启540 *

指令功能

如果设备实现了200指令中的reboot命令，那么应用可以使用本指令重启设备

请求示例

{
    "mid": "123456", 
    "from": "411549919082446848",
    "to": "system",
    "time": 1555307375, 
    "action": 540,
    "data": {
        "sn": "3960CT_1A45678910"
    }
}
请求参数 格式 必传 参数说明
sn 字符串 Y 设备sn

响应示例

{
    "mid": "123456",
    "from": "3960CT_1A45678910", 
    "to": "system", 
    "time": 1555307488,
    "action": 200, 
    "data": {
        "cmd": "reboot" 
    }
}
设备回复200指令后，即可开始重启设备。