## apiprovicer服务接口文档

## 接口响应约定

```json
{
  "code": 0,
  "message": "",
  "result": null
}
```

**code**为0，为请求成功

**message**保存相关的消息提示

**result**为服务器处理结果

### 1.服务功能

为厂商app提供平台原生的api调用能力

### 2.接口说明

| 接口URL                                               | 请求类型 | 功能说明                 |
|-----------------------------------------------------|------|----------------------|
| /application/v1/device/info                         | GET  | 根据device_key获取设备基本信息 |
| /application/v1//devices/{identifier}/info          | GET  | 根据设备identifier获取设备信息 |
| /application/v1/devices/{identifier}/status/current | GET  | 获取设备当前状态             |
| /application/v1/devices/{identifier}/status         | PUT  | 设置设备当前设备的状态          |
| /application/v1/devices/{identifier}/commands       | POST | 向指定设备发送命令            |
| /application/auth                                   | POST | 获取app认证token         |
| /application/v1/device/check_net_config             | GET  | 验证设备配网结果             |

### 2.1 获取App Token

_首先应用方要获取当前应用的授权访问token,为后续的接口请求提供正确的认证,应用方就根据expire_at值自动获取最新的token_

* 接口URL: `application/auth`
* 请求方法: `POST`
* 请求参数: `BODY`

| 参数        | 类型  | 是否必填 | 说明                |
|-----------|-----|------|-------------------|
| AppKey    | 字符串 | Y    | 平台为应用分配的AppKey    |
| Secretkey | 字符串 | Y    | 平台为应用分配的Secretkey |

* 接口响应: `JSON`

```json
{
  "code": 0,
  "message": "",
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBcHBJRCI6MSwiQXBwTmFtZSI6ImNsaWVudCIsIkFwcEtleSI6IjRkMjJmZDZjOWU4YWY0MzQwM2QwZmU2MWMwYzdlNTYzODc4YTg1YWE5ZDE4MGZmNjcyNmUwOWIxYTEzOTdjOTZkN2MyNjkzZWM4NjlhZmU3MDc5ODZmZDgyNTMxYzdlZiIsIlNlY3JldEtleSI6Im5yM3preHBLRDg0UTJCV1giLCJWZW5kb3JJRCI6IjFwczlkanBzd2kwY2RzN2NvZnlua3NvMzAwZXFsNGl1IiwiZXhwIjoxNjMwOTg0MTU2LCJpYXQiOjE2MzA4OTc3NTYsImlzcyI6ImFwaXByb3ZpZGVyIn0.t0KX26p_8Q5WxzU-96Gwg5t6iuFnA8iDmUJk8bmW4Uc",
    "expire_at": 1630984156
  }
}
```

| 字符           | 类型  | 说明         |
|--------------|-----|------------|
| access_token | 字符串 | token字符串   |
| expire_at    | 数字  | 精确到秒的过期时间戳 |

### 2.2 根据设备device_key获取设备信息

_厂商可以通过平台为设备生成的device_key查询设备基础信息_

* 请求URL: `/application/v1/device/info`
* 请求方法: `GET`
* 请求参数: `Query`

| 参数         | 类型  | 是否必填 | 说明                        |
|------------|-----|------|---------------------------|
| device_key | 字符串 | Y    | 设备device_key,注册流程可以得到这个数据 |

* 请求Header:

| 参数            | 类型  | 是否必填 | 说明                                  |
|---------------|-----|------|-------------------------------------|
| Authorization | 字符串 | Y    | 获取AppToken(2.1)接口返回的access_token字段值 |

* 请求响应:

```json
{
  "code": 0,
  "message": "",
  "result": null,
  "data": {
    "identifier": "1-1-relay-test",
    "name": "TSL-8",
    "description": "模块",
    "version": "1.0.0"
  }
}
```

### 2.3 根据设备identifier获取设备基本信息

* 请求URL: `/application/v1/devices/{identifier}/info`
* 请求方法: `GET`
* 请求参数: `Path参数`

| 参数         | 类型  | 是否必填 | 说明                         |
|------------|-----|------|----------------------------|
| identifier | 字符串 | Y    | 设备的identifier,注册流程可以得到这个数据 |

* 请求Header:

| 参数            | 类型  | 是否必填 | 说明                                  |
|---------------|-----|------|-------------------------------------|
| App-Key       | 字符串 | Y    | 由平台分配的应用AppKey的值                    |
| Authorization | 字符串 | Y    | 获取AppToken(2.1)接口返回的access_token字段值 |

* 请求响应: `JSON`

```json
{
  "code": 0,
  "message": "",
  "result": null,
  "data": {
    "identifier": "1-1-relay",
    "name": "TSL-8",
    "description": "模块",
    "version": "1.0.0"
  }
}
```

### 2.4 根据设备identifier获取设备当前最新的状态值

* 请求URL: `/application/v1/devices/{identifier}/status/current`
* 请求方法: `GET`
* 请求参数: `Path参数`

| 参数         | 类型  | 是否必填 | 说明                         |
|------------|-----|------|----------------------------|
| identifier | 字符串 | Y    | 设备的identifier,注册流程可以得到这个数据 |

* 请求Header:

| 参数            | 类型  | 是否必填 | 说明                                  |
|---------------|-----|------|-------------------------------------|
| App-Key       | 字符串 | Y    | 由平台分配的应用AppKey的值                    |
| Authorization | 字符串 | Y    | 获取AppToken(2.1)接口返回的access_token字段值 |

* 请求响应: `JSON`

_data字符中的具体响应内容是根据产品配置中相应的字段名称生成的，以最终配置为准，平台会以格式化的数据，返回设备的最新状态_

```json
{
  "code": 0,
  "message": "",
  "result": null,
  "data": {
    "device_id": 9480,
    "outputState": {
      "route": 2,
      "value": 0
    }
  }
}
```

### 2.5 向指定设备发送指令

* 请求URL: `/application/v1/devices/{identifier}/commands`
* 请求方法: `POST`
* 请求参数: `JSON BODY`

| 参数         | 类型  | 是否必填 | 说明                         |
|------------|-----|------|----------------------------|
| identifier | 字符串 | Y    | 设备的identifier,注册流程可以得到这个数据 |

* BODY体结构: `根据产品的配置文件`

```json
{
  "objects": [
    {
      "no": 1,
      "label": "outputState",
      "part": 1,
      "status": [
        {
          "value_type": 7,
          "name": "route"
        },
        {
          "value_type": 7,
          "name": "value"
        }
      ]
    },
    {
      "no": 2,
      "label": "inputState",
      "part": 1,
      "status": [
        {
          "value_type": 7,
          "name": "route"
        },
        {
          "value_type": 7,
          "name": "value"
        }
      ]
    },
    {
      "no": 3,
      "label": "temperature",
      "part": 1,
      "status": [
        {
          "value_type": 1,
          "name": "degrees"
        }
      ]
    },
    {
      "no": 4,
      "label": "humidity",
      "part": 1,
      "status": [
        {
          "value_type": 1,
          "name": "degrees"
        }
      ]
    }
  ],
  "commands": [
    {
      "no": 1,
      "name": "setState",
      "part": 1,
      "priority": 0,
      "params": [
        {
          "value_type": 7,
          "name": "no"
        },
        {
          "value_type": 7,
          "name": "state"
        },
        {
          "value_type": 8,
          "name": "subDeviceID"
        }
      ]
    }
  ],
  "events": []
}

```

_例如上面的产品配置信息，commands字段有一个指令名称为setState,参数有三个，则传输的结构体为_

```json
{
  "setState": [
    1,
    1,
    1308
  ]
}
```

* 请求Header:

| 参数            | 类型  | 是否必填 | 说明                                  |
|---------------|-----|------|-------------------------------------|
| App-Key       | 字符串 | Y    | 由平台分配的应用AppKey的值                    |
| Authorization | 字符串 | Y    | 获取AppToken(2.1)接口返回的access_token字段值 |

* 请求响应: `JSON`

```json
{
  "code": 0,
  "message": "",
  "result": null
}
```

### 2.6 验证设备配网结果

* 请求URL: `/application/v1/devices/check_net_config`
* 请求方法: `GET`
* 请求参数: `Query`

| 参数          | 类型  | 是否必填 | 说明            |
|-------------|-----|------|---------------|
| device_code | 字符串 | Y    | 设备的identifier |
| md5         | 字符串 | Y    | 校验hash        |

* 响应BODY: `JSON`

```json
{
  "code": 0,
  "message": "",
  "result": false
  // false或true,代表失败或成功
}
```