robot_open_platform_develop_document_cn - HMIP3.0以及NLP使用说明

# 科沃斯机器人开放平台接入文档

## 产品介绍

科沃斯机器人开放平台是科沃斯提供给第三方组织或个人接入科沃斯机器人产品的开发平台。
平台主要提供以下能力：控制科沃斯机器人产品的启动停止等相关功能。

## 第三方接入流程

### １、创建第三方开发平台应用（目前无需创建，由科沃斯直接提供应用信息）

* 在科沃斯机器人开放平台中，填写第三方平台应用的基本信息、需要的权限和相关参数后，即可创建第三方平台应用。

### ２、操控地宝

* 第三方发起科沃斯授权登录请求，加载科沃斯授权登录页面。
* 采取oauth2.0标准协议授权。具体查看 [oauth](#oauth)
* 根据科沃斯协议，获取用户的设备列表。具体查看[获取用户设备列表](#获取用户设备列表)
* 根据科沃斯指令协议，对指定地宝发送指令，操控地宝。具体查看[机器人产品控制接口](#机器人产品控制接口)

## OAUTH

### 1、相关概念

第三方在接入科沃斯机器人平台时，必须得到科沃斯产品用户的许可，通过OAUTH的方法第三方平台可以引导用户完成许可授权。只有得到用户授权后，第三方平台才可以调用相关接口控制科沃斯机器人产品。

### 2、准备工作

科沃斯账号登录是基于OAuth2.0协议标准构建的授权登录系统。 在进行科沃斯OAuth2.0授权登录接入之前，在科沃斯开放平台注册开发者帐号，创建网站应用，生成相应的client_id和client_secret，并填写redirect_uri。申请科沃斯登录，在通过审核后，可开始接入流程。（client_id和client_secret目前由科沃斯直接提供）

### 3、授权流程说明

科沃斯OAuth2.0授权登录让科沃斯用户使用科沃斯身份安全登录第三方应用或网站，在科沃斯用户授权登录已接入科沃斯OAuth2.0的第三方应用后，第三方可以获取到用户的接口调用凭证（access_token），通过access_token可以进行科沃斯开放平台授权关系接口调用，从而可实现获取科沃斯用户基本开放信息和帮助用户实现基础开放功能等。 科沃斯OAuth2.0授权登录目前仅支持authorization_code模式，适用于拥有server端的应用授权。流程为：

1. 第三方发起科沃斯授权登录请求，加载科沃斯授权登录页面。
    2. 科沃斯用户允许授权第三方应用后，科沃斯会拉起应用或重定向到第三方网站，并且带上授权临时票据code参数。
    3. 通过code参数加上client_id和client_secret等，通过API换取access_token。
    4. 通过access_token进行接口调用，获取用户基本数据资源或帮助用户实现基本操作。

### ４、科沃斯授权登录页面

#### URL

```
https://<ACCOUNT_SERVICE_DOMAIN>/newauth/default/default/1/0/ologin.htm?client_id={client_id}&redirect_uri={redirect_uri}&state={state}
```

### ５、通过code获取access_token（参考oauth2.0标准文档 <https://oauth.net/2/>）

#### URL

```
https://<ACCOUNT_SERVICE_DOMAIN>/api/newauth/oauth2/token

https://account.ecouser.net/api/newauth/oauth2/token?client_id=4f846d53-4921-443b-8753-ce0aba83d368&client_secret=D4RU5R8YhDebBHnG513nrSFft3DjFnDB&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL
```

### ６、刷新access_token（参考oauth2.0标准文档 <https://oauth.net/2/>）

#### 说明

access_token是调用授权关系接口的调用凭证，由于access_token有效期（目前为24个小时）较短，当access_token超时后，可以使用refresh_token进行刷新，使用refresh_token刷新access_token后会同时返回新的refresh_token并更新有效期。
refresh_token拥有较长的有效期（7天），当refresh_token失效的后，需要用户重新授权。

#### URL

```
https://<ACCOUNT_SERVICE_DOMAIN>/api/newauth/oauth2/token
```

## 注意

1. client_secret 是应用接口使用密钥，泄漏后将可能导致应用数据泄漏、应用的用户数据泄漏等高风险后果；存储在客户端，极有可能被恶意窃取（如反编译获取client_secret）；
2. access_token 为用户授权第三方应用发起接口调用的凭证（相当于用户登录态），存储在客户端，可能出现恶意获取access_token 后导致的用户数据泄漏、科沃斯接口被恶意调用等行为；
3. refresh_token 为用户授权第三方应用的长效凭证，仅用于刷新access_token，但泄漏后相当于access_token 泄漏，风险同上。

建议将client_secret、用户数据（如access_token）放在App云端服务器，由云端中转接口调用请求。

## 用户相关接口

### 获取用户信息

#### 说明

此接口用于获取用户个人信息

#### 调用方法

* 协议：HTTPS
* 方法：POST
* 数据格式：JSON
* url: ```https://<ACCOUNT_SERVICE_DOMAIN>/api/newauth.do?td=GetUserInfoByToken```
* Request header

```json
{
    "Content-Type": "application/json"
}
```

* Request body example

```json
{
    "token": ""
}
```

* Request parameters

| 参数        |  参数说明  |  参数类型  |
| --------   | :----  | -----|
| todo     |  固定值 GetUserInfoByToken    |   string    |
|token        | access_token |string|

* Response example

```json
{
    "todo": "result",
    "result": "ok",
    "userID": ""
}

```

* Response parameters

| 参数        |  参数说明  |  参数类型  |
| --------   | :----  | -----|
| todo     |  固定值 result    |   string    |
|result        | ok－请求成功，fail－请求失败 |string|
|userID        | 用户标识，ok-存在，fail-不存在|string|

## 获取用户设备列表

### 说明

开发者通过此接口，可以拿到用户的设备列表，主要包含机器的三元组did，mid，res

### 调用方法

* 协议：HTTPS
* 方法：POST
* 数据格式：JSON
* url: ```https://<ROP_SERVICE_DOMAIN>/api/rop/req.do?td=GetDeviceList```
* Request header

```json
{
    "Content-Type": "application/json"
}
```

* Request body

```json
{
    "data": {
        "app": {
            "id": "",
            "ts": 123,
            "sig": "",
            "crypt": "AES-X"
        }
    },
    "auth": {
        "with": "oauth",
        "token": ""
    }
}
```

* Request parameters

| 参数        |  参数说明  |  参数类型  |
| --------   | :----  | -----|
|td     |  固定值 GetDeviceList    |   string    |
| data.app.id       | yes |   应用创建时系统分配的app_id   | string |
| data.app.ts       | yes |   当前的时间戳，单位毫秒     |   number    |
| data.app.sig      | yes |  使用对称加密方式对时间进行加密, 具体内容查看下方AES对称加密[AES对称加密](#AES对称加密)   | string |
| data.app.crypt      | yes |  "AES-S"或者"AES-X"   | string |
|auth.with        | 固定值 oauth |   string|
|auth.token       | access_token|  string|

* Response

```json
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "did": "",
            "name": "",
            "class": "",
            "resource": "",
            "nick": "",
            "cchost": "",
            "evthost": "",
        }
    ]
}
```

* Response parameters

| 参数        |  参数说明  |  参数类型  |
| --------   | :----  | -----|
|code        | 0－请求成功，非0值－请求失败 |number|
|msg        | 附加信息 |string|
|data        |用户设备列表，ok-存在，fail-不存在| array|
| did     |  每台机器有唯一的did，发送指令需携带did    |   string    |
| name     |  每台机器有唯一的sn码    |   string    |
|class        | 机器的型号，发送指令需携带class，又称为mid |string|
|resource        | 发送指令需携带，简称res |string|
|nick        | 用户给机器起的昵称 |string|
|cchost        | 后续对该机器进行操控的接口host |string|
|evthost        | 后续对该机器进行事件订阅的接口host |string|

## 机器人产品控制接口

### 说明

开发者通过此接口可以控制科沃斯扫地机器人

### 调用方法

* 协议：HTTPS
* 方法：POST
* 数据格式：JSON
* url: ```https://<ROP_SVC_CC_HOST>/api/cloudctl/ctl.do?td=ctl```
* Request header

```json
{
    "Content-Type": "application/json"
}
```

* Request body

```json
{
    "data": {
        "app": {
            "id": "",
            "ts": 123,
            "sig": "",
            "crypt": "AES-S"
        },
        "ctl": {
            "did": "",
            "mid": "",
            "res": "",
            "cmd": "",
            "data": {}
        }
    },
    "auth": {
        "with": "oauth",
        "token": ""
    }
}
```

* Request parameters

| 参数        | 是否必填   |  参数说明    |  参数类型  |
| --------   | -----:  | :----  | -----|
| td                | yes |   固定值 ctl     |   string    |
| data.app.id       | yes |   应用创建时, 系统分配的app_id   | string |
| data.app.ts       | yes |   当前的时间戳，单位毫秒     |   number    |
| data.app.sig      | yes |  使用对称加密方式对时间进行加密, 具体内容查看下方AES对称加密[AES对称加密](#AES对称加密)   | string |
| data.app.crypt      | yes | "AES-S"或者"AES-X"   | string |
| data.ctl.did      | yes |  所控制机器的did，可通过GetDeviceList获取  |   string   |
| data.ctl.mid      | yes |  所控制机器的类型，可通过GetDeviceList获取  |    string  |
| data.ctl.res      | yes |    所控制机器的res,可通过GetDeviceList获取，res是不固定的|    string  |
| data.ctl.cmd      | yes |  向机器发送的请求名称，如Clean、Charge等。具体可查看Robot Control Protocol document  |     string |
| data.ctl.data     | yes |  请求所携带的参数，随着cmd的改变而改变。具体可查看Robot Control Protocol document  |   object   |
| auth.with         | yes |  固定值 oauth  |     string |
| auth.token        | yes |  access_token  |     string |

* Response

```json
{
    "code": 0,
    "msg": "",
    "data": {
        "ctl": {
            "data": {
                "ret": "",
                "errno": 1000,
                "$CMDRESKEY": $CMDRESVAL
            }
        }
    }
}
```

* Response parameters

| 参数        |  参数说明  |  参数类型  |
| --------   | :----  | -----|
|code        | 0－请求成功，others－请求失败 |number|
|msg        | 附加信息 |string|
|data        | - |object|
|data.ctl        | - |object|
|data.ctl.data  | - |object|
|data.ctl.data.ret        | ok－cmd执行成功，fail－cmd执行失败 |string|
|data.ctl.data.errno        | 错误码，请求失败时才存在，参考robot_control_protocol.md中具体cmd的errno|number|
|data.ctl.data.$CMDRESKEY      | 参考robot_control_protocol.md中具体cmd的resp|-|

### AES对称加密

* 对称加密：采用单钥密码系统的加密方法，同一个密钥可以同时用作信息的加密和解密，这种加密方法称为对称加密，也称为单密钥加密。
    * 方式：对称加密目前主流的有 AES 和 DES，我们采取AES方式，速度快，安全级别更高。

样例，代码使用nodejs：

```js
//下载第三方库Crypto-js.js git地址：https://github.com/brix/crypto-js
//引入src下的crypto-js.js，加密代码如下：

var encryptKey = "12345678"  //密钥，由科沃斯提供

## 事件上报相关接口

### 订阅设备事件通知

#### 描述

在可以接受上报事件前，首先要订阅事件

#### 调用方法

* Protocol: HTTPS
* HTTP method: POST
* Request URL: ```https://<ROP_SVC_EVT_HOST>/api/rop/event.do?td=subDevEvt```
* Request payload parameters

* Request payload example

```json
{
    "auth": {
        "with": "oauth",
        "token": ""
    },
    "data": {
        "did": "",
        "appid": "",
        "name": ["Clean"]
    }
}
```
  
* Response payload example

```json
{
    "code": 0,
    "msg": "",
    "data": {
        "last": 30*60*1000
    }
}
```

* Response parameters

### 订阅设备事件通知2

#### 描述

在可以接受上报事件前，首先要订阅事件，比"订阅设备事件通知"的接口多一些字段

#### 调用方法

* Protocol: HTTPS
* HTTP method: POST
* Request URL: ```https://<ROP_SVC_EVT_HOST>/api/rop/event.do?td=subDevEvt2```
* Request payload parameters

| Parameters  | required   |  Parameters description   |  Parameter type  |
| --------    | -----:    | :----       | -----|
| td     | yes |   fixed value subDevEvt                      |   string    |
| auth.with   | yes |   fixed with "oauth"     |   string    |
| auth.token  | yes |   access_token got from OAUTH process               |   string    |
| data.did    | yes |   device identifier                        |   string    |
| data.name   | yes |   event name, see Robot Control Protocol document                 |   string[]    |
| data.appid  | yes |   assigned by the system when the application was created(currently provided directly by ECOVACS)                 |   string    |
| data.callback.url  | yes |   url to accept the post event data  |   string    |
| data.callback.auth  | no |     |   object    |
| data.callback.auth.with  | - |   fix with "Basic"  |   string    |
| data.callback.auth.username  | - |   http basic authorization username  |   string    |
| data.callback.auth.password  | - |   http basic authorization password  |   string    |
| data.expireIn    | no |   subscribe expire in, unit millisecond, if this value is bigger than value specified in server, the actual value will be returned in response's last   |   number    |

* Request payload example

```json
{
    "auth": {
        "with": "oauth",
        "token": ""
    },
    "data": {
        "did": "",
        "appid": "",
        "name": ["Clean", "Charge"],
        "callback": {
            "url": "",
            "auth": {
                "with": "Basic",
                "username": "",
                "password": ""
            },
        },
        "expireIn": 5*60*1000
    }
}
```
  
* Response payload example

```json
{
    "code": 0,
    "msg": "",
    "data": {
        "last": 30*60*1000
    }
}
```

* Response parameters

### 取消订阅设备事件通知

#### Description

如果不想收到事件推送，取消订阅这条事件

#### Call method

* Protocol: HTTPS
* HTTP method: POST
* Request URL: ```https://<ROP_SVC_EVT_HOST>/api/rop/event.do?td=unsubDevEvt```
* Request payload parameters

| Parameters  | required   |  Parameters description   |  Parameter type  |
| --------    | -----:    | :----       | -----|
| td     | yes |   fixed value unsubDevEvt                      |   string    |
| auth.with   | yes |   fixed with "oauth"     |   string    |
| auth.token  | yes |   access_token got from OAUTH process               |   string    |
| data.did    | yes |   device identifier                        |   string    |
| data.name   | yes |   event name, see Robot Control Protocol document                 |   string[]    |
| data.appid  | yes |   assigned by the system when the application was created(currently provided directly by ECOVACS)                 |   string    |

* Request payload example

```json
{
    "auth": {
        "with": "oauth",
        "token": ""
    },
    "data": {
        "did": "",
        "appid": "",
        "name": ["Clean"]
    }
}
```
  
* Response payload example

```json
{
    "code": 0,
    "msg": ""
}
```

* Response parameters

### 查询设备事件订阅

#### Description

查询设备订阅的剩余生效时间，如果某事件已经过期，回复结果不包含该事件

#### Call method

* Protocol: HTTPS
* HTTP method: POST
* Request URL: ```https://<ROP_SVC_EVT_HOST>/api/rop/event.do?td=queryDevEvt```
* Request payload parameters

* Request payload example

```json
{
    "auth": {
        "with": "oauth",
        "token": ""
    },
    "data": {
        "did": "",
        "appid": "",
        "name": ["Clean", "Charge"]
    }
}
```
  
* Response payload example

```json
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "name": "Clean",
            "last": 1*60*60*1000,
            "callbackUrl": "https://webhook-callback-url.com"
        },
        {
            "name": "Charge",
            "last": 5*1000,
            "callbackUrl": "https://webhook-callback-url.com"
        }
    ]
}
```

* Response parameters

| Parameters | Parameter description | Parameter type |
| --------   | :----  | -----|
| code       | 0-request succeeded, 1000-internal failed | string |
| msg           | some additional message to help understand the result | string |
| data.$.name | event name, see Robot Control Protocol document | string |
| data.$.last | event report remaining time from current, unit in millisecond | number |
| data.$.callbackUrl | the callback url when call subDevEvt2, not exsit when call subDevEvt | string |

### Event report web hook

### 描述

当机器产生某些事件的时候，ROP会调用此接口传入事件相关信息。接入方需要实现该接口，当使用subDevEvt时需提供URL到科沃斯，当使用subDevEvt2时，url为subDevEvt2接口传入的url
该接口必须实现为https方式。

### Request

* URL: ```https://<guests_provide>``` or ```subDevEvt2中传入的url```

* HTTP method: POST

* Request header parameters

| 参数         | 是否必填   |  参数说明    |  参数类型  |
| --------    | -----:    | :----       | -----|
| Authorization     | no |    exist if subDevEvt2 has auth  |   string    |

* Request payload parameters

| 参数         | 是否必填   |  参数说明    |  参数类型  |
| --------    | -----:    | :----       | -----|
| id     | yes |   unqiue identifier                        |   string    |
| sign   | no |   use symmetric encryption to encrypt time, see [AES symmetric encryption](#AES对称加密), if Authorization exist in header, this can be omitted      |   string    |
| ts     | yes |   unix timestamp, unit in ms               |   string    |
| uid    | yes |   ecovacs user id                          |   string[]  |
| did    | yes |   device identifier                        |   string    |
| name   | yes |   event name, see Robot Control Protocol document                 |   string    |
| data   | yes |   event data, see Robot Control Protocol document                 |   object    |

* Request payload example

```json
{
    "id": "",
    "sign": "",
    "ts": ,
    "uid": [""],
    "did": "",
    "name": "",
    "data": {}
}
```

* Response example

```json
{
    "ret": "ok"
}
```

| 参数名 | 参数描述 | 参数类型 |
| --------   | :----  | -----|
| ret | ok-request succeeded, fail-request failed | string |

## 机器人产品控制接口常见错误码

| 错误码        |  错误码说明  |
| --------   | :----  |
|4000        | 请求体的格式错误|
|4500        | 服务端内部错误|
|4501        | appid无效|
|4504        | token校验失败|
|4508        | 请求体里ts与服务端收到该请求的时间超过了2分钟或者sig错误|
|4509        | appid已被删除|
|4511        | appid未配置该机型|
|4512        | appid未配置该机型的该指令|
|5009        | 服务端不支持该机型的该指令|
|10000       | 主机低电，无法完成发送的指令|
|10004       | 主机离线，请求超时或者是地宝已关机或者地宝被他人重新配网|
|10005       | 主机故障，如地宝悬空、尘盒未安装等|

## 域名定义

### 中国大陆销售的机型

* ACCOUNT_SERVICE_DOMAIN: account.ecouser.net
* ROP_SERVICE_DOMAIN: rop.ecouser.net
* ROP_SVC_CC_HOST: returned in the response filed 'cchost' of GetDeviceList
* ROP_SVC_EVT_HOST: returned in the response filed 'evthost' of GetDeviceList

### 中国大陆之外销售的机型

* ACCOUNT_SERVICE_DOMAIN: account-ww.ecouser.net
* ROP_SERVICE_DOMAIN: rop-ww.ecouser.net
* ROP_SVC_CC_HOST: returned in the response filed 'cchost' of GetDeviceList
* ROP_SVC_EVT_HOST: returned in the response filed 'evthost' of GetDeviceList