安美PMS综合业务接口协议规范

安美PMS综合业务接口协议规范

2011年5月

一． 简介

本协议规范的目的是使安美数字客房系统或者宽带计费系统（以下简称AMTT）能够同步地与酒店管理系统（以下简称HOTEL）完成酒店客人的Check-In、Check-Out和换房，对客人上网或者其它业务（比如VOD/打印等）产生计费帐单，并能查询HOTEL方的客人留言和帐单。

AMTT与HOTEL之间采用TCP或串口进行通信，对于采用消息/帐单等双向PMS业务的场合，由于接口数据流量相对较大，尽可能采用TCP通信。

采用TCP通信时，AMTT作为客户方，默认连接HOTEL方的TCP端口5000，端口双方均可。AMTT在同一时刻只能与HOTEL建立一个TCP连接，HOTEL方主动请求Check-In，Check-Out和换房，AMTT主动请求为客人抛送帐单，查询留言和帐单。AMTT尽可能长时间地与HOTEL保持TCP连接，除非发生故障或者进行系统维护，不要主动关闭TCP连接。

若采用串口进行通信，链路规程：默认速率为9600，数据位8，停止位1，无校验位，流控默认为硬件流控，也可视情况采用xon/off或者无流控。

本协议描述部分“<”和“>”间表示必须包含的部分，“[”和“]”间表示可选可不选的部分。

二. 协议描述

2.1 请求包格式规范以及应答处理

1.每个请求都以STX（0x02）开始，ETX（0x03）结束，STX和ETX间为请求消息

内容，ETX后跟一字节校验符，即，MSGBODY

内必须不能包含任何STX或ETX字符。无论串口或者TCP通信，ETX后都需要

跟一字节的LRC校验，产生LRC的具体算法：从STX后的字节开始，到ETX结

束（不包括STX，但是包括ETX）的每字节进行XOR操作，结果即为LRC；

2.任意方接受到请求后，必须回答ACK（0x06）、或者NAK（0x15）、或者ENQ（0x05）；

3.ACK表示被请求方正确接收到了请求，但并不表示已经对该请求作了正确的事务

处理；

4.当发生LRC校验错误时，或者收到ENQ但是2秒内并没有发出过任何请求，被请

求方必须应答NAK；收到NAK的一方，必须重传上一条请求；

5.请求方在收到不正确的非NAK/ACK应答或者在2秒内没有收到任何应答时，必须

发送ENQ，ENQ发送最多重复3次，无任何应答则丢弃本次请求，做详细日志。

ENQ的意义为，向对端请求重发对最近2秒内的最后一条指令所做的ACK／NAK

应答。收到ENQ的一方，若在2秒内没有收到过任何请求，那么直接发送NAK，否则发送上一次ACK/NAK应答；

6.接口的数据交互是全双工的，请求方在等待应答的超时间隔内，可能在未收到

ACK/NAK应答前先收到对方的请求(STX开头)，那么应先处理对方的请求；

7.请求内容的每个字段间以“|”字符作为分隔字符，每个字段内必须不能包含“|”

字符，第一个字段表达该请求的类型，比如是check-in还是check-out，后续的字段

包含该类型请求中必要包含的其它信息，比如房间号，客人姓名等。第一个字段前

可有分隔符，也可没有分隔符，最后一个字段后可跟分隔符，也可不跟分隔符；请

求类型后的各字段间没有特别严格的顺序定义，只要包含了协议规定该请求类型中

必须有的所有字段，不论各字段间顺序如何，均视为合法请求；合法请求中不可识

别的字段作忽略处理，而不是丢弃整个请求；对于非法请求，做静默丢弃处理。2.2 链路建立和拆除流程

链路建立使用LS指令，LS表示Link Start，对于TCP，连接发起方总是AMTT，对于串口，连接发起方可以是任意一方。举例如下：

AMTT发送：LS|DA030611|TI121500|

HOTEL应答

HOTEL发送：LS|DA030611|TI121500|

AMTT应答

链路建立完毕。

链路拆除使用LE指令，LS表示Link End，举例如下：

AMTT发送：LE|DA030611|TI121500|

HOTEL应答

HOTEL发送：LE|DA030611|TI121500|

AMTT应答

任意一方都可以主动发出LE请求。

2.3 Check-In流程

举例：

HOTEL发送：

AMTT应答：

以上表示1108房间John，Check-In。

字段说明：

GI：表示Guest In，客人Check-In请求；

RN：该字段必选,表示Room Number，房号，也是上网的帐号；

G#：该字段可选,表示客人内部号。对于一个客房房多个客人的系统，此字段与GS

字段一同出现。

GS：该字段可选,表示是否出于客房是否出于多客人共用Share状态，值为Y或N 与G#一同出现；

GN：该字段必选,表示Guest Name，客人姓名；

GG：该字段可选,表示客人所属的团队号；

GL：该字段可选,表示Guest Language，客人语种，两英文大写字母表达，可为CN，EA，JP，SP，IT，GE，KO，分别表示中，英/美，日，西，意和韩文。

GV：该字段可选,表示客人的VIP代码,可进行计费策略选择或Portal控制.参数值双方协商.

2.4 换房或客人信息变更流程

换房举例：

HOTEL发送： AMTT应答：

注：G#和GS，意义同GI指令，必须同时出现两个GS，分别表示新旧房间的Share状态，同时GN也必须同时出现两个，分别表示新房间和原房间客人。

以上表示1107房的客人换房到1108。字段依次为：

GC：表示Guest Change，客人换房请求；

RN：表示Room Number，客人要换到的新房间号；

GS：新房间的Share状态；

G#：客人内部号；

RO：表示Room Old，客人原来所在的旧房间号；

GS：原房间的GS状态；

注：客人换房后，上网帐号变为新的房间号。

当GC指令中不存在RO字段时，视为变更信息请求，可以变更GN，GV，GL，GG等信息。举例如下：

HOTEL发送： AMTT应答：

以上将1108房客人的姓名变更为李四，VIP代码变更为2。

2.5 Check-Out流程

举例：

HOTEL发送：

AMTT应答：

以上表示1108房间的客人Check-Out。

GO：表示Guest Out，客人Check-Out请求；

RN：表示Room Number，客人房间号；

GS： Share状态，Y或N；

G#和GS可选，意义同GI指令，若出现G#，那么必须出现GS，表示房间是否处于Share 状态。当客人Check-Out后客房内仍有客人，那么GS为Y，否则为N。

2.6 帐单请求流程

此业务由AMTT发起请求，向HOTEL抛送客人帐单，HOTEL收到帐单后，必须回复帐单的处理结果。

注：此业务是面向房间的，请求中不带有G#字段。

举例：

AMTT发送抛帐请求：

HOTEL应答：

HOTEL发送帐单处理应答：

AMTT确认：

以上表示1108房客人，于2003年1月1日21:10:30产生了12.00元的上网费用，上网时长为1小时25分2秒。

PS：表示Posting，抛帐请求；

RN：表示Room Number，房间号；

TA：表示Total Amount，本帐单计费金额，单位为分；

DA：表示DATE，帐单产生日期，YYMMDD格式；

TI：表示TIME，帐单产生时间，HHMMSS格式；

DU：表示Duration，上网时长，格式为HHMMSS，即时、分、秒，各占两位，<10前补0；特别的，当小时数当小时数>100，按实际数字填写；

P#：表示本帐单流水号，必须为数字，最长四位，用于帐单请求和处理应答的流水号匹配；

PC：表示Post Code，业务代码，字段值为1个字符，AMTT和HOTEL双方可协商定制，为每一种业务定制一个业务代码，比如宽带为2，VOD为3，MiniBar为4等； PT：表示Posting Type，抛帐类别，默认为C直接Charge，此时必须有TA字段；当为M表示迷你吧消费单，此时没有TA字段，但是必须有MA和M#字段，费用由HOTEL 方计出；

MA：表示Minibar Article，MiniBar商品类别，当PT为M时必选；

M#：表示Minibar商品数量，当PT为M时必选；

帐单处理结果的相关字段

PA：表示Posting Answer，帐单应答；

RN：表示Room Number，房间号；

AS：表示Answer Status，应答状态，若帐单请求处理成功，后必须跟OK，否则跟其它字符串，说明失败原因；

P#：表示本帐单流水号，必须为数字，最长四位，必须与PS请求中的P#值匹配；

迷你吧的抛帐例子：

AMTT发送抛帐请求：

HOTEL应答：

HOTEL发送帐单处理应答：

AMTT确认：

注：一个帐单请求事务中双方的P#字段内容必须匹配。AMTT的帐单流水号不断增长，若流水号>10000，则取后四位，所以相当长长时间内帐单的流水号是不会重复的。当需要重发帐单时，帐单请求的每一部分，包括P#，DA和TI字段都必须保持不变。

2.7 夜审流程

酒店管理系统可能需要在凌晨的时候做夜审。在夜审期间，如果酒店管理系统不能接受和缓存AMTT发送过去的帐单，可以发送夜审信号通知AMTT，由AMTT来缓存帐单，等夜审结束的时候再把夜审期间缓存的帐单发送给酒店管理系统。如果AMTT在夜审结束信号之前收到酒店管理系统发过来的GI或GC信号，会认为夜审已经结束，开始正常抛帐。

2.7.1 夜审开始：

举例：

HOTEL发送：

AMTT应答：

以上表示酒店管理系统在2006年6月7日01:01:00通知AMTT：HOTEL夜审开始

NS：表示Night Audit Start，夜审开始；

DA：表示DATE，夜审开始日期，YYMMDD格式；

TI：表示TIME，夜审开始时间，HHMMSS格式；

2.7.1 夜审结束：

举例：

HOTEL发送：

AMTT应答：

以上表示酒店管理系统在2006年6月7日02:09:30的时候通知AMTT：HOTLE夜审结束。

NE：表示Night Audit End，夜审结束；

DA：表示DATE，夜审结束日期，YYMMDD格式；

TI：表示TIME，夜审结束时间，HHMMSS格式；

2.8 留言业务流程

消息留言有两种模式，一种是实时模式，另外一种是主动查询的模式；

客人可以实时看到消息留言，也可以查询其他人给自己的留言，并可以删除留言。

采用实时模式，一旦客人有留言，HOTEL 就主动发送此客人的XL 消息指令，建议在与AMTT ISTV 对接时采用此方式。注意此模式下仍允许AMTT 发送XM 指令主动查询。

注：此业务是面向客人的，必须有G#字段。支持此业务时，相关的GI/GO/GC也必须带有G#信息。

1、HOTEL 实时发送留言的例子：（Opera系统支持该模式功能）

HOTEL 发送实时留言序列：

XL|RN1108|G#10335|MI903|MT This is a text messagefrom room 1108

for test|DA001031|TI124753|[LRC]

AMTT 应答

XL指令内各字段意义完全同XT。

XT/XL的相关字段解释如下：

RN：必选，表示Room Number，房间号；

G#：必选，客人内部ID号；

MI：必选，表示Message ID，消息ID；

MT：必选，表示Message Text，消息文本，可以包含换行字符，文本必须以0xff结束；

DA：必选，表示DATE，消息日期，YYMMDD格式；

TI：必选，表示TIME，消息时间，HHMMSS格式；

2、查询留言例子：

AMTT发送：XM|RN1108|G#103355

HOTEL应答

HOTEL发送留言序列：

XT|RN1108|G#10335|MI903|MT This is a text messagefrom room 1108 for test|DA001031|TI124753|[LRC]

AMTT应答

XT的相关字段解释如下：

MI：表示Message ID，消息ID；

MT：表示Message Text，消息文本，可以包含换行字符，文本必须以0xff 结束；

当没有留言存在，HOTEL应答ACK后不需要再发送任何信息，若存在留言，留言序列可以多于一条XT指令。

3、删除留言例子：

AMTT发送：XD|RN1108|G#10335|MI903|

HOTEL应答

2.9 帐单查询流程

客人可通过此业务查询自己的消费帐单。对于一些酒店不想公开给客人的帐单，酒店方可以选择不传送，或者传送时加禁止显示的标记。

注：此业务是面向客人的，必须有G#字段。支持此业务时，相关的GI/GO/GC也必须带有G#信息。

帐单查询例子，以下忽略指令中的，忽略链路层的：

AMTT发送帐单查询请求，XR表示Bill Request：

XR|RN1108|G#10335|

HOTEL应答帐单序列，包含3条XI帐单应答，和一个XB总计应答：

XI|RN1108|G#10335|DC327|BI350|BD Telephone|DA001031|TI124753|FD Y|

XI|RN1108|G#10335|DC400|BI2500|BD Lobby Bar|DA001031|TI1843000|FD Y|

XI|RN1108|G#10335|DC100|BI11000|BD Room&Tax|DA001101|TI031000|FD N|

XB|RN1108|G#10335|BA13850|DA001101|TI071500|

帐单的相关字段解释如下：

BI表示Bill值，单位为分；

BD表示Bill Description，帐单描述；

FD表示是否该条帐单允许显示给客人，字段值为Y或者N，对于FD值为N的帐单，AMTT不会将帐单内容显示给客人；

DA和TI表示帐单产生时间。

总计的相关字段解释如下：

BA表示Balance Amount，总计帐单金额，单位为分。

当没有任何帐单，HOTEL只返回一条XB指令。

2.10房态同步流程

酒店管理人员可通过此业务进行所有房间状态的同步操作，仅限与对房间的CheckIn、Checkout的状态同步。

房态同步例子，以下忽略指令中的，忽略链路层的：

AMTT发送房态同步请求，DR表示房态同步命令请求；

DR|DA001005|TI125045|

DA和TI表示房态同步的时间；

HOTEL应答房态数据序列，DS表示房态同步数据开始，房态数据（GI、GO），DE表示房态同步数据结束。

DS|DA001005|TI125047|

GI|RN1001|G#12345|GS N|

GO|RN1002|GS N|

GI|RN1003|G#12002|GS N|

GO|RN1004|GS N|

GI|RN1005|G#12234|GS N|

DE|DA001005|TI1252001|

其中，GI的信息是房间中实际入住的客人信息，GO信息中没有G#，因为房间是空的。

2.11HOTEL打开或关闭VOD点播权限

HOTEL可以在信息管理系统（PMS）中，手动打开或关闭VOD功能。

当HOTEL系统手动修改NO POSTING 状态为“TV ON”时，HOTEL会发出如下指令给AMTT（RE|RN1006|TVTU| ）

当HOTEL系统手动修改NO POSTING 状态为“TV OFF”时，HOTEL会发出如下指令给AMTT（RE|RN1006|TVTN| ）