PMS 开放 API

更新时间：2025-05-30 01:56:03下载pdf

本文介绍了适用于酒店管理系统（Property Management System，PMS）的应用程序编程接口 (Application Programming Interface，API)。

API 列表

请求方式	API	描述
POST	/v1.0/hotel/pms/checkin	入住
PUT	/v1.0/hotel/pms/checkout	退房
PUT	/v1.0/hotel/pms/change-room	换房
PUT	/v1.0/hotel/pms/renew	续住
POST	/v1.0/hotel/pms/checkin/guest	添加入住人
PUT	/v1.0/hotel/pms/checkin/guest	修改入住人
DELETE	/v1.0/hotel/pms/checkin/guest	删除入住人
POST	/v1.0/hotel/pms/rooms	新增客房
DELETE	/v2.0/hotel/pms/rooms	删除客房
POST	/v1.0/hotel/pms/rooms/sync	客房信息全量同步
GET	/v1.0/hotel/pms/face/picture/score	获取人脸照片评分
POST	/v1.0/hotel/pms/face/picture	入住机上传人脸图片
PUT	/v1.0/iot-02/pms/customers	人员信息推送
GET	/v1.0/iot-02/pms/customers	人员信息分页获取

入住

接口描述

当 PMS 系统有客户入住，则将入住信息同步至智慧酒店公寓平台。

接口地址

POST /v1.0/hotel/pms/checkin

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[]	是	入住的详细信息	BODY

data 参数说明

参数名	类型	参数类型	说明	是否必需
checkin_id	String	BODY	客户入住唯一标识	是
room_no	String	BODY	房间号，最大长度为 10 个字符	是
building	String	BODY	楼栋，最大长度为 10 个字符	否
floor	String	BODY	楼层，最大长度为 10 个字符	否
checkin_time	Long	BODY	入住时间，标准 13 位时间戳	是
checkout_time	Long	BODY	离店时间，标准 13 位时间戳	是
cust_name	String	BODY	入住人姓名	是
gender	String	BODY	入住人性别。 `0`：女 `1`：男	是
phone_no	String	BODY	入住人手机号	是
id_card_no	String	BODY	证件号	是
id_card_type	String	BODY	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	是
face_picture_url	String	BODY	人脸照片 URL 路径	否

可能存在批量入住情况，data 数据可能是同一个消息体里面多条数据推送，因此是个 object 数据。如果数据里面 room_no + floor + building 相同的话，表示多人入住同一个房间。
checkin_id 是每个客人入住的唯一标识，酒店能通过此标识对客人进行各种业务类型操作。

请求示例

POST  {url}/v1.0/hotel/pms/checkin

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14136",
            "room_no":"2703",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ"
        },
        {
            "checkin_id":"14137",
            "room_no":"2703",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
 "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

退房

接口描述

当 PMS 系统有客户退房，则将退房信息同步至智慧酒店公寓平台。

接口地址

PUT /v1.0/hotel/pms/checkout

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[]	是	退房的详细信息	BODY

data 参数说明

参数名	类型	必填	描述	参数类型
checkin_id	String	是	客户入住唯一标识	BODY
departure_time	Long	是	实际离店时间，标准 13 位时间戳	BODY
id_card_no	String	是	证件号	BODY
id_card_type	String	是	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	BODY
phone_no	Long	是	用户手机号码	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

PUT  /v1.0/hotel/pms/checkout

    "hotel_code":"800884",
    "data":[
        {
            "departure_time":1565568000000,
            "checkin_id":"14136",
            "phone_no":"XXXXXXXXXXX",
            "id_card_no":"XXXXXXXXXXX",
            "id_card_type":"SFZ"
        },
        {
            "departure_time":1565568000000,
            "checkin_id":"14137",
            "phone_no":"XXXXXXXXXXX",
            "id_card_no":"XXXXXXXXXXX",
            "id_card_type":"SFZ"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

换房

接口描述

当 PMS 系统有客户换房，则将换房信息同步至智慧酒店公寓平台。

接口地址

PUT /v1.0/hotel/pms/change-room

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[]	是	换房的详细信息	BODY

data 数据说明

参数名	类型	必填	描述	参数类型
new_checkin_id	String	是	客户入住唯一标识	BODY
old_checkin_id	String	是	客户入住的旧标识	BODY
room_no	String	是	房间号，最大长度为 10 个字符	BODY
building	String	否	楼栋，最大长度为 10 个字符	BODY
floor	String	否	楼层，最大长度为 10 个字符	BODY
checkin_time	Long	是	入住时间，标准 13 位时间戳	BODY
checkout_time	Long	是	预离店时间，标准 13 位时间戳	BODY
cust_name	String	是	入住人姓名	BODY
gender	Integer	是	入住人性别。 `0`：女 `1`：男	BODY
phone_no	String	是	用户手机号码	BODY
id_card_no	String	是	入住人身份证件号	BODY
id_card_type	String	是	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	BODY

如果变更房间后 checkin_id 不发生变化的话，就使 new_checkin_id 与 old_checkin_id 保持相同。

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

PUT  /v1.0/hotel/pms/change-room

{
    "hotel_code":"800884",
    "data":[
        {
            "new_checkin_id":"14136",
            "old_checkin_id":"14136",
            "room_no":"2705",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxxx",
            "id_card_type":"SFZ"
        },
        {
            "new_checkin_id":"14136",
            "old_checkin_id":"14136",
            "room_no":"2705",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "gender":1,
            "cust_name":"xxx",
            "phone_no":"xxxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxxx",
            "id_cardt_type":"SFZ"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

 {
     "code":500,
     "msg":"System error, please contact the admin",
     "success":false,
     "t":1561378856383
 }

续住

接口描述

当 PMS 系统有客户续住，则将续住信息同步至智慧酒店公寓平台。

接口地址

PUT /v1.0/hotel/pms/renew

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[]	是	续住的详细信息	BODY

data 数据说明

参数名	类型	必填	描述	参数类型
checkin_id	String	是	客户入住唯一标识	BODY
id_card_no	String	是	入住人身份证件号	BODY
id_card_type	String	是	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	BODY
checkout_time	Long	是	实际离店时间，标准 13 位时间戳	BODY

响应参数

参数名	类型	说明
code	Integer	Integer
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

PUT /v1.0/hotel/pms/checkout

{
    "hotel_code":"800884",
    "data":[
        {
            "checkout_time":1565568000000,
            "id_card_no":"xxxxx",
            "id_card_type":"SFZ",
            "checkin_id":"14136"
        },
        {
            "checkout_time":1565568000000,
            "id_card_no":"xxxxx",
            "id_card_type":"SFZ",
            "checkin_id":"14137"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

添加入住人

接口描述

当 PMS 系统添加新的入住人，则将入住人信息同步至智慧酒店公寓平台。

接口地址

POST /v1.0/hotel/pms/checkin/guest

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[]	是	入住人的详细信息	BODY

data 数据说明

参数名	类型	必填	描述	参数类型
checkin_id	String	是	客户入住唯一标识	BODY
room_no	String	是	房间号，最大长度为 10 个字符	BODY
building	String	BODY	楼栋，最大长度为 10 个字符	否
floor	String	BODY	楼层，最大长度为 10 个字符	否
checkin_time	Long	是	入住时间，标准 13 位时间戳	BODY
checkout_time	Long	是	离店时间，标准 13 位时间戳	BODY
cust_name	String	是	入住人姓名	BODY
gender	Integer	是	入住人性别。 `0`：女 `1`：男	BODY
phone_no	String	是	入住人手机号	BODY
id_card_no	String	是	证件号	BODY
id_card_type	String	BODY	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	是
face_picture_url	String	否	人脸照片 URL 路径	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

POST /v1.0/hotel/pms/checkin/guest

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14138",
            "room_no":"2705",
            "checkin_time":1576055286000,
            "checkout_time":1576216800000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type": "SFZ"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

修改入住人

接口描述

当 PMS 系统有客户信息修改，则将客户信息同步至智慧酒店公寓平台。

接口地址

PUT /v1.0/hotel/pms/checkin/guest

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[ ]	是	入住人的详细信息	BODY

data 数据说明

参数名	类型	必填	描述	参数类型
checkin_id	String	是	客户入住唯一标识	BODY
cust_name	String	是	入住人姓名	BODY
id_card_no	String	是	用户身份证号码	BODY
id_card_type	String	是	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	BODY
gender	Integer	是	入住人性别。 `0`：女 `1`：男	BODY
new_phone_no	String	是	新手机号	BODY
old_phone_no	String	是	旧手机号	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

PUT {url}/v1.0/hotel/pms/checkin/guest

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14137",
            "cust_name":"xxx",
            "gender":1,
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ",
            "new_phone_no":"xxxxxxxxxxx",
            "old_phone_no":"xxxxxxxxxxx"
        },
        {
            "checkin_id":"14138",
            "cust_name":"xxx",
            "gender":0,
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ",
            "new_phone_no":"xxxxxxxxxxx",
            "old_phone_no":"xxxxxxxxxxx"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

删除入住人

接口描述

当 PMS 系统有客户删除入住人，则将删除的入住人信息同步至智慧酒店公寓平台。

接口地址

DELETE /v1.0/hotel/pms/checkin/guest

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
data	Object[]	是	入住人的详细信息	BODY

data 数据说明

参数名	类型	必填	描述	参数类型
checkin_id	String	是	客户入住唯一标识	BODY
id_card_no	String	是	用户身份证号码	BODY
id_card_type	String	是	证件类型。 `SFZ`：身份证 `WAIGUOREN`：外国人居留证 `HKMOJUMIN`：港澳台居住证	BODY
phone_no	String	是	用户手机号码	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

DELETE {url}/v1.0/hotel/pms/checkin/guest

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14138",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ",
            "phone_no":"xxxxxxxxxxx"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

新增客房

接口描述

当 PMS 系统有新增房间，则将新增的房间信息同步至智慧酒店公寓平台。

接口地址

POST /v1.0/hotel/pms/rooms

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
rooms	Object[]	是	房间的详细信息列表	BODY

rooms 数据说明

参数名	类型	必填	描述	参数类型
room_no	String	是	房间号码，最大长度为 10 个字符	BODY
floor	String	否	楼层	BODY
building	String	否	楼栋	BODY
room_name	String	是	房间名称	BODY
room_type	String	是	房间房型	BODY
tel	String	是	房间座机	BODY
floor	String	是	楼层	BODY
description	String	否	房间描述	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

POST {url}/v1.0/hotel/pms/rooms

{
    "hotel_code":"800884",
    "rooms":[
        {
            "room_no":"101",
            "room_name":"伦敦",
            "room_type":"精品复式套房",
            "tel":"020-8734124",
            "floor":"5",
            "description":"精品复式套房，满足家庭出游需求"
        },
        {
            "room_no":"102",
            "room_name":"洛杉矶",
            "room_type":"精品总统套房",
            "tel":"020-8734125",
            "floor":"6",
            "description":"精品总统套房，满足高档商务出行"
        },
        {
            "room_no":"103",
            "room_name":"马来西亚",
            "room_type":"精品套房",
            "tel":"020-8734126",
            "floor":"3",
            "description":""
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "success":true,
    "t":1566053034624,
}

删除客房

接口描述

当 PMS 系统有删除房间，则将删除的房间信息同步至智慧酒店公寓平台。

接口地址

DELETE /v2.0/hotel/pms/rooms

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
rooms	Arrays	是	房间列表	BODY

rooms 数据说明

参数名	类型	必填	描述	参数类型
room_no	String	是	房间号码，最大长度为 10 个字符	BODY
floor	String	否	楼层	BODY
building	String	否	楼栋	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

DELETE {url}/v2.0/hotel/pms/rooms

{
    "hotel_code":"800884",
    "rooms": [{"room_no":"101","floor":"1","building":"1"}]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

客房信息全量同步

接口描述

PMS 酒店房间信息的同步，包括新增、编辑、删除房间等操作。若该 PMS 酒店编号存在房间数据，则对比之前房间数据，房间号存在则修改，房间号不存在则新增，旧房间号存在、同步过来的数据不存在则删除。若之前不存在房间数据，则新增房间数据。

接口地址

POST /v1.0/hotel/pms/rooms/sync

请求参数

参数名	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	BODY
rooms	Object[]	是	房间的详细信息列表	BODY

rooms数据说明

参数名	类型	必填	描述	参数类型
room_no	String	是	房间号码，最大长度为 10 个字符	BODY
old_room_no	String	否	旧房间号	BODY
room_name	String	是	房间名称	BODY
room_type	String	是	房间房型	BODY
tel	String	是	房间座机	BODY
floor	String	是	楼层	BODY
description	String	否	房间描述	BODY

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果对象

请求示例

POST /v1.0/hotel/pms/rooms/sync

{
    "hotel_code":"800884",
    "rooms":[
        {
            "room_no":"101",
            "room_name":"伦敦",
            "room_type":"精品复式套房",
            "tel":"020-8734181",
            "floor":"8",
            "description":"精品复式套房，满足家庭出游需求"
        },
        {
            "room_no":"8803",
            "old_room_no":"8802",
            "room_name":"伦敦",
            "room_type":"精品复式套房",
            "tel":"020-8734182",
            "floor":"8",
            "description":"精品复式套房，满足家庭出游需求"
        },
        {
            "room_no":"1011",
            "room_name":"伦敦",
            "room_type":"精品复式套房",
            "tel":"020-8734121",
            "floor":"10",
            "description":"精品复式套房，满足家庭出游需求"
        },
        {
            "room_no":"1012",
            "room_name":"伦敦",
            "room_type":"精品复式套房",
            "tel":"020-8734122",
            "floor":"10",
            "description":"精品复式套房，满足家庭出游需求"
        }
    ]
}

响应成功示例

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

获取人脸照片评分

接口描述

根据人脸照片路径，获取人脸照片分数。

接口地址

GET /v1.0/hotel/pms/face/picture/score

请求参数

请求参数	类型	必填	描述	参数类型
hotel_code	String	是	PMS 厂家旗下门店唯一编码	URL
face_picture_url	String	否	人脸照片 URL 路径	URL
face_picture_id	String	否	人脸照片 ID	URL

faca_picture_url 和 face_picture_id 必传一个。
可选 face_picture_url 和 face_picture_id 两种方式。face_picture_url 是厂家提供人脸照片 URL，face_picture_id 是使用涂鸦文件系统返回的文件 ID。

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Object	结果集

result 参数说明

参数名	类型	说明
score	Integer	照片评分
pass	Boolean	是否通过

请求示例

GET {url}/v1.0/pms/face/picture/score?hotel_code=800884&face_picture_url=http://www.xxx.com/picture.jpeg

响应成功示例

{
    "success":true,
    "result": {
        "score":80,
        "pass":true
    }
    "t":1566053034624,
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

入住机传输人脸图片

接口描述

入住机传输人脸照片路径。

接口地址

POST /v1.0/hotel/pms/face/picture

请求参数

请求参数	类型	必填	描述	参数类型
sn	String	是	入住机唯一编码	BODY
brand_code	String	否	涂鸦提供品牌编码	BODY
checkin_id	String	否	入住单 ID	BODY
face_picture_url	String	是	人脸照片 URL 路径	BODY
phone_no	String	否	手机号	BODY
room_no	String	否	房间号	BODY

face_picture_url 是厂家提供人脸照片 URL, 接入时需要与报备域名等信息

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Boolean	结果集

请求示例

POST {url}/v1.0/hotel/pms/face/picture

{
    "sn": "6F192029B4106EE7",
    "brand_code": "fdddstewqt",
    "checkin_id": "11125533",
    "face_picture_url": "http://test.jpg",
    "phone_no": "86-13544029100",
    "room_no": "101"
}

响应成功示例

{
    "success":true,
    "result":true,
    "t":1566053034624,
}

响应失败示例

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

人员信息推送

接口描述

PMS 系统将人员信息同步至智慧酒店公寓平台。

接口地址

PUT /v1.0/iot-02/pms/customers

请求参数

参数名	类型	参数类型	说明	是否必须
hotel_code	String	BODY	涂鸦提供的唯一标识	是
data	Object[]	BODY	同步的人员列表	是

data 参数说明

参数名	类型	参数类型	说明	是否必须
usename	String	BODY	用户名，商户内唯一，作为更新数据依据	是
cust_name	String	BODY	入住人姓名	是
gender	Integer	BODY	入住人性别。 `0`：女 `1`：男	否
id_card_type	String	BODY	证件类型。`SFZ`：身份证。	否
id_card_no	String	BODY	证件号	否
phone_no	String	BODY	手机号	否
country_code	String	BODY	国家码，如中国为 86	否
address	String	BODY	地址	否
emergency_contact_name	String	BODY	紧急联系人	否
emergency_contact_phone_no	String	BODY	紧急联系电话	否

响应参数

参数名	类型	说明
code	Integer	响应码，成功为空
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	异常信息，成功为空
result	Object	结果集

result 参数说明

参数名	类型	说明
username	String	用户名
customer_id	String	涂鸦分配的用户 ID

请求示例

POST  {url}/v1.0/iot-02/pms/customers

{
    "hotel_code":"xxxxx",
    "data":[
        {
            "usename":"xxxxxxx",
            "cust_name":"xxxxxxx",
            "gender":1,
            "id_card_type":"SFZ",
            "id_card_no":"xxxxxxx",
            "phone_no":"xxxxxxx",
            "country_code":"86",
            "address":"xxxxxxx",
            "emergency_contact_name":"xxxxxxx",
            "emergency_contact_phone_no":"xxxxxxx"
        }
    ]
}

响应成功示例

{
 "success":true,
    "result":[
        {
            "username":"xxx",
            "customer_id":"121212121212"
        }
    ],
    "t":1566053034624
}

响应失败示例

{
 "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

将人员上报给涂鸦后，涂鸦将会为用户分配唯一标识 customer_id，接口调用方可将 customer_id 存储下来，后续接收涂鸦下发的消息时做关联。若返回的 customer_id 为空，表明保存失败。
username 字段可以是手机号、邮箱、学号等，只要在商户系统里能作为用户的唯一标识即可。字符串由数字、字母、中划线、@ 等字符组成，字符长度 5-32 位。

人员信息分页获取

接口描述

PMS 系统从智慧酒店公寓平台分页获取已经同步过的人员信息。

接口地址

GET /v1.0/iot-02/pms/customers

请求参数

参数名	类型	参数类型	说明	必填
hotel_code	String	URL	涂鸦提供门店的唯一标识。	是
page_no	Integer	URL	页码，数值需大于 `0`，默认 `1`。	否
page_size	Integer	URL	页条数。数值范围：0 < `page_size` < 100，默认 20。	否

响应参数

参数名	类型	说明
code	Integer	响应码，成功时为空。详情见错误码章节。
success	Boolean	是否成功。 `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回 13 位时间戳
result	Object	返回结果

result 参数说明

参数名	类型	说明
total	Integer	总条数
page_no	Integer	页码
page_size	Integer	页条数
customers	Array	人员集合

customers 参数说明

参数名	类型	说明
usename	String	用户名，商户内唯一，作为更新数据依据
cust_name	String	入住人姓名
gender	Integer	入住人性别。 `0`：女 `1`：男
id_card_type	String	证件类型。`SFZ`：身份证
id_card_no	String	证件号
phone_no	String	手机号
country_code	String	国家码，如中国为 86
address	String	地址
emergency_contact_name	BODY	紧急联系人
emergency_contact_phone_no	BODY	紧急联系电话

请求示例

GET  {url}/v1.0/iot-02/pms/customers?hotel_code=XXX&page_no=1&page_size=20

响应成功示例

{
    "success":true,
    "result":{
        "total":1,
        "page_no":1,
        "page_size":20,
        "customers":[
            {
                "customer_id":"xxxxxxx",
                "usename":"xxxxxxx",
                "cust_name":"xxxxxxx",
                "gender":"xxxxxxx",
                "id_card_type":"SFZ",
                "id_card_no":"xxxxxxx",
                "phone_no":"xxxxxxx",
                "country_code":"86",
                "address":"xxxxxxx",
                "emergency_contact_name":"xxxxxxx",
                "emergency_contact_phone_no":"xxxxxxx"
            }
        ]
    },
    "t":1566053034624
}

响应失败示例

{
 "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

附录

联调环境

上一篇PMS接入