第三方服务集成

单点登录集成

一、应用场景

物联云平台提供统一认证服务，用于集中式的身份管理。企业可以通过物联云平台进行一站式的登录认证。通过登录认证的用户即可直接访问第三方应用，而无需再次输入账号密码。

第三方应用需要将物联云平台作为身份认证的服务端，以物联云平台账号信息作为第三方应用登录时候的账号、密码。企业成员输入账号、密码后，由第三方应用的页面发起请求。物联云平台验证通过后，企业成员即可访问平台和各个应用。

企业通过物联云平台作为统一身份，建立各平台间的身份联系。企业内部应用使用物联云平台进行身份认证。

二、功能说明

物联云平台支持作为单点登录的服务端进行统一的身份认证。在使用物联云平台单点登录服务前，需要先获取物联云平台的AccessToken作为调用凭证、clien_id作为应用系统标识。

调用凭证（AccessToken）：需要前往物联云平台管理台【系统设置->平台访问授权】中，创建一个授权。记录已创建授权的AccessKeyId和AccessKeySecret，用于获取AccessToken。

应用系统标识（client_id）：需要前往物联云平台管理台【应用中心->应用网关】中，创建一个应用类型的应用，并开启单点登录。

企业成员通过第三方企业应用进行登录时，需要完成三步处理：获取临时授权码（Code）、获取单点登录调用凭证（SsoToken）、注册客户端。

获取临时授权码：企业应用提供登录页需要向应用服务端验证登录状态。在未登录状态下，由企业应用服务端通过物联云平台统一认证地址进行登录验证。物联云平台登录成功后则返回临时授权码（Code）。

获取单点登录调用凭证：应用服务端通过临时授权码（Code）、应用系统标识（client_id）、签名（Signature）换取单点登录调用凭证（SsoToken）。

注册客户端：通过单点登录调用凭证（SsoToken）、应用系统标识（client_id）进行注册客户端。

三、前提条件

1.第三方应用需要将物联云平台作为身份验证的服务端。 2.需要已创建的对应的AccessToken。 3.已创建应用类型的应用，并开启单点登录。 4.第三方应用开发登录页与物联云平台单点服务进行对接。 5.第三方登录页需要以物联云平台身份信息作为登录的账号、密码。 6.需要在物联云平台完成企业成员的创建。

四、关键流程

4.1 客户端对接示例流程

4.1.1 场景说明

以从物联网中台管理台跳转至外部系统管理台为例子，跳转之前物联网中台管理台需要知道外部系统管理台的地址。

4.1.2 场景前提

需要在物联网中台管理台的应用中心处创建应用用以代指 外部系统，并按照需要配置 外部系统管理台着陆页以及外部系统管理台注销回调页。

4.1.3 场景接口

外部系统需要实现以下功能接口:

单点登录客户端页面获取认证地址，让 外部系统管理台着陆页 得到 物联网中台认证页 的地址，此接口无固定要求，可缺省。
客户端注销单点登录，让 外部系统管理台 使用 外部系统 调用凭证进行单点登录客户端注销，此接口无固定要求，可缺省。
注销登录回调，此接口不可缺省，目的是让 物联网中台 通知 外部系统 在物联网中台已注销，格式见 5.2.1。
注销登录回调地址校验，此接口不可缺省，目的是让 物联网中台 校验 外部系统 的有效性，格式见 5.2.2。

4.1.4 流程说明

第一，在 物联网中台管理台 点击 外部系统管理台 期望进入外部系统管理台进行工作，点击后进入外部系统管理台着陆页，此页面需要实现后续功能。
第二，外部系统管理台着陆页 通过检测浏览器持有变量以确定访问者是否在 外部系统管理台 登录，如已在 外部系统管理台 登录，则可直接使用 外部系统管理台 而不用执行以下操作。
第三，外部系统管理台着陆页 检测到访问者未登录至 外部系统管理台，则向 外部系统服务端 发起请求用于获取外部系统在物联网中台的客户端标识clientId以及 物联网中台管理台认证页面，为固定html页面。
第四，外部系统管理台着陆页 向 物联网中台管理台认证页面 进行跳转，需要带上客户端标识clientId以及 回调地址callbackUrl，从而进入 物联网中台管理台认证页面。
第五， 物联网中台管理台认证页面 通过检测浏览器持有变量以确定访问者是否在 物联网中台管理台 登录，此时分两种情况：
- 未在 物联网中台管理台 登录跳转至 物联网中台管理台登录页，由访问者物联网中台的账号密码进行登录，从而得到物联网中台成员级调用凭证。
- 已在 物联网中台管理台 登录则可以直接得到物联网中台成员级调用凭证。
第六， 物联网中台管理台认证页面 在获取到 物联网中台成员级调用凭证 后向 物联网中台 发起获取单点登录临时授权码 请求以得到 临时授权码code 。
第七， 物联网中台管理台认证页面 将 临时授权码code和客户端标识clientId作为参数向外部系统回调地址callbackUrl 进行请求，此时进入 外部系统服务端 。
第八， 外部系统服务端 接收到 临时授权码code后，配合物联网中台的客户端标识clientId和客户端秘钥clientSecret向物联网中台发起 临时授权码换取单点登录调用凭证 请求，从而得到 单点登录调用凭证 。
第九， 外部系统服务端 得到 单点登录调用凭证 ，需要调用 依据单点登录调用凭证注册客户端，此操作目的在于访问者在物联网中台注销后由物联网中台通知 外部系统服务端 注销局部会话。
第十， 外部系统服务端 建立外部系统自身的会话信息，重定向至 外部系统管理台 导航页，进行正常功能访问。
第十一， 外部系统管理台 如需要得到访问者在 物联网中台 的基础信息则可发起 单点登录凭证换取基本信息 请求。
第十二， 外部系统管理台 如需要注销单点登录则可发起 单点登录调用凭证注销登录 ，从而使得 物联网中台 不在维护此客户端的单点登录信息。
第十三，访问者在 物联网中台管理台 注销登录，则物联网中台需要遍历此访问者注册上来的所有客户端，并找出客户端对应的 注销回调地址 进行注销通知，外部系统服务端 在接收到注销回调后销毁外部系统的会话标识，至此整个流程结束。

客户端对接示例流程

五、API列表

5.1 单点登录

5.1.1 获取单点登录临时授权码

接口描述

前提：第三方应用需要将物联平台当做账号的服务端，以物联平台账号作为登录第三方应用的账号密码；账号已在物联平台登录获得了物联平台的调用凭证，由单点登录服务自己页面发起请求

场景：访问第三方应用发现未登录跳转至物联平台统一页面，此时必须带有参数客户端标识clientId和回调地址redirectUrl

后续：单点登录服务页面在获取到code之后, 应该将code以参数形式添加在redirectUrl, 然后以get方式回调到客户端服务器

请求方式

POST

请求地址

/v3/service/sso/member/code

请求头

名称	必填	类型	备注
Access-Token	true	String	调用凭证企业成员
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
client_id	body	true	String	SSO应用系统标识

请求示例：

{
    "client_id":"456saffewf324235dsfsf"
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据
data.code	true	String	临时授权码

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": {
        "code": "4564dsfe1dsfsdf65446"
    }
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误
40435001	客户端不存在/未启用
40035002	客户端不是业务系统
40035003	客户端未启用sso

5.1.2 临时授权码换取单点登录调用凭证

接口描述

单点登录客户端根据临时授权码, 客户端标识, 签名换取单点登录的调用凭证

请求方式

POST

请求地址

/v3/service/sso/member/token

请求头

名称	必填	类型	备注
Signature	true	String	请求签名，签名方法为sha1(body + clientId + clientSecret)
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
code	body	true	String	临时授权码
grant_type	body	true	String	授权类型, 目前只支持authorization_code
timestamp	body	true	String	时间戳, 如果和服务器相差5分钟, 则认为非法
client_id	body	true	String	SSO应用系统标识

请求示例：

{
    "client_id":"456saffewf324235dsfsf",
    "code":"4564dsfe1dsfsdf65446",
    "grant_type":"authorization_code",
    "timestamp":"1635131391000"
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据
data.sso_token	true	String	单点登录调用凭证

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": {
        "sso_token": "45695661fdsfewdf2323"
    }
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误
40435001	客户端不存在/未启用
40035002	客户端不是业务系统
40035003	客户端未启用sso
40035006	时间戳不合法
40035007	授权类型不合法
40435002	临时授权码不存在
40035004	客户端标识不相等
40335001	签名不正确

5.1.3 依据单点登录调用凭证注册客户端

接口描述

单点登录客户端根据单点登录调用凭证注册客户端系统

请求方式

POST

请求地址

/v3/service/sso/member/register

请求头

名称	必填	类型	备注
Sso-Token	true	String	单点登录调用凭证
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
client_id	body	true	String	SSO应用系统标识

请求示例：

{
    "client_id":"456saffewf324235dsfsf"
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": {}
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误
40435001	客户端不存在/未启用
40035002	客户端不是业务系统
40035003	客户端未启用sso
40335002	调用凭证已过期
40335003	调用凭证被刷新

5.1.4 成员注销登录

接口描述

企业成员调用凭证注销登录，销毁调用凭证以及刷新凭证，并以消息队列将注销登录事件发送通知给SSO服务进而通知给各个单点登录客户端，该接口由Api-Service和Corp-Service提供

请求方式

PUT

请求地址

/v2/corp/member-logout

请求头

名称	必填	类型	备注
Access-Token	true	String	调用凭证企业成员
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
无	无	无	无	无

请求示例：

{
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": null
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误

5.1.5 单点登录调用凭证注销登录

接口描述

单点登录客户端使用单点调用凭证注销单点登录，主要来源与客户端发起，发起该请求之后会根据单点登录调用凭证的MemberId和Resource找出所有注册的客户端，异步通知各个客户端注销局部会话.

请求方式

PUT

请求地址

/v3/service/sso/member/client-logout

请求头

名称	必填	类型	备注
Sso-Token	true	String	单点登录调用凭证
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
无	无	无	无	无

请求示例：

{
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": null
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误
40335002	调用凭证已过期
40335003	调用凭证被刷新

5.1.6 单点登录调用凭证换取基本信息

接口描述

单点登录客户端使用单点调用凭证单点调用凭证获取成员基本信息.

请求方式

GET

请求地址

/v3/service/sso/member/infos

请求头

名称	必填	类型	备注
Sso-Token	true	String	单点登录调用凭证
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
无	无	无	无	无

请求示例：

{
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据
data.id	true	String	成员标识
data.name	true	String	成员名称
data.email	false	String	成员邮箱
data.phone	false	String	成员手机号

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": {
        "id":"123sdfwe123sdfe",
        "name":"李四",
        "email":"liqinghua@xlink.cn",
        "phone":"13838383388"
    }
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误
40335002	调用凭证已过期
40335003	调用凭证被刷新

5.2 外部系统实现接口标准

5.2.1 注销登录回调

接口描述

成员在物联网中台管理台或者某个客户端向物联网中台发起注销客户端时，物联网中台会找出该成员下所有注册的客户端，向对应客户端注销回调地址发起请求，进行注销登录通知。

客户端注销回调地址需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200。

请求方式

POST

请求地址

http://xxxx/xxx/xxx/xxx

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
client_id	body	true	String	SSO应用系统标识
sso_token	body	true	String	SSO调用凭证

请求示例：

{
    "sso_token": "单点登录调用凭证",
    "client_id": "客户端标识, 即是应用标识"
}

返回参数说明

名称	必填	类型	备注
status	true	Int	HTTP状态码
code	true	Int	业务错误码
msg	false	String	业务错误信息
data	true	Object	业务数据

返回示例：

{
    "status": 200,
    "code": 200,
    "msg": "访问成功",
    "data": {}
}

错误码：

错误码	描述
----	----

5.2.2 注销登录回调地址校验

接口描述

成员在物联网中台管理台应用中心处创建单点登录的应用时，需要填写单点登录的客户端注销回调接口地址，物联网中台会校验该客户端注销回调接口的有效性。

注销登录回调地址校验需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且响应值echo_string需要与请求参数echo_string一致。

请求方式

GET

请求地址

http://xxxx/xxx/xxx/xxx?timestamp={timestamp}&nonce={nonce}&echo_string={echo_string}&signature={signature}&app_id={app_id}

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
signature	Query	true	String	加密签名，签名方法 1.将timestamp、nonce、app_id、app_secret四个参数进行字典序排序 2. 将四个参数字符串拼接成一个字符串进行sha1加密, 得到 signature
timestamp	Query	true	String	时间戳
nonce	Query	true	String	随机数
echo_string	Query	true	String	随机字符串
app_id	Query	true	String	应用标识, 用于找出对应的app_secret

请求示例：

{
}

返回参数说明

名称	必填	类型	备注
echo_string	true	String	随机字符串

返回示例：

{
   "echo_string":"随机字符串"
}

错误码：

错误码	描述
----	----

用户第三方认证接口

一、应用场景

第三方平台用户指代非物联云平台自主注册的C端App用户。物联云平台支持第三方平台用户直接跳转至平台中，而无需再次进行注册账号、输入账号密码进行登录等操作。

第三方平台分为主流第三方平台（微信、QQ、微博、支付宝、Facebook、Twitter）及通过物联云平台认证的第三方平台。非主流第三方平台需要根据物联云平台接口规范进行实现，并将已实现的接口URL地址配置在免登陆验证中。用户在第三方平台登录成功后，通过open_id、access_token在物联云平台请求登录。

用户在第三方平台登录后，可无感切换至物联云平台中继续进行操作。用于第三方平台维护平台间统一的用户身份体系。

二、功能说明

客户可以在物联网平台的管理台【应用中心->集成->免验证登录】中，依据第三方平台认证接口规范进行实现。在免登陆验证中配置已实现的接口URL地址和token信息。依据第三方平台用户登录接口发送请求。

第三方平台用户首次登入，物联云平台会自动为其创建用户信息。并绑定第三方平台的open_id。物联云平台支持用户解绑第三方平台的open_id。

第三方平台用户登入后，物联云平台自动初始化其登录密码，每个第三方用户只能初始化一次密码。后续按照忘记密码流程进行处理。

三、前提条件

1.依据物联云平台接口规范实现，并将接口URL地址和token配置在免登陆验证中。 2.第三方平台需要完成和物联云平台的用户登录对接。 3.目前仅支持微信用户、QQ用户、微博用户、支付宝用户、Twitter用户、Facebook用户。

四、关键流程

4.1 用户第三方认证

流程说明：

首先，管理员级B端成员 登录到 企业管理台 得到物联网中台成员级调用凭证和刷新凭证。
其次，管理员级B端成员 获得到物联云平台第三方平台的用户认证地址和用户认证凭证，向 物联网中台 发起 设置用户第三方认证配置 请求，进行认证校验配置。
再次，管理员级B端成员 向 物联网中台 发起 查询用户第三方认证配置 请求，得到用户第三方认证的配置确认是否配置正确。
接着，第三方C端用户 登录到 物联云平台标准第三方平台，获得第三方平台调用凭证以及第三方标识。
接着，第三方C端用户 依据第三方平台调用凭证以及第三方标识向物联网中台发起 第三方用户认证登录 请求。
最后，物联网中台接收到 第三方用户认证登录 请求后查找出对应的第三方平台校验地址和校验凭证，向物联云平台第三方平台发起 第三方调用凭证和第三方标识校验 请求，校验通过后为第三方C端用户颁发用户级调用凭证以及刷新凭证。

用户第三方认证流程

五、API列表

5.1 第三方认证设置

5.1.1 设置用户第三方认证配置

接口描述

当企业希望启用第三方认证登录时，需要登录到物联网企业管理台处设置第三方认证的认证回调地址，此接口正是用于配置每个企业的用户第三方认证的回调地址以及凭证。

请求方式

POST

请求地址

/v2/corp_setting

请求头

名称	必填	类型	备注
Access-Token	true	String	调用凭证企业成员
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
user_auth_third	body	true	Object	用户第三方认证配置
user_auth_third.url	body	true	String	用户第三方认证地址
user_auth_third.token	body	true	String	用户第三方认证凭证

请求示例：

{
    "user_auth_third": {
        "url": "http://www.xlink.cn",
        "token": "456125145"
    }
}

返回参数说明

名称	必填	类型	备注
user_auth_third	true	Object	用户第三方认证配置
user_auth_third.url	true	String	用户第三方认证地址
user_auth_third.token	false	String	用户第三方认证地址

返回示例：

{
    "user_auth_third": {
        "url": "http://www.xlink.cn",
        "token": "456125145"
    }
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误

5.1.2 查询用户第三方认证配置

接口描述

查询企业下用户第三方认证配置信息。

请求方式

GET

请求地址

/v2/corp_setting

请求头

名称	必填	类型	备注
Access-Token	true	String	调用凭证企业成员
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
----	----	----	----	----

请求示例：

{
}

返回参数说明

名称	必填	类型	备注
user_auth_third	true	Object	用户第三方认证配置
user_auth_third.url	true	String	用户第三方认证地址
user_auth_third.token	false	String	用户第三方认证地址

返回示例：

{
    "user_auth_third": {
        "url": "http://www.xlink.cn",
        "token": "456125145"
    }
}

错误码：

错误码	描述
40010001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误

5.2 第三方认证登录

5.1.2 第三方用户认证登录

接口描述

用户在通过了第三方平台登录成功后，通过第三方openId、accessToken在物联云平台请求登录，如果第三方用户不在物联云平台则直接创建一个用户，如果已在物联云平台则更新相关信息．

请求方式

POST

请求地址

/v2/user_auth_third

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
source	body	true	Int	用户第三方源 10: 其他
plugin_id	body	false	String	应用标识
open_id	body	true	String	第三方用户标识
corp_id	body	true	String	企业标识
access_token	body	true	String	第三方调用凭证
name	body	false	String	用户名称
resource	body	false	String	用户登录源

请求示例：

json

{
    "source": 4,
    "corp_id": "1235aed1f1df222",
    "open_id":"156s1fe6d123fef15d1d2",
    "access_token":"1112sdfwefdsfafd212",
    "name":"李清华",
    "resource":"TEST",
    "plugin_id":"131566efdfaew23"
}

返回参数说明

名称	必填	类型	备注
user_id	true	String	用户标识
access_token	true	String	调用凭证
refresh_token	true	String	刷新凭证
expire_in	true	Int	调用凭证的有效期
authorize	true	String	用户认证码

返回示例：

json

{
    "user_id":112356456,
    "access_token":"dsfs16we1d1fd23afew5fdf",
    "refresh_token":"1561ewfd1s2fwe5fffdfdsfsdf",
    "expire_in":7200,
    "authorize":"dsfe1561d56fds1fe"
}

错误码：

错误码	描述
4001001	请求数据字段验证不通过
4001002	请求数据必须字段不可为空
4031001	调用凭证权限被禁止访问
4031003	无效的调用凭证
4031002	需要调用凭证
4041001	接口不存在
5031001	系统错误
4031024	权限不足
4001482	第三方源未知
4041020	应用不存在
4041023	未设置第三方登录地址
4001059	第三方验证失败

5.3 外部系统实现接口标准

5.3.1 第三方调用凭证和第三方标识校验

接口描述

物联网中台企业设置了用户第三方认证配置后发起用户第三方认证登录，此时物联网中台会向外部系统发起第三方调用凭证和第三方标识校验 请求，用于确认第三方凭证和第三方标识的有效性。

第三方调用凭证和第三方标识校验: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。

请求方式

GET

请求地址

http://xxxx/xxx/xxx/xxx?access_token=xxxx?open_id=xxxx?timestamp=xxxx?sign=xxxx

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
access_token	body	true	String	第三方认证登录时传输到物联平台的access_token
open_id	body	true	String	第三方认证登录时传输到物联平台的open_id
timestamp	body	true	Long	物联平台生成的时间戳
sign	body	true	String	请求签名 1.签名算法:MD5(open_id+access_token+timestamp+sign_token) 2.sign_token为5.1.1 设置成员第三方认证配置中的token 3.外部系统接收到请求后，使用同样的签名方法得到签名与请求签名参数相比较以确认请求是否有效合法

请求示例：

{
}

返回参数说明

名称	必填	类型	备注
open_id	false	String	第三方用户标识
nickname	false	String	昵称
sex	false	Int	性别 1：男 2：女 -1：未知
country	false	String	所在国家
province	false	String	所在省份
city	false	String	所在城市
phone	false	String	手机号码
email	false	String	邮箱地址

返回示例：

{
    "open_id": "4541465ewfds23f1ds",
    "nickname": "lily",
    "sex": 2,
    "country": "中国",
    "province": "广东",
    "city": "广州",
    "phone": "13838383388",
    "email": "liqinghua@xlink.cn"
}

错误码：

错误码	描述
----	----

六、物联云平台标准第三方平台

6.1 物联云平台标准第三方成员平台

第三方平台实现了 5.3.1 第三方调用凭证和第三方标识校验 标准的接口。
第三方平台将实现了 5.3.1 第三方调用凭证和第三方标识校验 标准的接口使用 5.1.1 设置用户第三方认证配置 配置在物联网中台。
至此，可以称第三方平台为 物联云平台标准第三方成员平台

工单集成

一、应用场景

1.应用于工单转发记录的查看
2.应用于设备异常转发工单时的模板配置
3.应用于第三方工单系统的对接

二、功能说明

可实现设备出现异常后，将异常信息转发至第三方的工单系统中，并在工单系统完成后，将对应的状态信息回写至平台的对应工单记录中

三、前提条件

1.在平台完成工单系统的配置
2.在平台完成工单模板的配置
3.在第三方工单系统中完成回调信息的配置

四、关键流程

4.1.发起工单

4.2.查询工单

五、API列表

5.1. 工单创建

接口描述

创建工单

请求方式

POST

请求地址

/v3/workorder/system/server/ticket/create

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
template_id	body	是	String	发送内容模板
content	body	否	String	自定义工单内容(带通配符)
user_id	body	否	String	操作员工
event_id	body	否	String	绑定事件id（事件id与设备id二选一）
device_id	body	是	Integer	触发设备id（事件id与设备id二选一）
event_type	body	是	Integer	@1：人工 @2：自动
title	body	否	String	自定义标题
contacts_name	body	否	String	联系人
contacts_phone	body	否	String	联系人电话
scene_id	body	否	String	场景id
log_id	body	否	String	场景日志id
photos	body	否	Array	图片集（图片传输方式三选一）
photos.value	body	否	byte[]	图片流
photos.url	body	否	String	图片下载url
photos.file_id	body	否	String	物联云平台文件系统文件id

请求示例：

json

{
    "template_id": "发送内容模板",
    "content": "xxxxxxxxxxxxxxxx",
    "user_id": "操作员工",
    "event_id": "事件id",
    "event_type": 1,
    "photos":[
        {
            "url" : "www.google.com/xxx.png"
        },
        {
            "file_id" : "xxxxxxxxx"
        }
    ]
}

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Object	业务响应数据
data.flow_id	是	String	工单流水号
data.is_success	是	int	是否创建成功@1：成功；@2：失败
data.msg	否	String	退款错误消息

返回示例：

json

{
    "code" : "000000",
    "status" : "200",
    "msg" : "请求成功",
    "data" : {
        "flow_id": "工单流水号",
        "is_success": 1,
        "msg": "失败原因"
    }
}

错误码：

错误码	描述
000000	请求成功
4001005	参数不能为空
4001102	获取企业信息失败
5031001	服务端发生异常
4001103	没有该第三方用户
40001104	第三方配置已停用

5.2. 单个工单查询

接口描述

查询工单接口

请求方式

GET

请求地址

/v3/workorder/system/server/ticket/check/

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
id	path	true	String	工单id

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Object	业务响应数据
data.flow_id	是	String	第三方工单流水号
data.project_id	是	String	项目id
data.corp_id	是	String	企业id
data.event_id	是	String	事件id
data.third_name	是	String	第三方系统名称
data.event_type	是	String	来源（事件类型，@1：人工 @2：自动）
data.urgent	否	Integer	紧急程度
data.content	是	String	内容
data.third_msg	否	String	第三方返回内容
data.deal_user	否	String	处理人
data.deal_time	否	date	处理时间
data.deal_remark	否	String	处理备注
data.deal_pic_url	否	String	处理图片
data.create_ticket_time	否	date	转发时间
data.stauts	是	int	状态码@1：待处理；@2：处理中；@3：已处理；@4：失败；@5：撤销/取消；@9：错误工单
data.created_time	是	date	创建时间
data.updated_time	否	date	更新时间
data.accept_time	否	date	接收工单时间
data.finish_time	否	date	完成工单时间

返回示例：

json

{
    "responseTime": "2021-10-14T15:40:39.620Z",
    "code": "000000",
    "status": "200",
    "msg": "请求成功",
    "data": {
        "id": "X488785707981078528",
        "status": 1,
        "application": "VideoSecurity",
        "corp_id": "100010b9c424fa00",
        "created_date": "2021-09-10T18:59:53.982Z",
        "create_man": "1206c0c06968e800",
        "updated_date": "2021-09-10T18:59:54.25Z",
        "update_man": "1206c0c06968e800",
        "deleted": false,
        "third_id": "tc488296482240200704",
        "third_name": "物联云平台工单系统",
        "ticket_id": "tc488297794138800128",
        "template_id": "tpc488723393596620800",
        "flow_id": "yzy488785707721031680",
        "event_id": "3b613b3a96b991e5411c6fd0f5",
        "event_type": 1,
        "address": "广东省广州市海珠区琶洲街道都比教育M+Studio创工场",
        "content": "设备名称：公司大门\n事件触发条件：人为抓图-实时监控\n空间位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n详细位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n预警对象姓名：",
        "third_msg": "发起工单成功",
        "create_ticket_time": "2021-09-10T18:59:53.982Z"
    }
}

错误码：

错误码	描述
000000	请求成功

5.3. 查询工单列表

接口描述

查询工单列表

请求方式

POST

请求地址

/v3/workorder/system/server/ticket/list

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限/外部权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
filter	body	false	Array	过滤字段
limit	body	true	Integer	每页数量
offset	body	true	Integer	返回数据指针
order	body	false	Map	排序
query	body	false	Map	查询条件：支持name；id等字段

请求示例：

json

{
    "order":{
        "create_ticket_time":"desc"
    },
    "limit":10,
    "offset":0
}

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Array	业务响应数据
data.id	是	String	工单id
data.flow_id	否	String	第三方工单id（未受理则为空）
data.event_id	否	String	事件id
data.event_type	否	Integer	事件来源（@1：手动；@2：自动）
data.address	否	String	地址
data.device_id	否	String	设备
data.third_name	是	String	第三方系统名称
data.content	是	String	内容
data.deal_user	否	String	处理人
data.deal_pic_url	否	String	处理图片
data.deal_time	否	date	处理时间
data.deal_remark	否	String	处理备注
data.create_ticket_time	否	date	转发时间
data.stauts	是	int	状态码@1：待处理；@2：处理中；@3：已处理；@4：失败；@5：撤销/取消；@9：错误工单

返回示例：

json

{
    "responseTime": "2021-10-14T15:39:12.275Z",
    "code": "000000",
    "status": "200",
    "msg": "请求成功",
    "data": {
        "list": [
            {
                "id": "X488785707981078528",
                "status": 1,
                "application": "VideoSecurity",
                "corp_id": "100010b9c424fa00",
                "created_date": "2021-09-10T18:59:53.982Z",
                "create_man": "1206c0c06968e800",
                "updated_date": "2021-09-10T18:59:54.25Z",
                "update_man": "1206c0c06968e800",
                "deleted": false,
                "third_id": "tc488296482240200704",
                "third_name": "物联云平台工单系统",
                "ticket_id": "tc488297794138800128",
                "template_id": "tpc488723393596620800",
                "flow_id": "yzy488785707721031680",
                "event_id": "3b613b3a96b991e5411c6fd0f5",
                "event_type": 1,
                "address": "广东省广州市海珠区琶洲街道都比教育M+Studio创工场",
                "device_id": null,
                "content": "设备名称：公司大门\n事件触发条件：人为抓图-实时监控\n空间位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n详细位置：广东省广州市海珠区琶洲街道都比教育M+Studio创工场\n预警对象姓名：",
                "third_msg": "发起工单成功",
                "create_ticket_time": "2021-09-10T18:59:53.982Z"
            }
        ],
        "count": 386,
        "current_page": null,
        "per_page": null
    }
}

错误码：

错误码	描述
000000	请求成功

5.4. 工单状态回调

接口描述

第三方工单处理完成回调接口

请求方式

POST

请求地址

/v3/workorder/system/server/third/callback/

请求头

名称	必填	类型	备注
Access-Token	true	String	企业权限
Content-Type	true	String	application/json

请求参数

名称	位置	必填	类型	备注
type	path	是	String	@招商：UBMS；@微钉：WEIDING；@四格：SIGE；@佳兆业：JZY
is_success	body	是	Integer	是否成功（@1：成功，@0：失败）
third_project_id	body	是	String	第三方项目id
ticket_code	body	是	String	第三方工单编码
ticket_status	body	是	String	工单状态
ticket_deal_user	body	否	String	处理人第三方id
ticket_finish_time	body	否	Date	处理完成时间
ticket_remark	body	否	String	处理备注

请求示例：

json

{
    "is_success": "1",
    "third_project_id": "111111",
    "ticket_code": "1111",
    "ticket_status": "has_finish",
    .........
}

返回参数说明

名称	必填	类型	备注
status	是	int	HTTP状态码
code	否	int	业务错误码
msg	否	String	业务错误信息
data	否	Object	业务响应数据
data.is_success	是	Integer	是否处理成功（@1：成功；@2：失败）
data.ticket_code	是	String	第三方工单编码

返回示例：

json

{
    "code" : "000000",
    "status" : "200",
    "msg" : "请求成功",
    "data" : {
        "is_success": 1,
        "ticket_code": "11111"
    }
}

错误码：

错误码	描述
000000	请求成功
400	请求字段不合法
4002003	没有对应的工单

主数据同步（主数据拉取数据）

一、应用场景

主数据集成是指物联云平台和第三方平台中的基础数据同步。物联云平台主要包含5大类基础数据，分别为组织、企业成员、业主、项目、空间。其中空间数据下细分为5类数据，包含区域、楼栋、单元、楼层、房屋。

保障第三方平台和物联云平台的数据一致性。

二、功能说明

物联云平台提供主动拉取数据的方式进行主数据的同步。需要企业按照规范提供接口进行数据同步。数据同步方式包含全量同步和增量同步，仅在查询到该类型数据不存在成功状态的同步记录时才会进行。当该类型数据已存在成功状态的同步记录时，会进行增量数据的同步，增量数据同步包含新增、更新、删除。删除操作需要通过指定字段（is_delete）进行标识。

三、前提条件

3.1、全量同步：

程序启动或者定时任务触发增量同步时，如果查询对应的租户与数据类型没有成功状态的同步记录，进行全量同步：分页拉取租户对应的主数据全量数据进行同步。

3.2、增量同步（包括新增，更新，删除）：

通过每个租户拟定的同步规则（详情请见同框下文）创建不同规则的定时任务线程进行数据的增量同步：通过分页拉取租户同步记录空缺时间时间段的数据进行同步。

3.3、同步规则

1、第三方主数据的删除操作都需要有删除识别，通过is_deleted字段标识，并且能通过第三方主数据提供的查询数据接口体现出来。 2、begin_time～end_time 能够查询该时间段内创建/更新/删除的数据。 3、begin_time , end_time 都是针对 update_time 字段进行筛选。 4、租户同步规则：请提供对应的同步规则包括：数据类型、同步时间时间段、同步时间间隔（如：项目类型数据、每天00：00：00到23：00：00、60分钟）。 5、数据全量同步请按照以下顺序进行同步（如果无对应类型，忽略即可）：组织→项目→区域→楼栋→单元→楼层→房屋→住户；组织→项目→员工 6、数据删除同步请按照以下顺序同步（如果无对应类型忽略即可）：住户→房屋→楼层→单元→楼栋→区域→项目→组织；员工→ 项目→组织

四、关键流程

4.1、主数据同步流程（拉取数据）

五、数据提供方接口规范

5.1 数据获取接口规范

各企业定义按该接口规范进行接口开发：

接口URI

请自定义

接口调用Method POST 请求头

名称	必填	类型	备注
Content-Type	True	String	application/json; charset=utf-8
corp_id	True	String	企业ID
timestamp	True	Long	时间戳，精确到秒，10分钟内数据有效
nonce	True	String	流水号nonce（防止重复提交），至少为10位
signature	True	String	请求签名MD5(corp_id（企业ID）timestamp（时间戳） nonce（随机字符串） appSecret（加密秘钥，创建规则时填写）) （直接字段串拼接，无分隔符），用于数据提供方进行安全校验

请求参数

名称	必填	类型	备注
project_id	False	String	项目id(同步项目时不需要传)
data_type	True	String	同步数据类型（请看6.1、数据类型）
begin_time	False	Long	开始时间点，（时间戳：毫秒）（如不传此参数则返回到end_time字段的所有数据，两者都不传则返回全量数据）
end_time	False	Long	结束时间点，（时间戳：毫秒）（如不传此参数则返回begin_time到现在的所有数据，两者都不传则返回全量数据）
page_no	False	Int	当前页，不传默认1
page_size	False	Int	页面大小，不传默认100

请求示例：

java

{
    "project_id": "xxxxx",
    "data_type": "building",
    "begin_time": 6271823901,
    "end_time": 6782138991,
    "page_no": 1,
    "page_size": 100
}

返回参数说明

名称	必填	类型	备注
status	True	Int	HTTP状态码（400、401、403、404、500、503）
code	True	Int	业务错误码，由数据提供方自定义
msg	True	String	业务错误信息，由数据提供方自定义
data	True	Object	业务响应数据
data.count	False	Int	数据总数
data.list	False	Array	数据列表
data.list.<T>	False	Object	具体数据（根据请求的不同数据类型，参考具体数据模型。请看5.2、数据说明）

返回示例：

java

{
  "status": "HTTP状态码",
  "code": "业务错误码",
  "msg": "业务错误信息",
  "data": {
    "count": "总数",
    "list": [<T>]
  }
}

5.2 字段说明

5.2.1 组织数据

字段名称	类型	描述	备注	是否必填
id	String	标识	组织ID	是
parent_id	String	父级标识		否
name	String	名称		是
remark	String	描述		否
type	Integer	组织分类	0:内部行政组织；1:内部行政组织；2:应用帐号组织;3:职能帐号组织;4:外部帐号组织;5:公共通讯录组织;6:业务组织，默认为6	否
sub_type	Integer	组织性质	1:公司;2:分公司;3:子公司;4:片区公司;5:服务中心;6:部门，默认为1	否
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源	由数据同步方填写	是

java

{
    "id":"组织ID",
    "parent_id":"父级标识",
    "name": "名称",
    "remark": "描述",
    "type":6,
    "sub_type":1,
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源"
}

5.2.2 项目数据

字段名称	类型	描述	备注	是否必填
id	String	标识	项目ID	是
name	String	名称		是
type	Int	项目类型	默认为 2 ：智慧社区（请参考：3.2.1 项目类型）	是
organization_id	String	业务组织id	第三方组织ID	是
province	String	省份	格式如："广东省"	是
city	String	城市	格式如:"广州市"	是
county	String	县/区	无特殊格式要求	否
address	String	项目的详细地址		否
remark	String	项目备注		否
layout	String	项目平面图的url		否
coordinate	Array	项目经纬度数组	double数组, coordinate[0]是经度,coordinate[1]是纬度	否
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源	由数据同步方填写	是

java

{
    "id":"项目ID",
    "name": "项目名称",
    "type": 1,
    "organization_id":"项目的上层组织ID",
    "province": "省份",
    "city": "城市名",
    "county": "国家",
    "address": "详细地址",
    "remark": "备注",
    "layout": "项目平面图的url",
    "coordinate": [130.012,66.37],
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.3 区域数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
parent_id	String	父级区域标识		否
index	Int	在同级中的排序	空间服务的业务属性 (如果没有,主数据是否自动生成)	否
remark	String	备注		否
address	String	详细地址		否
coordinate	Array	经纬度数组	double数组	否
name	String	名称		是
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源		是

java

{
    "id":"区域ID",
    "project_id":"所属项目标识",
    "parent_id":"父级区域标识",
    "index": 1,
    "remark": "备注",
    "address": "详细地址",
    "coordinate": [130.012,66.37],
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.4 公区数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
parent_id	String	父级空间标识		否
index	Int	在同级中的排序	空间服务的业务属性 (如果没有,主数据是否自动生成)	否
remark	String	备注		否
address	String	详细地址		否
coordinate	Array	经纬度数组	double数组	否
name	String	名称		是
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源		是

java

{
    "id":"公区ID",
    "project_id":"所属项目标识",
    "parent_id":"父级空间标识",
    "index": 1,
    "remark": "备注",
    "address": "详细地址",
    "coordinate": [130.012,66.37],
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.5 楼栋数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
parent_id	String	所属父级标识		是
name	String	名称		是
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源		是

java

{
    "id":"楼栋ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.6 单元数据

字段名称	类型	描述	备注	是否必填
id	String	单元标识		是
project_id	String	所属项目标识		是
parent_id	String	所属父级标识		是
name	String	名称		是
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源	由数据同步方填写	是

java

{
    "id":"单元ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.7 楼层数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
parent_id	String	所属父级标识		是
name	String	名称		是
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源	由数据同步方填写	是

java

{
    "id":"楼层ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.8 房屋数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
parent_id	String	所属父级标识		是
name	String	名称		是
type	Int	房屋类型	1：家庭房屋，2：设备房3，公寓。对应的类型是家庭类型的房屋，会创建对应的home来供app用户使用。	是
sub_type	Int	房屋子类型	完全由用户自定义的类型，不做限制	否
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源		是

java

{
    "id":"房屋ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "type": 1,
    "sub_type": 1,
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.9 住户数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
name	String	名称		是
certificate_type	Int	证件类型	1：身份证，2：护照，3：军官证，4：港澳通行证	是
certificate_id	String	证件号		是
phone	String	手机号		是
gender	Int	性别	0：未知，1：男性，2：女性	是
birthday	String	生日		否
register_time	Long	注册时间	时间戳，毫秒数	是
houses	Array	房产列表		是
houses.house_id	String	房屋标识		否
houses.role	Int	房屋下的角色		否
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源	由数据同步方填写	是

java

{
    "id":"住户ID",
    "project_id":"所属项目标识",
    "name": "名称",
    "certificate_type": 1,
    "certificate_id": "证件号",
    "phone": "手机号",
    "gender": 0,
    "birthday": "出生时间",
    "register_time": 1595385751001,
    "houses": [{
        "house_id":"房屋ID",
        "role":1
    }],
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源"
}

5.2.10 员工数据

字段名称	类型	描述	备注	是否必填
id	String	标识		是
project_id	String	所属项目标识		是
name	String	名称		是
email	String	邮箱		是
phone	String	手机		是
certificate_id	String	证件号		是
phone	String	手机号		是
is_delete	Boolean	是否已删除	true:已删除，false:没有删除	是
create_time	Long	创建时间	时间戳，毫秒数	是
update_time	Long	更新时间	时间戳，毫秒数	是
data_source	String	数据来源	由数据同步方填写	是

java

{
    "id":"员工ID",
    "project_id":"所属项目标识",
    "name": "名称",
    "phone": "手机号",
    "email": "邮箱",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源"
}

六、枚举详情

6.1、数据类型

数据类别	具体数据	data_type	数据类型
空间	项目	project	String
空间	楼栋	building	String
空间	区域	area	String
空间	单元	unit	String
空间	楼层	floor	String
空间	房屋	house	String
业主	业主	customer	String
组织	组织	organization	String
员工	员工	employee	String

6.2、项目类型

枚举值	说明	数据类型
1	长租公寓	Int
2	智慧社区	Int
3	智慧家庭	Int
4	智慧路灯	Int
5	资产管理	Int
6	综合体	Int
7	标准类型	Int
8	联合办公	Int

6.3、同步操作类型

operation_type	说明	数据类型
update	修改（删除必须是逻辑删除，归类为修改类型）	String
add	新增	String

6.4、房产角色类型

枚举值	说明	数据类型
0	未知	Int
1	业主	Int
2	亲属	Int
3	租客	Int
99	安装工	Int

6.5、房屋类型

枚举值	说明	数据类型
1	家庭房屋	Int
2	设备房（废弃）	Int
3	公寓	Int

6.6、证件类型

枚举值	说明	数据类型
1	身份证	Int
2	护照	Int
3	军官证	Int
4	港澳通行证	Int

6.7、性别类型

枚举值	说明	数据类型
0	未知	Int
1	男性	Int
2	女性	Int

第三方短信集成

一、应用场景

短信集成服务是物联网平台提供的用于客户自定义短信发送通道的功能。客户可以使用短信集成服务实现将物联网平台需要发送短信的业务通过客户指定的第三方短信平台进行发送。可用于以下业务场景：

客户已有自建的统一的短信系统，需要将物联网平台的短信通过客户自建的短信系统发送；
客户希望根据不同用户地区、用户短信类型采用不同的短信发送提供商的短信发送服务；

二、功能说明

客户在物联网平台管理台【应用中心->集成->短信服务->短信配置】中开启第三方短信平台功能，并填写URL与Token。其中URL是用来接收物联网平台发送的短信数据接口，URL必须为HTTPS接口；Token用作验证URL有效性。在物联云平台产生一条短信后，将使用第三方厂商平台发送短信，物联云平台会将短信 POST到第三方厂商短信平台，最终由第三方厂商平台将短信发出。

短信主要包含以下几种：
用户注册验证码用户忘记密码用户更新手机号码用户短信登录

三、前提条件

参考管理台操作手册《应用中台操作手册》，在管理台【应用中心->集成->短信服务->短信配置】中选择使用第三方厂商短信；
在管理台正确配置第三方邮箱URL、Token；
第三方平台在配置的URL上实现验证接口和接收短信内容的接口；
点击【验证】按钮进行第三方优先系统对接验证，验证完成后点击【保存】按钮；

四、关键流程

4.1. 第三方短信系统对接流程

流程说明： 成员在管理台进行短信配置，填写第三方短信系统URL和Token，进行验证和保存。验证通过后，物联网平台的短信将发送到配置的第三方短信系统进行发送。

短信配置验证

4.2 短信发送流程

流程说明： 短信发送者根据不同场景向物联网中台发起 发送短信 请求，物联网中台收到请求后根据请求信息找出企业下设置第三方短信系统的地址以及调用凭证，利用短信系统地址和调用凭证向第三方短信系统发送短信。

短信发送流程

五、API列表

5.1 验证URL有效性

接口描述

在物联网平台配置完URL和Token后，物联网平台会通过配置的URL和Token向第三方厂商发起验证。

验证URL有效性: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。

请求方式

GET

请求地址

由用户在物联网平台管理台配置的URL

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	参数位置	必填	类型	备注
timestamp	query	true	string	时间戳
signature	query	true	string	物联网平台加密签名； 1.签名算法：signature=SHA1(corpId + Token + timestamp)， 2.corpId是企业在物联网平台的企业ID 3.Token由客户在物联网平台管理台填写

验证方法说明：第三方短信系统通过检验signature对GET请求验证，若自身通过签名算法【SHA1(corpId + Token + timestamp) 】加密得到的数据与请求的signature一致，则返回HTTP状态码 200 OK设置有效，否则设置无效，返回错误消息，统一按照返回消息格式响应。

请求示例：

GET http://tac.com/sms/iot?tumestamp=14342587903&signature=37975ef199e20f8b04fbdba750547e42b2e604f3

返回参数说明

校验成功返回http 状态码 200。

返回示例：

http status code ：200

错误返回参数说明

名称	必填	类型	备注
err_code	是	Integer	错误码
err_msg	是	String	错误信息

错误返回示例：

{
    "err_code":"4031003",
    "err_msg":"Token验证失败"
}

错误码：

错误码	描述
4031003	不合法的调用凭证
4041010	企业ID不合法

5.2 发送短信

接口描述

物联网根据短信模板生成短信，若管理台短信配置为【使用第三方厂商短信】，则将内容POST到管理台填写的URL中，内容为请求Body，第三方厂商负责将短信发出。此接口定义物联网平台发出短信格式；

发送短信: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。

请求方式

POST

请求地址

由用户在物联网平台管理台配置的URL

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	参数位置	必填	类型	备注
to	body	true	String	接收者手机号码，多个号码以英文逗号分隔，如： 17011223344,17022334455
sms_param	body	true	Object	短信参数
sms_param.type	body	true	enum	短信参数类型，参考5.3.1 短信参数类型说明
sms_param.code	body	true	String	验证码
sms_param.minute	body	true	String	验证码有效期, 单位分钟
area_code	body	false	String	接收短信的手机区号
plain_sms	body	false	String	短信原文
plugin_id	body	false	String	短信关联的物理网中台应用网关标识第三方系统可以根据此参数去确定不同的短信签名等

验证方法说明：第三方短信系统通过检验signature对GET请求验证，若自身通过签名算法【SHA1(corp_id + Token + timestamp) 】加密得到的数据与请求的signature一致，则返回HTTP状态码 200 OK设置有效，否则设置无效，返回错误消息，统一按照返回消息格式响应。

请求示例：

json

{
    "area_code": "+86",
    "to": "13838383388",
    "plain_sms": "注册验证码为 85626",
    "plugin_id": "5632265wfdsafdsf",
    "sms_param": {
        "type": 1,
        "code": "85626",
        "minute": 5
    }
}

返回参数说明

名称	必填	类型	备注
err_code	是	Integer	错误码
err_msg	是	String	错误信息

返回示例：

{
    "err_code":"4031003",
    "err_msg":"Token验证失败"
}

错误码：

错误码	描述
0	发送成功
4031003	不合法的调用凭证
4041010	企业ID不合法
4002001	短信内容不合法
4002002	短信接收号码不合法
4002003	国家码不合法

5.3 附录一：短信参数说明

5.3.1 短信参数类型说明

Type枚举值	备注
1	用户注册验证码
2	用户忘记密码
3	用户更新手机号码
4	用户短信登录

5.3.2 各类型短信参数描述

5.3.2.1 用户注册验证码

json

{
    "type": 1,
    "code": "验证码",
    "minute": "验证码有效期"
}

5.3.2.2 用户忘记密码

json

{
    "type": 2,
    "code": "验证码",
    "minute": "验证码有效期"
}

5.3.2.3 用户更新手机号码

json

{
    "type": 3,
    "code": "验证码",
    "minute": "验证码有效期"
}

5.3.2.4 用户短信登录

json

{
    "type": 4,
    "code": "验证码",
    "minute": "验证码有效期"
}

第三方邮件集成

一、应用场景

邮件集成服务是物联网平台提供的用于客户自定义邮件发送通道的功能。客户可以使用邮件集成服务实现将物联网平台需要发送邮箱的业务通过客户指定的第三方邮件平台进行发送。可用于以下业务场景：

客户已有自建的统一的邮件系统，需要将物联网平台的邮件通过客户自建的邮件系统发送；
客户希望根据不同用户地区、用户邮箱类型采用不同的邮件发送提供商的邮件发送服务；

二、功能说明

客户在物联网平台管理台【应用中心->集成->邮件服务->邮件配置】中开启第三方邮件平台功能，并填写URL与Token。其中URL是用来接收物联网平台发送的邮件数据接口，URL必须为HTTPS接口；Token用作验证URL有效性。在物联云平台产生一条E-mail后，将使用第三方厂商平台发送E-mail，物联云平台会将E-mail POST到第三方厂商邮件平台，最终由第三方厂商平台将E-mail发出。

邮件主要包含以下几种：
用户注册激活用户重置密码用户更换手机号邮件注册激活码邮件找回密码验证码文件邮件成员报警邮件成员找回邮件

三、前提条件

参考管理台操作手册《应用中台操作手册》，在管理台【应用中心->集成->邮件服务->邮件配置】中选择使用第三方厂商邮件；
在管理台正确配置第三方邮箱URL、Token；
第三方平台在配置的URL上实现验证接口和接收邮件内容的接口；
点击【验证】按钮进行第三方优先系统对接验证，验证完成后点击【保存】按钮；

四、关键流程

4.1. 第三方邮件系统对接流程

流程说明： 成员在管理台进行邮件配置，填写第三方邮件系统URL和Token，进行验证和保存。验证通过后，物联网平台的邮件将发送到配置的第三方邮件系统进行发送。

邮件配置验证

4.2 邮件发送流程

流程说明： 邮件发送者根据不同场景向物联网中台发起 发送邮件 请求，物联网中台收到请求后根据请求信息找出企业下设置第三方邮件系统的地址以及调用凭证，利用邮件系统地址和调用凭证向第三方邮件系统发送邮件。

发送邮件流程

五、API列表

5.1 验证URL有效性

接口描述

在物联网平台配置完URL和Token后，物联网平台会通过配置的URL和Token向第三方厂商发起验证。

验证URL有效性: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。

请求方式

GET

请求地址

由用户在物联网平台管理台配置的URL

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	参数位置	必填	类型	备注
timestamp	query	true	string	时间戳
signature	query	true	string	物联网平台加密签名； 1.签名算法：signature=SHA1(corpId + Token + timestamp)， 2.corpId是企业在物联网平台的企业ID 3.Token由客户在物联网平台管理台填写

验证方法说明：第三方邮件系统通过检验signature对GET请求验证，若自身通过签名算法【SHA1(corpId + Token + timestamp) 】加密得到的数据与请求的signature一致，则返回HTTP状态码 200 OK设置有效，否则设置无效，返回错误消息，统一按照返回消息格式响应。

请求示例：

GET http://tac.com/email/iot?tumestamp=14342587903&signature=37975ef199e20f8b04fbdba750547e42b2e604f3

返回参数说明

校验成功返回http 状态码 200。

返回示例：

http status code ：200

错误返回参数说明

名称	必填	类型	备注
err_code	是	Integer	错误码
err_msg	是	String	错误信息

错误返回示例：

{
    "err_code":"4031003",
    "err_msg":"Token验证失败"
}

错误码：

错误码	描述
4031003	不合法的调用凭证
4041010	企业ID不合法

5.2 发送邮件

接口描述

物联网根据邮件模板生成E-Mail，若管理台邮件配置为【使用第三方厂商邮件】，则将内容POST到管理台填写的URL中，内容为请求Body，第三方厂商负责将E-mail发出。此接口定义物联网平台发出E-mail格式；

发送邮件: 需要符合以下规范，且由外部系统实现，其中请求地址可自定义，调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。

请求方式

POST

请求地址

由用户在物联网平台管理台配置的URL

请求头

名称	必填	类型	备注
Content-Type	true	String	application/json

请求参数

名称	参数位置	必填	类型	备注
subject	body	true	String	要发送的邮件主题
to	body	true	String	接收者E-mail地址，多个地址以英文逗号分隔，如：example1@xlink.cn,example2@xlink.cn
email_param	body	true	Object	邮件参数，具体格式参考本文档附录一
email_param.type	body	true	enum	邮件参数类型，参考5.3.1 邮件参数类型说明
email_param.code	body	false	String	验证码
email_param.hour	body	false	String	验证码有效期, 单位 h
plain_email	body	false	String	邮件原文内容

验证方法说明：第三方邮件系统通过检验signature对GET请求验证，若自身通过签名算法【SHA1(corp_id + Token + timestamp) 】加密得到的数据与请求的signature一致，则返回HTTP状态码 200 OK设置有效，否则设置无效，返回错误消息，统一按照返回消息格式响应。

请求示例：

json

{
    "subject":"用户注册邮件",
    "to":"example1@xlink.cn,example2@xlink.cn",
    "email_param":{
        "type": 1,
        "code":"87d1",
        "hour": 2,
    },
    "plain_email":"邮件内容"
}

返回参数说明

名称	必填	类型	备注
err_code	是	Integer	错误码
err_msg	是	String	错误信息

返回示例：

{
    "err_code":"4031003",
    "err_msg":"Token验证失败"
}

错误码：

错误码	描述
0	发送成功
4002011	email内容不合法
4002012	email接收者地址不合法

5.3 附录一：邮件参数说明

5.3.1 邮件参数类型说明

Type枚举值	备注
1	用户注册激活
2	用户重置密码
3	用户更换手机号
5	邮件注册激活码
6	邮件找回密码验证码
7	文件邮件
8	成员告警信息
9	成员找回密码

5.3.2 各类型邮件参数描述

5.3.2.1 用户注册激活

json

{
    "type": "1",
    "url": "用户激活链接地址",
    "hour": "链接有效期"
}

5.3.2.2 用户重置密码

json

{
    "type": "2",
    "url": "用户重置密码链接地址",
    "hour": "链接有效期"
}

5.3.2.3 用户更换手机号

json

{
    "type": "3",
    "code": "验证码",
    "hour": "验证码有效期"
}

5.3.2.4 邮件注册激活码

json

{
    "type": "3",
    "code": "验证码",
    "hour": "验证码有效期"
}

5.3.2.5 邮件找回密码验证码

json

{
    "type": "5",
    "hour": "激活码有效期"
}

5.3.2.6 文件邮件

json

{
    "type": "7",
    "download_url": "文件下载地址"
}

5.3.2.7 成员报警邮件

json

{
    "type": 8,
    "username": "成员的名称",
    "corporation": "报警企业名称",
    "productName": "报警设备所属产品",
    "time": "成员找回密码时间",
    "email": "成员的邮件地址"
}

5.3.2.8 成员找回邮件

json

{
    "type": 9,
    "url": "找回密码链接",
    "username": "成员的名称",
    "email": "成员的邮件地址",
    "verifycode": "成员找回密码验证码",
    "time": "成员找回密码时间",
    "hour": "成员找回密码链接有效期"
}

APP 开发

APP SDK集成

C端APP集成

第三方服务集成 ​

单点登录集成 ​

一、应用场景 ​

二、功能说明 ​

三、前提条件 ​

四、关键流程 ​

4.1 客户端对接示例流程 ​

4.1.1 场景说明 ​

4.1.2 场景前提 ​

4.1.3 场景接口 ​

4.1.4 流程说明 ​

五、API列表 ​

5.1 单点登录 ​

5.1.1 获取单点登录临时授权码 ​

5.1.2 临时授权码换取单点登录调用凭证 ​

5.1.3 依据单点登录调用凭证注册客户端 ​

5.1.4 成员注销登录 ​

5.1.5 单点登录调用凭证注销登录 ​

5.1.6 单点登录调用凭证换取基本信息 ​

5.2 外部系统实现接口标准 ​

5.2.1 注销登录回调 ​

5.2.2 注销登录回调地址校验 ​

用户第三方认证接口 ​

一、应用场景 ​

二、功能说明 ​

三、前提条件 ​

四、关键流程 ​

4.1 用户第三方认证 ​

五、API列表 ​

5.1 第三方认证设置 ​

5.1.1 设置用户第三方认证配置 ​

5.1.2 查询用户第三方认证配置 ​

5.2 第三方认证登录 ​

5.1.2 第三方用户认证登录 ​

5.3 外部系统实现接口标准 ​

5.3.1 第三方调用凭证和第三方标识校验 ​

六、物联云平台标准第三方平台 ​

6.1 物联云平台标准第三方成员平台 ​

工单集成 ​

一、应用场景 ​

二、功能说明 ​

三、前提条件 ​

四、关键流程 ​

4.1.发起工单 ​

4.2.查询工单 ​

五、API列表 ​

5.1. 工单创建 ​

5.2. 单个工单查询 ​

5.3. 查询工单列表 ​

5.4. 工单状态回调 ​

主数据同步（主数据拉取数据） ​

一、应用场景 ​

二、功能说明 ​

三、前提条件 ​

3.1、全量同步： ​

3.2、增量同步（包括新增，更新，删除）： ​

3.3、同步规则 ​

四、关键流程 ​

4.1、主数据同步流程（拉取数据） ​

五、数据提供方接口规范 ​

5.1 数据获取接口规范 ​

5.2 字段说明 ​

5.2.1 组织数据 ​

5.2.2 项目数据 ​

5.2.3 区域数据 ​

5.2.4 公区数据 ​

5.2.5 楼栋数据 ​

5.2.6 单元数据 ​

5.2.7 楼层数据 ​

5.2.8 房屋数据 ​

5.2.9 住户数据 ​

5.2.10 员工数据 ​

六、枚举详情 ​

6.1、数据类型 ​

6.2、项目类型 ​

6.3、同步操作类型 ​

6.4、房产角色类型 ​

第三方服务集成

单点登录集成

一、应用场景

二、功能说明

三、前提条件

四、关键流程

4.1 客户端对接示例流程

4.1.1 场景说明

4.1.2 场景前提

4.1.3 场景接口

4.1.4 流程说明

五、API列表

5.1 单点登录

5.1.1 获取单点登录临时授权码

5.1.2 临时授权码换取单点登录调用凭证

5.1.3 依据单点登录调用凭证注册客户端

5.1.4 成员注销登录

5.1.5 单点登录调用凭证注销登录

5.1.6 单点登录调用凭证换取基本信息

5.2 外部系统实现接口标准

5.2.1 注销登录回调

5.2.2 注销登录回调地址校验

用户第三方认证接口

一、应用场景

二、功能说明

三、前提条件

四、关键流程

4.1 用户第三方认证

五、API列表

5.1 第三方认证设置

5.1.1 设置用户第三方认证配置

5.1.2 查询用户第三方认证配置

5.2 第三方认证登录

5.1.2 第三方用户认证登录

5.3 外部系统实现接口标准

5.3.1 第三方调用凭证和第三方标识校验

六、物联云平台标准第三方平台

6.1 物联云平台标准第三方成员平台

工单集成

一、应用场景

二、功能说明

三、前提条件

四、关键流程

4.1.发起工单

4.2.查询工单

五、API列表

5.1. 工单创建

5.2. 单个工单查询

5.3. 查询工单列表

5.4. 工单状态回调

主数据同步（主数据拉取数据）

一、应用场景

二、功能说明

三、前提条件

3.1、全量同步：

3.2、增量同步（包括新增，更新，删除）：

3.3、同步规则

四、关键流程

4.1、主数据同步流程（拉取数据）

五、数据提供方接口规范

5.1 数据获取接口规范

5.2 字段说明

5.2.1 组织数据

5.2.2 项目数据

5.2.3 区域数据

5.2.4 公区数据

5.2.5 楼栋数据

5.2.6 单元数据

5.2.7 楼层数据

5.2.8 房屋数据

5.2.9 住户数据

5.2.10 员工数据

六、枚举详情

6.1、数据类型

6.2、项目类型

6.3、同步操作类型

6.4、房产角色类型

6.5、房屋类型

6.6、证件类型

6.7、性别类型