同佳智慧酒店

操作流程

1. 账号注册、项目创建；

   在开始接入PMS服务之前，您需要先完成账号注册、项目创建流程，详情请参考：酒店项目创建

   说明 

   酒店平台认证

   认证地址：https://www.aligenie.com/account/approve

   注意：PMS对接用户请选择“企业认证”方式，按界面提示完成信息填写和认证;

2. 酒店平台新建应用获取密钥

   PMS厂商接入猫精酒店平台，需要创建自己对应的酒店应用，实现云云对接服务端链路。

   进入酒店项目详情后，点击设置里面应用管理中新建应用按钮；

   

   点击新建应用按钮后；

   

   输入应用名称和描述后，自动获得平台应用key相关信息；

   

   说明 

   注：此处为后续云云对接密钥，注意保密。

3. 收集对应的信息提供给酒店支持同学

   PMS服务商名称	XXX（PMS服务商）
   商标	推荐图片大小：800*800
   调用url	合作方提供uri
   应用名称	控制台上创建的应用名称

   说明 

   注：需要PMS厂商提供URL消息接收地址，小二在后台录入。业主在前台开通授权后，猫精往这个地址推送消息，如下图：

   

4. 线下对接，同步应用名，完成平台之间鉴权用户酒店平台一键开启PMS服务

   完成应用创建后，线下进行技术对接，同步应用名完成猫精与PMS合作伙伴平台之间的鉴权。

   用户直接选择服务商完成授权，授权后，猫精发一条消息给PMS厂商，猫精给过去的消息包含hotelID等，完成酒店账号创建或关联。

   

联调测试

正式联调测试前，需要先进行商务对接，两边确定合作后进入到联调测试环节；

技术对接

1. 酒店业主一键开启pms服务，天猫精灵给pms发送通知消息；post请求地址：合作方提供的uri;发送消息格式如下：

   request:
   {
     "pmsBaseInfo": {
       "appName": "xxxx",
       "authType": "MD5",
       "hotelId": "b3e8a63****af8904b3cdb4",
       "requestId": "871d6117f8****8f4d44f3b3",
       "requestTime": 1690270270928,
       "token": "c6f7c5774****2059fbab170"
     },
     "type": 0, //0-20； 0表示开通授权的,给pms厂商推送一个消息，消息内容为payload的message字段
     "payload": {
       "message": "测试酒店已开通旅智PMS服务，请做好线下服务对接"
     }
   }

   response:
   {
     "statusCode": 200,    //状态code 200 表示成功
     "message": "success", // 成功 success;失败，返回具体原因
     "data": "",
     "success": true
   }

   public static String sign(String text, String key, String input_charset) {
       text = text + key;
       return DigestUtils.md5Hex(getContentBytes(text, input_charset));
   }
   
   
   private static byte[] getContentBytes(String content, String charset) {
         if (charset == null || "".equals(charset)) {
             return content.getBytes();
         }
         try {
             return content.getBytes(charset);
         } catch (UnsupportedEncodingException e) {
             throw new RuntimeException("MD5签名过程中出现错误,指定的编码集不对,您目前指定的编码集是:" + charset);
         }
   }

   注释：

   key : appKey (控制台上：应用名称对应的应用密钥appKey)

   text ：{$appName}|{$hotelId}|{$requestId}|{$requestTime}

   input_charset : UTF-8

   token = sign(text,key,input_charset);

   返回值：

   {
    "statusCode":200,   //状态code 200 表示成功
    "message":"success",  // 失败，返回具体原因
    "data" :"",
    "success":true 
   }

2. PMS事件上报接口说明

   • PMS合作伙伴同步事件给猫精云接口（AliGenie Open API ： API接口；

   • payload内容说明：

     属性名	子属性		属性类型	是否必填	属性描述
     eventId	无		String	是	事件id（合作方自己填写）
     eventType			Integer	是	0：预定 1：直接入住 2: 结账退房 3: 预定转入住 4: 未结账退房 5：续房 6：取消订单 7：换房 9: 取消入住 10：添加同住人 11：删除同住人 12：更新入住人信息 13：退房恢复
     hotelId			String	是	酒店项目id
     pmsPartnerName			String	是	pms合作商名
     orderItemList [OrderItem]	orderItemId		String	否	订单id（可选）
     	channelName		String	否	预定渠道
     	checkinTime		Date	否	入驻时间
     	checkoutTime		Date	否	退房时间
     	guests[GuestInfoDTO]	name	String	是	客户名字
     		familyName	String	否	姓氏
     		phone	String	和telephone二选一	手机号
     		email	String	否	邮箱
     		telephone	String	和telephone二选一	座机号
     		gender	Integer	是	性别 0：女 1：男 -1：未知
     		identityType	String	是	身份类型
     		identityNo	String	是	身份号码
     	price		Double	否	订单价格
     	lastRoomNo		String	否	上一个房间号
     	roomNo		String	否	当前房间号
     	roomTypeCode		Integer	否	房型码 ：11001
     	roomTypeName		String	否	房型名：大床房、标准间等等
     	status		Integer	是（子订单维度状态）	0：预定 1：入驻 2：结账退房 4: 不结账退房 6: 订单取消 8：客户未到 9: 取消入驻

   • payload的请求实例：

     {
       "eventId": "123342",
       "eventType": 2,
       "hotelId": "95fc******4f7b",
       "pmsPartnerName": "XX科技",
       "orderItemList": [
         {
           "orderItemId": "12345",
           "channelName": "飞猪",
           "checkinTime": "2023-04-15 12:03:20",
           "checkoutTime": "2023-04-16 11:12:04",
           "guests": [
             {
               "name": "张*",
               "familyName": "张",
               "phone": "187***0967",
               "email": "****@qq.com",
               "telephone": "0571-433**343",
               "gender": 1,
               "identityType": "idCard",
               "identityNo": "330**********3538"
             }
           ],
           "price": "318",
           "lastRoomNo": "119",
           "roomNo": "210",
           "roomTypeCode": "1023",
           "roomTypeName": "大床房",
           "status": 2
         }
       ]
     }

   • 返回值：

     请求成功：

     {
       "StatusCode": 200,//状态code 200 表示成功
       "Result": true// 失败，返回具体原因
     }

   • 鉴权不通过：

     {
       "RequestId": "DB689742-ED7A-715E-B0FF-58D539EC0204",
       "Message": "查询凭证失败",
       "Recommend": "https://api.aliyun.com/troubleshoot?q=AuthenticationFailed.NotFound&product=AliGenie&requestId=DB689742-ED7A-715E-B0FF-58D539EC0204",
       "HostId": "aligenie-open-inner.aliyuncs.com",
       "Code": "AuthenticationFailed.NotFound"
     }

   • 参数内容错误：

     {
       "RequestId": "5BEA7234-4002-7874-9C98-01EFDB4621C8",
       "HostId": "aligenie-open-inner.aliyuncs.com",
       "Code": "InvalidParameter",
       "Message": "The request parameter is invalid",
       "Recommend": "https://api.aliyun.com/troubleshoot?q=InvalidParameter&product=AliGenie&requestId=5BEA7234-4002-7874-9C98-01EFDB4621C8"
     }

   • 接口测试

     接口白屏测试地址：API接口；

     

   • 协议说明

     参数名	参数类型	参数描述
     accessKeyId	String	控制台上：客户提供的应用名对应的accessKeyId，鉴权使用；
     accessKeySecret	String	控制台上：客户提供的应用名对应的accessKeySecret，鉴权使用；
     payload	String	pms上报的事件内容