1、请求结构

请求方法

内容安全支持基于URL发起HTTPS POST请求。请求参数是JSON格式的结构体，以http body的方式发送到服务器端。其中，公共查询参数位于url header参数里。

通信协议

为了获得更高的安全性，仅支持使用HTTPS协议发送请求。

请求参数

您需要在每个请求中指定公共请求参数和具体接口规定的业务请求参数。其中，业务参数以body的方式透传，body结构说明请参见各API接口的具体描述。

字符编码

请求及返回结果都使用UTF-8字符集进行编码。

2、公共请求头参数

2.1 申请app_id与app_secret，每个酒店不同

如申请到的

app_id为：f6cfe45e64c17b638f07e7a623327721

app_secret为：44XYuYwWkC1k6h2r58YHzFXUnYj5NMa9

2.2 签名流程

1、序列化请求参数。

按照以下方式，将HTTP请求参数请拼接成JSON字符串：

{"AppId":"?","NonceStr":"?","Secret":"?","Timestamp":"?"}

其中问号处填入实际值

AppId: 上文中申请到的app_id

NonceStr: 随机字符串

Secret: 上文中申请到的app_secret

Timestamp: unix时间（秒）

数据顺序根据字典排序

2、生成签名

对步骤1中得到的字符串，进行MD5/SHA256算法加密得到bytes数组，并转换为String 为签名结果

3、结果放到HTTP的请求头中

2.3 公共请求头

名称	类型	是否必选	描述
X-Wooyu-AppId	string	是	酒店的app_id
X-Wooyu-Timestamp	string	是	上文中的unix时间(秒)，注意，进入计算处是字符串，而不是integer
X-Wooyu-NonceStr	string	是	上文中的随机字符串
X-Wooyu-SignMethod	string	是	加密方式，MD5 或是 SHA256
X-Wooyu-Signature	string	是	签名结果

3、接口测试

连通性测试

URL: https://yueketong.com/open/ping.json

METHOD：GET

RESPONSE:

{
  "errcode": 0,
  "msg": "pong",
  "request_uuid": "7e037745-d1b2-4110-9867-8afb789cceda",
  "timestamp": 1712120099
}

timestamp 为服务器时间

request_uuid 为请求追踪值，下文所有API中都包含，若出现API请求问题，需要提供对应的数据。

4、物业基础信息

4.1 基础信息

URL: https://yueketong.com/open/hotels/info.json

METHOD: GET

RESPONSE:

{
  "errcode": 0,
  "msg": "SUCCESS",
  "request_uuid": "cac7ae9d-f8ba-466d-abe1-8a5fa55fa1e8",
  "hotel": {
    "name": "无忧住体验公寓",
    "lat": "22.791252",
    "lng": "113.529085",
    "short_name": "无忧住体验公寓",
    "contact_phone": "XXXXXXXXX",
    "default_checkout_time": "14:00",
    "uuid": "18cefaeeb6ffe",
    "expires_at": "2100/01/01"
  }
}

4.2 更新酒店信息

URL: https://yueketong.com/open/hotels/update_info.json

METHOD: POST

请求参数：

{
  "attrs": [
    {"column": "name", "value": "酒店名称"},
    {"column": "short_name", "value": "酒店简称"},
    {"column": "lat", "value": "酒店简称"},
    {"column": "lng", "value": "酒店简称"},
    {"column": "contact_phone", "value": "酒店简称"},
    {"column": "default_checkout_time", "value": "酒店简称"},
  ]
}

name lat lng short_name contact_phone default_checkout_time 为可用 column 值，若不存在的值，则直接报错

RESPONSE:

{
  "errcode": 0,
  "msg": "SUCCESS",
  "request_uuid": "cac7ae9d-f8ba-466d-abe1-8a5fa55fa1e8",
  "hotel": {
    "name": "无忧住体验公寓",
    "lat": "22.791252",
    "lng": "113.529085",
    "short_name": "无忧住体验公寓",
    "contact_phone": "XXXXXXXXX",
    "default_checkout_time": "14:00",
    "uuid": "18cefaeeb6ffe",
    "expires_at": "2100/01/01"
  }
}

ERROR RESPONSE:

{
  "errcode": 1,
  "msg": "字段不允许，操作中止",
  "request_uuid": "83cf7cc8-8866-4040-afb5-c788dd60ae1d"
}

4.3 获取房间号

URL: https://yueketong.com/open/rooms.json

METHOD: GET

RESPONSE:

{
  "errcode": 0,
  "msg": "",
  "request_uuid": "f3d4122d-abd7-4de8-8fda-61bda1c2c173",
  "data": {
    "total": 600,
    "pagesize": 10,
    "page": 1,
    "rooms": [
      {
        "id": 33,
        "uuid": "0b25465a7e034ffb8a9e855d92d6f717",
        "name": "8201",
        "lock_state": "already_setup",
        "voltage_per": 100,
        "has_keyboard": true,
        "building_id": 1,
        "floor_id": 1,
        "status": "empty"
      },
      {
        "id": 34,
        "uuid": "407c73926a6b46ea8158de3e9544e4cc",
        "name": "8202",
        "lock_state": "already_setup",
        "voltage_per": 17,
        "has_keyboard": true,
        "building_id": 1,
        "floor_id": 1,
        "status": "empty"
      },
      ...
    ]
  }
}

5、手机钥匙

URL: https://yueketong.com/open/room_keys.json

METHOD: POST

请求参数：

参数	值类型	是否必填	说明
type	String	是	推送类型： checkin：办理入住 checkout：办理退房 room_change：换房 extension：续住，修改离店时间 mobile_change：入住客户更新手机号 add_companion：当前房间或预订添加额外的同住人 remove_companion：同一入住订单移除同住人
building_id	String	是	获取房间号时取得的 building_id，如果是简单物业，可以直接向门锁系统获取
room_no	String	是	房间号，PMS与门锁系统需保持一致
tracking_no	String	是	PMS唯一入住单单号，方便PMS数据核查
payload	Json	是	根据不同的type传不同的内容，内容下文进行详细说明

type 对应 payload 类型

5.1 checkin

payload

{
    phone_number: '1234567890', // 入住人手机号，手机号为订单内维一标识，添加、移除以手机号为标准
    guest_name: '用户姓名',         // 用户姓氏
    checkin_time: '',           // 用户入住时间，使用unix时间（秒）
    checkout_time: '',          // 用户离店时间，使用unix时间（秒）
    gender: '',                 // 性别，男 / 女 / 保密
    generate_password: false,   // 是否创建密码，注意：创建密码接口时间会长200ms左右
}

RESPONSE:

{
    errcode: 0,
    checkin: {
        qrcode_str: 'https://wu-iot.com/uqr/rkh6nlwsqeumm8', // 二合一码，生成二维码扫一扫即可进入，发送给客人也可以
        password: '02313',  //在generate_password时生成，注意：最前面若存在0也是有意义的
        password_msg: '',   //密码信息，出错时候的提示。
    }
}

5.2 checkout

payload

{}

RESPONSE:

{
    errcode: 0,
    checkout: {}
}

5.3 room_change

换房后，原房间会checkout

payload

{
    target_room_no: "",         // 目标房间名称
    target_building_id: "",     // 目标楼栋ID，相同楼栋可不传
    checkout_time: '',          // 是否修改离店时间，使用unix时间（秒）,若不传，保持原订单时间
}

5.3 extension

payload

{
    checkout_time: '',          // 修改离店时间，使用unix时间（秒）
}

5.4 mobile_change

payload

{
    phone_number: "",           // 旧的手机号
    new_phone_number: "",       // 新的手机号
}

5.5 add_companion

payload

{
    phone_number: '1234567890', // 入住人手机号，手机号为订单内维一标识，添加、移除以手机号为标准
    guest_name: '用户姓名',         // 用户姓氏
    checkin_time: '',           // 用户入住时间，使用unix时间（秒）
    checkout_time: '',          // 用户离店时间，使用unix时间（秒）
    gender: '',                 // 性别，男 / 女 / 保密
}

5.6 remove_companion

payload

{
    phone_number: "",           // 需要移除的手机号
}