技术专区为您提供行业知识、功能解释、设置常见问题
国威HB3000酒店管理对接文档-接口协议说明V3.1
国威HB3000-IPPBX酒店管理系统 接口协议说明V3.1
目 录
1 引言 5
1.1 编写目的 5
1.2 预期的读者和阅读建议 5
2 术语、定义和缩略语 5
3 组网环境示意图 6
4 消息传输方式 6
5 IPPBX与话务台间消息定义 6
5.1 登录 6
5.2 登出 8
5.3 心跳 9
6 详细功能 10
6.1 分机拨号权限 10
6.2 分机姓名 11
6.3 分机免打扰 12
6.4 分机叫醒设置 14
6.5 话单 15
6.6 当前用户呼入话务台 16
6.7 分机状态 17
6.8 酒店语音留言信箱.........................................................................................................18
1 引言
1.1 编写目的
本文规范了酒管系统与国威IPPBX之间的消息通信。
1.2 预期的读者和阅读建议
本文预期的读者和阅读建议见表1.1。
表1.1 本文预期的读者
读者分类 阅读重点 备注
系统工程师（负责软件需求开发） 协作说明
系统工程师（负责同层次相关系统的概要设计） 设计原理
系统工程师（负责构件的概要设计） 构架说明、协作说明、构件说明、接口说明 <当某构件还是子系统时，后续还要继续概要设计时，才有这类读者>
软件工程师（负责构件的详细设计） 构架说明、协作说明、构件说明、接口说明 <当某构件已经是?？槭?，后续就开始详细设计时，才有这类读者>
测试工程师 构架说明、协作说明、接口说明
2 术语、定义和缩略语
本文件应用了以下缩略语：
IMS：IP Multimedia Subsystem IP多媒体系统
NGN：Next Generation Network 下一代网络
PSTN：Public Switched Telephone Network 公共交换电话网络
国威IPPBX：话务台：IPPBX控制台，一般为话务台软件，酒管系统或者计费软件
3 酒店环境示意图
国威HB3000酒店管理对接文档-接口协议说明V3.1
4 消息传输方式
国威IPPBX HB3000与计费系统采用TCP方式通信，端口号64888，服务端为国威IPPBX，客户端为计费系统，之间的消息采用文本方式传输，采用一种简单的"key: value"协议用于已连接的管理客户端和IPPBX之间的信息传递。数据流格式为key: value，由\r\n分隔，空行（连续两个\r\n）代表结束。注意：字符串区分大小写，key与value之间除了有字符“：”外，“：”后还有一个空格，还有\r值为0x0d，\n值为0x0a 。所有涉及中文的配置都转换成utf8格式后发送。
5 IPPBX与话务台间消息定义
5.1 登录
1）PMS ?国威IPPBX:
ServiceType: PMS
Action: UserLogin
SeqID: xxxxx
CallMethod: Account
User: xxxx ----登录账号
Password: xxxx
注：系统***次连接时需要发送登录验证消息，默认账号和密码需要IPPBX管理员分配。
2）国威IPPBX ? PMS，确认消息
ServiceType: PMS
Action: UserLogin
SeqID: xxxxx
Response: Success -----Success: 成功
CallMethod: Account
User: xxxx ----登录账号
ServiceType: PMS
Action: UserLogin
SeqID: xxxxx
Response: Error ----- Error: 失败
CallMethod: Account
Message: xxxx ----- 失败原因
3）Demo
ServiceType: PMS \r\n
Action: UserLogin\r\n
SeqID: 123456\r\n
CallMethod: Account\r\n
User: admin\r\n
Password: admin\r\n\r\n
ServiceType: PMS \r\n
Action: UserLogin\r\n
SeqID: 123456\r\n
Response: Success\r\n
CallMethod: Account\r\n
User: admin\r\n
Password: admin\r\n\r\n
ServiceType: PMS \r\n
Action: UserLogin\r\n
SeqID: 123456\r\n
Response: Error\r\n
CallMethod: Account\r\n
Message: User Login failed, Password Wrong ! \r\n\r\n
5.2 登出
1）PMS ?国威IPPBX:
ServiceType: PMS
Action: UserLogout
SeqID: xxxxx
CallMethod: Account
User: xxxx ----登出账号
Password: xxxx
2）国威HB3000 IPPBX ? PMS，确认消息
ServiceType: PMS
Action: UserLogout
SeqID: xxxxx
CallMethod: Account
Response: Success -----Success: 成功
User: xxxx ----登出账号
ServiceType: PMS
Action: UserLogout
SeqID: xxxxx
CallMethod: Account
Response: Error ----- Error: 失败
CallMethod: Account
Message: xxxx ----- 失败原因
5.3 心跳
心跳用于监测前台与后台的联机情况，前台发送频率以5秒一次，后台收到后立即返回应答，当前台发送3次均无返回时认为断线。
1）PMS ? 国威IPPBX:
ServiceType: PMS
Action: UserLogin
SeqID: xxxxx
CallMethod: HeartBeat
User: xxxx ----账号
2）国威IPPBX? PMS，确认消息
ServiceType: PMS
Action: UserLogin
SeqID: xxxxx
CallMethod: HeartBeat
User: xxxx ----账号
Response: Success -----Success: 成功
3）Demo
ServiceType: PMS \r\n
Action: UserLogin\r\n
SeqID: 123456\r\n
CallMethod: HeartBeat\r\n\r\n
User: xxxx ----账号
ServiceType: PMS \r\n
Action: UserLogin\r\n
SeqID: 123456\r\n
CallMethod: HeartBeat\r\n
User: xxxx ----账号
Response: Success\r\n\r\n
6 详细功能
6.1 分机拨号权限
1）PMS ? 国威IPPBX:
ServiceType: PMS
Action: Set
SeqID: xxxxx
CallMethod: ExtenLimit
Phone: xxxx
Limit: x -----1-设备内部，2-企业内部，3-市话，4-国内长途，5-国际长途
2）国威HB3000 IPPBX? PMS
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Success -----Success: 成功
CallMethod: ExtenLimit
Phone: xxxx
Limit: x -----1-设备内部，2-企业内部，3-市话，4-国内长途，5-国际长途
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Error ----- Error: 失败
CallMethod: ExtenLimit
Phone: xxxx
Message: xxxx ----- 失败原因
3）Demo
ServiceType: PMS\r\n
Action: Set\r\n
SeqID: 123456\r\n
CallMethod: ExtenLimit\r\n
Phone: 8001\r\n
Limit: 4\r\n\r\n -----国内长途
6.2 分机姓名
1）PMS ? 国威IPPBX:
ServiceType: PMS
Action: Set
SeqID: xxxxx
CallMethod: ExtenName
Phone: xxxx ----分机
Name: xxxx -----分机姓名
2）国威IPPBX? PMS
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Success -----Success: 成功
CallMethod: ExtenName
Phone: xxxx ----分机
Name: xxxx -----分机姓名
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Error ----- Error: 失败
CallMethod: ExtenName
Phone: xxxx ----分机
Name: xxxx -----分机姓名
Message: xxxx ----- 失败原因
3）Demo
ServiceType: PMS\r\n
Action: Set\r\n
SeqID: 123456\r\n
CallMethod: ExtenName\r\n
Phone: 8001\r\n\r\n
Name: 国威\r\n\r\n ----国威转换成utf8格式编码发送
6.3 分机免打扰
1）PMS ?国威IPPBX:
ServiceType: PMS
Action: Set
SeqID: xxxxx
CallMethod: ExtenDND ---- Do Not Disturb
Phone: xxxx
Use: x -----0-取消，1-设置
Start: xxxx-xx-xx xx:xx:xx ---开始时间
End: xxxx-xx-xx xx:xx:xx ----结束时间
注：Start和End字段只有当Use为1时下发，取消不需要这两个字段
2）国威HB3000 IPPBX? PMS
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Success -----Success: 成功
CallMethod: ExtenDND ---- Do Not Disturb
Phone: xxxx
Use: x -----0-取消，1-设置
Start: xxxx-xx-xx xx:xx:xx ---开始时间
End: xxxx-xx-xx xx:xx:xx ----结束时间
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Error ----- Error: 失败
CallMethod: ExtenDND ---- Do Not Disturb
Phone: xxxx
Use: x -----0-取消，1-设置
Start: xxxx-xx-xx xx:xx:xx ---开始时间
End: xxxx-xx-xx xx:xx:xx ----结束时间
Message: xxxx ----- 失败原因
3）Demo
ServiceType: PMS \r\n
Action: Set\r\n
SeqID: 123456\r\n
CallMethod: ExtenDND\r\n
Phone: 8001\r\n
Use: 1\r\n -----启用免打扰
Start: 2012-03-08 07:30:00\r\n ---开始时间
End: 2012-03-08 15:30:00\r\n\r\n ----结束时间
6.4 分机叫醒设置
1）PMS ? 国威IPPBX:
ServiceType: PMS
Action: Set
SeqID: xxxxx
CallMethod: AlarmClock
Phone: xxxx
AlarmClock: start*end*frequency*days*file*num&start*end*frequency*days*file*num&…&
叫醒格式：
start: hh:mm ---叫醒开始时间, 未设置则为空
end: hh:mm ---叫醒结束时间, 未设置则为空，该字段后台已弃用，消息格式保留
frequency: x ---叫醒振铃频率, 单位分钟，***小值5，默认为5
days: x ---叫醒持续天数, 单位天
file: xxxx.ulaw ---叫醒播放文件，后缀名为.gsm、.ulaw、.alaw，默认fpm-world-mix.gsm
num: x ---叫醒次数，***小为1次，***值10次，默认3次
注意：AlarmClock:***必须以&结束或者字段为空，团队叫醒：设置在同一时间叫醒服务组，交换机对组内的客房进行批量自动叫醒，批量叫醒间隔为1-2秒。
2）Demo
ServiceType: PMS\r\n
Action: Set\r\n
SeqID: 123456\r\n
CallMethod: AlarmClock\r\n
Phone: 8001\r\n
AlarmClock: 07:30**5*1*fpm-world-mix.gsm*1&17:30**5*1*fpm-world-mix.gsm*3&\r\n\r\n
两个叫醒策略：
1)07:30叫醒, 每5分钟响铃一次，系统默认响5次，叫醒提示音为fpm-world-mix.gsm，叫醒次数1次。
2)17:30叫醒, 每5分钟响铃一次，系统默认响5次，叫醒提示音为fpm-world-mix.gsm，叫醒次数3次。
注意：end字段不设置也要填空。
3）国威HB3000 IPPBX? PMS
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Success -----Success: 成功
CallMethod: AlarmClock
Phone: xxxx
AlarmClock: start*end*frequency*days*file*num &start*end*frequency*days*file*num &…&
ServiceType: PMS
Action: Set
SeqID: xxxxx
Response: Error ----- Error: 失败
Phone: xxxx
CallMethod: AlarmClock
Message: xxxx ----- 失败原因
6.5 话单
1）国威IPPBX? PMS
ServiceType: BILLING
Action: CallControl
SeqID: xxxxx
CallMethod: CDR
Caller: xxxx --- 主叫号码
Callee: yyyy --- 被叫号码
Start: xxxx-xx-xx xx:xx:xx --- 呼叫开始时间
Answer: xxxx-xx-xx xx:xx:xx --- 应答时间
End: xxxx-xx-xx xx:xx:xx --- 通话结束时间
Dur: xx --- 通话时长，单位秒
Disposition: xxx ---呼叫状态，NO ANSWER，ANSWERED，FAILED，BUSY，CONGESTION
Call_type: xxx --- 呼叫类型，common_device-设备内部，internal-企业内部，local-市话，longdistance-国内长途， international-国际长途
2）Demo
ServiceType: BILLING
Action: CallControl
SeqID: 1
CallMethod: CDR
Caller: 1001
Callee: 93801
Start: 2018-01-05 16:46:59
Answer: 2018-01-05 16:47:03
End: 2018-01-05 16:47:13
Dur: 10
Disposition: ANSWERED
Call_type: local
6.6 当前用户呼入话务台
1）IPPBX? PMS:
ServiceType: PMS
Action: CallControl
SeqID: xxxxx
CallMethod: CallIn
Caller: aaaa -----aaaa 为主叫号码
Callee: bbbb -----bbbb 为被叫号码
注释：只发给对应客户端
6.7 分机状态
1）IPPBX? PMS:
ServiceType: PMS
Action: CallControl
SeqID: xxxxx
CallMethod: ExtenStatus
Exten: xxxx ---- 分机号码
ChannelId: xxxx ---- 分机通道ID
Status: x ---- 分机状态
Peer: xxxx ---- 对端号码
PeerId: xxxx --- 对端通道ID
注：1）Status 值：0-不在线，1-保留，2-取机，3-拨号，4-主叫回铃音，5-振铃，6-通话，
7-忙，8-取机拨号中，9-呼入，10-叫醒闹铃，65536-静音
界面处理：4、5 作为振铃显示，6 作为通话，0、1 作为空闲，其余作为忙处理
2）由于状态很多Peer、PeerId、DialNum 等字段可能为空
3）当Status=4 时，Exten 为主叫号码，Peer 为呼出号码
当Status=5 时，Exten 为被叫号码，Peer 为主叫号码
当Status=6 时，通过calltalk 消息来显示通话对端号码
注释：发给所有在线客户端
6.8 酒店语音留言信箱
1）IPPBX? PMS:
ServiceType: PMS
Action: CallControl
SeqID: xxxxx
CallMethod: ExtenStatus
Exten: xxxx ---- 分机号码
ChannelId: xxxx ---- 分机通道ID
Status: x ---- 分机状态
Peer: xxxx ---- 对端号码
PeerId: xxxx --- 对端通道ID
备注：语音留言信箱留言并发为400.
6.9 串口转发方式：
1.要设置为串口转发及等级设定模式，进入“参数设置”->“通 讯”->“转发话单”，设置成“转 发”给COM口。
话单转发及等级设定的串口不能和话务台与主机的通信串口冲突，否则转发无效。例如:若话务台与主机的通信串口为com1，则话单转发的串口可以为com2，接收的com口要和com2做连接?。?！
2.话单格式
T始话_主叫 被叫 结束时间 时长 费率 话费 中继 结束符 结束 (回车换行)采用ASCII码，每条话单以T打头，以D结束符或回车换行(0D 0A)结尾
例如
T8001,13820819228,2011-08-0415:37:36,11,0.20,0.80,1,0,D
话单开头是：T
主叫：4位（8001） 宽度:4
被叫：13820819228 宽度:21
结束时间：2011-08-04 15:37:36 宽度:21
时长：11秒 宽度:6
费率：0.20元 宽度:6
话费：0.80元 宽度:6
中继：1 宽度:2
账号：0 宽度:2
结束符：D
结束：回车换行
3.通信协议
波特率 1200, 无校验位, 数据位 8, 停止位 2
文件保存方式：
1.要设置话单保存为文件的模式，进入“参数设置”->“通讯”->选中“保存话单到文件”项，转出的话单到安装目录文本文件hd.txt
2.话单格式
始话 主叫 被叫 结束时间 时长 费率 话费 中继 (0D 0A回车换行)
例如
T8001,13820819228,2011-08-0415:37:36,11,0.20,0.80,1,0,D
话单开头是：T
主叫：4位（8001） 宽度:4
被叫：13820819228 宽度:21
结束时间：2011-08-04 15:37:36 宽度:21
时长：11秒 宽度:6
费率：0.20元 宽度:6
话费：0.80元 宽度:6
中继：1 宽度:2
账号：0 宽度:2
结束符：D
结束：回车换行
等级控制：
现在在软件的安装目录下建立个记事本文档名称：Grade
Grade：分机号码/0（只能内部通话）
分机号码/1（只能打市话）
分机号码/2（只能打国内长途）
分机号码/3（无限制）
返回指令：分机号码/OK
叫醒控制：
现在在软件的安装目录下建立个记事本文档名称：Clock
Clock：分机号码/，03-06，18:30:00(月份和时间)
返回指令：分机号码/，03-06，18:30:00(月份和时间)OK
点击右上角
分享给朋友吧
长按图片保存/分享
Call us
总机: 020-85261379
销售/售后: 18144823824（微信同号）
Address
工厂：中国·广东省·深圳市龙岗区坪地盛佳道2号
售后/维修：中国·广东省·广州市天河区广州大道北991号
ws824@82416.com
华北
——
北京 天津 济南 青岛 太原 长治 石家庄
电话/邮箱：beijing@82416.com
东北
——
哈尔滨 长春 沈阳 大连 大庆 呼和浩特
电话/邮箱：haerbin@82416.com
华东
——
上海 杭州 南京 苏州 温州 宁波 常州 无锡
电话/邮箱：shanghai@82416.com
西北
——
银川 兰州 西宁 乌鲁木齐 石嘴山 克拉玛依
电话/邮箱：lanzhou@82416.com
华南
——
- 广州 深圳 ?？?三亚 福州 厦门 南昌 赣州
- 电话/邮箱：guangzhou@82416.com
西南
——
重庆 贵阳 成都 南宁 昆明 遵义 柳州 桂林
电话/邮箱：chongqing@82416.com
华中
——
长沙 岳阳 武汉 孝感 西安 咸阳 郑州 合肥
电话/邮箱：wuhan@82416.com
珠三角
————
珠海 东莞 佛山 汕头 惠州 中山 湛江 阳江
电话/邮箱：shenzhen@82416.com
Copyright © 广州普国贸易有限公司 国威程控电话交换机 All Rights Reserved 粤ICP备17026317号 公安备案号:44010602002433
点击右上角
分享给朋友吧
QQ在线
