PMS接口的设计参考

应用项目

对应自己的PMS接口，本接口还没完成。

简介

酒店管理软件PMS有不同品牌
不同厂家的通信接口是完全不同
抽象成统一的数据请求接口
注册接口，退房接口，查询和控制各类设备
本文的接口均由PMS或获得受权的app/小程序发起请求

接口基本说明

1. app 采用http通信方式,端口3000
2. http请求URL是hotekey.cn:3000/文中方法
3. 一般从服务器读取数据方式为GET
4. GET请求由URL携带参数
5. 更新数据到服务器方法为PUT
6. 新建一个对象或数据方法为POST
7. POST请求由body携带参数，Content-Type 是 application/json
8. 返回数据都是JSON(除登录页)

(一) PMS系统入住退房管理接口

注：只能通过管理员登录网页操作
管理员编辑与PMS相关的信息

1.3 查看厂家web配置好的PMS信息

1.4 PMS主动发来的客人的CheckIn接口

方法
post(‘/api/pms/checkin’)

请求参数

成功

{
  "checkin":true,
  "area_name":"name"
}

失败

{
  "checkin":false,
  "area_name":"name",
  "err":"string err message"
}

1.4.2 PMS查询某房间的入住情况

方法
get(‘/api/pms/checkin’)

请求参数

成功

[
    {
        "area_name": "888",
        "begin": "2022-06-16 21:28:55",
        "end": "2022-06-19 14:06:02",
        "mobile": "18612345678",
        "name": "张三",
        "identity": "123456789ab"
    },
    {
            //第2个宾客
    },
    {
            //第n个宾客
    }
]

失败

{
  "checkin":false,
  "area_name":"name",
  "err":"string err message"
}

1.5 PMS主动发来的客人CheckOut接口

方法
post(‘/api/pms/checkout’)

请求参数

成功

{
  "checkout":true,
  "area_name":"name"
}

失败

{
  "checkout":false,
  "area_name":"name",
  "err":"string err message"
}

1.6 PMS发送房间续住

方法
post(‘/api/pms/extendstay’)

请求参数

成功

{
  "extendstay":true,
  "area_name":"name",
  "end":"newDateTime"
}

失败

{
  "extendstay":false,
  "area_name":"name",
  "err":"string err message"
}

1.7 PMS发送更换房间

方法
post(‘/api/pms/roomchange’)

请求参数

成功

{
  "roomchange":true,
  "area_name":"name",
  "newroom":"new room"
}

失败

{
  "roomchange":false,
  "area_name":"name",
  "err":"string err message"
}

(二) 操作有授权房间的设备

说明:
请求方可以是PMS，也可以是CheckIn的宾客。
凭手机号获得具体房间的操作权限

1. 用户登录有操作授权的区域
2. 操作区域内的网关
3. 操作区域内的继电器类开关,窗帘，灯光relay
4. 操作区域内的调光类灯光dim
5. 操作区域内的场景联动
6. 操作区域内的弱电IO状态信息

注意:

新建post不启用
删除delete不启用
只对接get,put

2.1.1 获得对app开放的区域列表

方法：get(‘/api/pms/auth_areas’)
固定请求参数: apptag=pc/yangjiangyagepms

返回：数组

[
    {
        "area_id" : "区域id (number)",
        "area_name" : "名字 (string)"
    },
    {
      "..." : "其它信息 (任意类型)"
    }
]

2.1.2 登录并获得开放区域的授权

方法：post(‘/api/pms/auth_login’)
数据：

{
    "apptag" : "app标识符，如小程序wx/wechatid,apk/id,ios/id,pc/id (string)", 
    "area_id": "区域id (number)",
    "mobile" : "用户手机号 (string)"
}

返回：成功

{
    "success" : true 
}

返回：失败

{
    "err" : "error message ..." 
}

返回后的cookie 多了一个pms

{
  "pms" : {
    "area_id":"区域id (number)",
    "mobile" : "用户手机号 (string)",
    "..." : "其它信息 (任意类型)"
  },
  "..." : "cookie 其它信息"
}

2.2 获得已登录授权区域的详细信息

通过获得的pms的cookie,获得授权区域的详细信息
获得授权区域的详细信息

方法：get(‘/api/pms/auth_areas/:area_id’)
数据：无
返回：

{
  "area_id" : "(number)",
  "area_name" : "(string)",
  "area_type" : "(string)",
  "projeck_id" : "(number)",
  "area_floor" : "(string)",
  "..." : "(其它)" 
}

2.3 操作区域内的网关

通过已获得俱有pms的cookie
查询该区域内的网关信息

2.3.1 获取已登录区域内所有网关netways

方法：get(‘/api/pms/auth_netways’)
数据：无
返回：数组

[
  {
    "net_id": 0,
    "net_name": "",
    "area_id": "",
    "net_type": "",
    "net_timestamp": 0,
    "..." : "(其它)" 
  },
  {
    "..." : "其它信息 (任意类型)"
  }
]

2.3.2 获取已登录区域内指定id的网关netways

方法：get(‘/api/pms/auth_netways/:net_id’)
数据：无
返回：

{
  "net_id": 0,
  "net_name": "",
  "area_id": "",
  "net_type": "",
  "net_timestamp": 0,
  "..." : "(其它)" 
}

2.4 操作区域内的继电器类relays

通过已获得俱有pms的cookie
操作该区域内的继电器类relay设备
开关,窗帘,灯光,排气扇

2.4.1 获得指定网关的继电器relays列表

方法：get(‘/api/pms/:net_id/auth_relays’)
数据：无
返回：数组

[
  {
    "relay_id": 0,
    "net_id": 0,
    "relay_name": "",
    "relay_value": "UNKNOW",
    "relay_flow": 0,
    "..." : "(其它)" 
  },
  {
    "..." : "其它信息 (任意类型)"
  }
]

2.4.2 获取指定id的继电器relay的信息

方法：get(‘/api/pms/auth_relays/:relay_id’)
数据：无
返回：

{
  "relay_id": 0,
  "net_id": 0,
  "relay_name": "",
  "relay_value": "UNKNOW",
  "relay_flow": 0,
  "..." : "(其它)" 
}

2.4.3 修改指定id的继电器relay的信息

方法：put(‘/api/pms/auth_relays/:relay_id’)
数据:

{
  "relay_value": "new_value"
}

注：pms 授权不修改其它字段

返回：

{
  "relay_id": 0,
  "relay_value": "new_value"
}

2.5 操作区域内的调光类dims

通过已获得俱有pms的cookie
操作该区域内的调光类dim设备
调光灯,灯带,阅读灯

2.5.1 获得指定网关的调光类dims列表

方法：get(‘/api/pms/:net_id/auth_dims’)
数据：无
返回：数组

[
  {
    "dim_id": 0,
    "net_id": 0,
    "dim_name": "",
    "dim_value": 0,
    "..." : "(其它)" 
  },
  {
    "..." : "其它信息 (任意类型)"
  }  
]

2.5.2 获取指定id的调光器dim的信息

方法：get(‘/api/pms/auth_dims/:dim_id’)
数据：无
返回：

  {
    "dim_id": 0,
    "net_id": 0,
    "dim_name": "",
    "dim_value": 0,
    "..." : "(其它)" 
  }

2.5.3 修改指定id的调光器dim的信息

方法：put(‘/api/pms/auth_dims/:dim_id’)
数据:

{
  "dim_value": "new_value (number)"
}

注：pms 授权不修改其它字段

返回：

{
  "dim_id": 0,
  "dim_value": "new_value (number)"
}

2.6 操作区域内的空调类air

通过已获得俱有pms的cookie
操作该区域内的空调air类设备
开关空调,调节风速,切换制冷制热
设置温度

2.6.1 获取当前网关下所有空调 airs

方法：get(‘/api/pms/:net_id/auth_airs’)
数据：无
返回：数组

[
  {
    "air_id": 0,
    "net_id": 0,
    "POWER": "开/关机 (string)",
    "SPEED": "风速 (string)",
    "MODE": "制冷/制热 (string)",
    "STMP": "16-32度  (number)",
    "..." : "(其它)" 
  },
  {
    "..." : "其它信息 (任意类型)"
  }  
]

2.6.2 获取指定id的空调air的信息

方法：get(‘/api/pms/auth_airs/:air_id’)
数据：无
返回：

{
  "air_id": 0,
  "net_id": 0,
  "POWER": "开/关机 (string)",
  "SPEED": "风速 (string)",
  "MODE": "制冷/制热 (string)",
  "STMP": "16-32度  (number)",
  "..." : "(其它)" 
}

2.6.3 修改指定id的空调air的信息

方法：put(‘/api/pms/auth_airs/:air_id’)
数据:

{
  "POWER": "开/关机 (string)",
  "SPEED": "风速 (string)",
  "MODE": "制冷/制热 (string)",
  "STMP": "16-32度  (number)"
}

注：以上字段可单项设置、多项设置

返回：

{
  "POWER": "开/关机 (string)",
  "SPEED": "风速 (string)",
  "MODE": "制冷/制热 (string)",
  "STMP": "16-32度  (number)"
}

2.7 操作区域内的弱电IO状态信息

通过已获得俱有pms的cookie
操作该区域内的IO类lso
清理,勿扰,门磁,窗磁,插卡

2.7.1 获得指定网关的传感器lsos列表

方法：get(‘/api/pms/:net_id/auth_lsos’)
数据：无
返回：数组

[
  {
    "lso_id": 0,
    "net_id": 0,
    "lso_name": "",
    "lso_value": "UNKNOW",
    "lso_type": "",
    "lso_devID": 0,
    "lso_order": 0,
    "..." : "(其它)" 
  },
  {
    "..." : "其它信息 (任意类型)"
  }
]

2.7.2 获取指定id的传感器lsos的信息

方法：get(‘/api/pms/auth_lsos/:lsos_id’)
数据：无
返回：

{
  "lso_id": 0,
  "net_id": 0,
  "lso_name": "",
  "lso_value": "UNKNOW",
  "lso_type": "",
  "lso_devID": 0,
  "lso_order": 0,
  "..." : "(其它)" 
}

2.7.3 修改指定id的传感器lsos的信息

方法：put(‘/api/pms/auth_lsos/:lsos_id’)
数据:

{
  "lso_value": "new_value"
}

注：pms 授权不修改其它字段

返回：

{
  "lso_id": 0,
  "lso_value": "new_value"
}

2.8 操作区域内的场景联动

通过已获得俱有pms的cookie
操作该区域内的场景类scne
查询场景

2.8.1 获取当前区域内所有场景 scnes

方法：get(‘/api/pms/auth_scnes’)
数据：无
返回：数组

[
  {
    "scn_id": 0,
    "area_id": 0,
    "scn_name": "",
    "scn_type": "",
    "scn_num": 0,
    "scn_json": "json",
    "scn_ico": "",
    "..." : "(其它)" 
  }
]

2.8.2 获取区域内指定scn_id的场景scne

方法：get(‘/api/pms/auth_scnes/:scn_id’)
数据：无
返回：

{
  "scn_id": 0,
  "area_id": 0,
  "scn_name": "",
  "scn_type": "",
  "scn_num": 0,
  "scn_json": "json",
  "scn_ico": "",
  "..." : "(其它)" 
}