中国联通G网智能网与VAC实时扣费接口规范.doc

i 中国联通公司企业标准 QB/CU xxx_xxxx G 网智能网与 VAC 实时扣费接口规范 （V 1.1） 2008-10-24 发布2008-10-24 实施 中国联通公司 发布 i 目 次 目 次.I 修改记录.I 前 言.1 G 网智能网与 VAC 实时扣费接口规范（V1.1）.2 1范围.2 2引用标准.2 3缩略语.2 4VAC 实时计费系统组网.3 5基于 TCP/IP 的协议.3 5.1通信方式.3 5.2通信初始化.4 5.3通信过程.4 5.4通信结束.4 5.5网络故障.4 5.6接收到非法命令或应答.4 5.7序列号定义.5 5.8序列号重复.5 6VAC 与 SCP 通信使用的实时接口协议 .6 6.1批价请求.6 6.1.1描述.6 6.1.1.1批价请求消息参数(SM_ACC) .6 6.1.1.2批价请求响应消息参数(SM_ACC_RESP) .8 6.1.1.3错误处理.8 ii 6.2结果通知.9 6.2.1描述.9 6.2.1.1结果通知消息参数（SM_FM）.9 6.2.1.2结果通知响应消息参数（SM_FM_REP） .9 6.2.1.3错误处理.10 7通信协议.10 7.1VAC 与 SCP 之间的消息.10 7.2消息定义.10 7.2.1数据类型.11 7.2.2消息头的格式.11 7.2.3消息体的格式.11 7.2.3.1BIND 消息 .11 7.2.3.2BIND_RESP 消息 .12 7.2.3.3UNBIND 消息 .12 7.2.3.4UNBIND_RESP 消息.12 7.3命令标志数值定义.12 7.4错误码定义.13 附录 A SOCKET 连接.15 i 修改记录 文件编号版本号 拟制人/ 修改人 拟制/修改日期更改理由 主要更改内容 （写要点即可） 封面V1.12008-12-18版本号修改从 1.0 改为 1.1 6.1.1.12008-12-18修改小节格式 7.2.32008-12-18修改小节格式 7.2.32008-12-18笔误修改 MMSC 为 VAC 6.1.1.1 2009-6-19SPNumber 字段说明改为“和话 单一致，产品接入号，该字段 不能为空。如果没有接入号， 则填 000000000000” 6.2.1.3 错 误处理 2009-6-19补充细化目录和处理机制 6.1.1 描述2009-6-19增加“当 SCP 判断当月包月费 已扣除、但 VAC 又发起包月费 扣除请求时，SCP 完成每月包 月费多次扣除的剔重。 ” 2009-7-16FeeType 取值 2 增加说明“对包 周期类型计费，仍填 2” 6.1.1.1批价请求消 息参数(SM_ACC) 注 1：每次更改归档文件时，需填写此表。 注 2：文件第一次归档时， “更改理由” 、 “主要更改内容”栏写“无” 。 1 前 言 本接口规范主要对中国联通增值业务鉴权中心接口规范 VAC与SCP的实时扣费接口方面 进行了规定。 本标准由中国联通公司增值业务部提出。 本标准由中国联通公司技术部归口。 本标准负责起草单位：中讯邮电咨询设计院，中国联通公司增值业务部 本标准主要起草人： 本标准的修改和解释权属中国联通公司。 2 G 网智能网与 VAC 实时扣费接口规范（V1.1） 1范围范围 本接口规范主要对中国联通增值业务鉴权中心接口规范 VAC与SCP的实时扣费接口 方面进行了规定。 2引用标准引用标准 下列文件中的条款通过本标准的引用而成为本标准的条款。凡是注日期的引用文件， 其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本标准，然而，鼓励根据 本标准达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件， 其最新版本适用于本标准。 中国联通预付费用户联通在信短消息实时计费实现技术规范 V1.2 短消息业务联网协议 1.2 版 短消息业务联网规范 1.2 版 SMPPV3.3 国际规范 SMPPV3.4 国际规范 3缩略语缩略语 VACValue-added service Authentication Center 增值业务鉴权中心 MOMobile Original移动用户发送短消息 MTMobile Terminal移动用户接收短消息 PPSPre-Paid Service预付费 SCPService Control Point业务控制点 SGIPShort message Gateway Interface Protocol短消息网关接口协议 SGIP+Short message Gateway Interface Protocol plus联通在信扣费协议 SMPPShort Message Peer to Peer短消息点对点协议 3 4VAC 实时计费系统组网实时计费系统组网 图 1 VAC 和预付费系统组网图 5基于基于 TCP/IP 的协议的协议 5.1 通信方式通信方式 SCP 与 VAC 之间的通信基于 SGIP+协议，但对 SGIP+协议进行了扩展，并且只支持 本规范所定的一些消息。 SCP 和 VAC 之间通信采用 SOCKET 连接方式，SCP 为通信服务端，VAC 为通信客户 端，如果需要，VAC 可以同时向一个 SCP 建立多个连接。SOCKET 连接的方式具体请见 附录 A。 当客户端要发送命令时，主动向服务器端建立连接，然后向服务器端发送命令，并接 收应答；服务器端从客户端接收命令，返回应答。连接建立以后，客户端可以连续发送多 条命令。 如果服务器端检测出一条连接长时间空闲(默认 90 秒，可配置)，可以主动断开该连接。 如果需要，客户端可以同时向一个服务器端建立多个连接。 客户端向服务端发送消息后等待 T 秒后未收到响应，应立即重发，再连续发送 N-1 次 后仍未得到响应则停发。现阶段建议取值为：T=60 秒，N=3。 （可配置） 。 4 5.2 通信初始化通信初始化 客户端有命令要向服务器端发送时，由客户端首先通过 Bind 命令向服务器端发起连接。 服务器端根据 Bind 命令之中的登录名和密码，对客户端的合法性进行验证，然后返回一条 Bind_Resp 应答给客户端。如果验证通过，则客户端和服务器端的通信开始，否则中断连 接。 客户端在向服务器端发送连接请求时，如果连续 3 次连接不成功，应报警，并在 5 分 钟后再次发出连接请求。 5.3 通信过程通信过程 客户端与服务器端之间发送的任何一条命令都带有一个序列号，序列号由命令源产生。 客户端与服务器端通信开始以后，客户端可以向服务器端发送相应的命令，服务器端对收 到的命令返回应答。 5.4 通信结束通信结束 如果客户端认为和服务器端的通信已结束，则客户端应该向服务器端发送 Unbind 命令， 服务器端随后返回 Unbind_Resp 应答，然后双方断开连接。 5.5 网络故障网络故障 客户端与服务器端的通信过程中如果检测到双方连接中断(如网络断线)，客户端应该 断开连接，然后尝试重新向服务器端建立新的连接；服务器端应该按照接收到 Unbind 的情 况进行处理，断开和客户端的连接。 5.6 接收到非法命令或应答接收到非法命令或应答 如果服务器端接收到的命令语法错误，比如命令不完整、命令无法识别等，则断开和 客户端的连接；客户端应该向服务器端建立新连接继续发送命令。 如果客户端接收到的应答语法错误，比如命令不完整、命令无法识别等，则主动断开 和服务器端的连接；服务器端也应该断开和客户端的连接。 如果命令语法正确，但服务器端不能处理该命令，比如 SCP 收到 SM_ACC 命令，则 返回相应应答，并在应答中指定错误原因。如果应答语法正确，但客户端不处理该应答， 比如 VAC 收到 SM_ACC_RESP 应答，则丢弃.。 Comment xujh1: 待统一分配 5 5.7 序列号定义序列号定义 序列号用来唯一标示一个消息的。在补款话单中，序列号需要与对应的批价请求消息 一致。 序列号分成三部分，每部分为一个 32 位整数，第一部分表示命令源节点的编号，第二 部分表示命令产生的日期和时间(网关系统中的任何命令的保存时间都不应该超过一年)， 格式为十进制的 mmddhhmmss，比如 11 月 20 日 20 时 32 分 25 秒产生的命令，其第二部 分为十进制 1120203225；第三部分由 0 开始，循环进位，直到进位满了之后再清零，重新 开始计数。接收方在返回应答时，应答的序列号必须和相对应的命令的序列号相同。 图 2 命令序列号格式举例 5.8 序列号重复序列号重复 如果命令的序列号和以前接收到的命令的序列号相同，且命令内容也相同，则接收方丢 弃该命令；如果序列号相同，但是命令内容并不相同，则命令接收方在应答中返回错误码。 由于联通在信、炫铃业务都是采用 SGIP+消息进行鉴权扣费，所以该序列号需要进行统 一规划，对于各个实体，需要统一分配源节点号。 源节点编号为 VAC 的节点编号，全国唯一，并且需要注意不要和本地其他增值业务平台 重复 6 6VAC 与与 SCP 通信使用的通信使用的实时接口协议实时接口协议 6.1 批价请求批价请求 6.1.1描述描述 VAC实现实时计费，必须向SCP发送有关的扣费信息，批价请求消息是基于SUBMIT消息 的扩展，它保留了实现实时计费必要的信息。 当SCP判断当月包月费已扣除、但VAC又发起包月费扣除请求时，SCP完成每月包月费多 次扣除的剔重。 6.1.1.1批价请求消息参数(SM_ACC) 字段长度 （字节） 类型说明 SPNumber21Text和话单一致，产品接入号，该字段不能为空。如果没有接入号， 则填 000000000000 CorpId5Text企业代码，取值范围0-99999，该字段不能为空。(现有企业代码为 8位，只向SCP同步前5位 X1X2X3X4X5) ServiceType10Text业务代码，由SP定义，该字段不能为空。 SmgCode6Text填写发起方设备编号，填写源发起方设备编号，例如彩信中心编 号 Priority1Integer优先级0-9从低到高，默认为0 Pay_msdn21Text付费号码，手机号码前加“86”国别标志，该字段不能为空。 SCP通过该号码进行鉴权扣费。 对于SP彩信，就是接受方号码。 UserNumber21Text接收该彩信的手机号，手机号码前加“86”国别标志 FeeValue6Text取值范围 0-99999，该条彩信的收费值，单位为分，由 SP 定义 对于包月制收费的用户，该值为月租费的值，该字段不能为空。 7 FeeType1Integer计费类型，该字段不能为空。 计费类型，该字段不能为空。 0：不计费，仅用于核减SP对称的信道费； 1：免费； 2：按条/次计费；对包周期类型计费，仍填 2 3：按包月收取； 4：封顶计费 5：按流量计费 6：按时长计费 7：包多月计费 GivenValue6Text取值范围 0-99999，赠送用户的话费，单位为分，由 SP 定义，特 指由 SP 向用户发送广告时的赠送话费； 保留，暂时不使用。VAC 填写 0. MorelatetoMTFlag1Integer业务类型，该字段不能为空，根据实际情况填写。 0-4-保留。 5-彩信 MOAT 6-彩信 AOMT 7-彩信 MOMT 8-彩信 MOET 9-彩信 EOMT 10-彩信 DlvRpt 11-彩信 RdRpt 12-彩信 Reply VAC 填写 0 CPID8TextCP 代码，做结算用，当 CPID、SPID 字段均存在时，以 CPID 进 行结算；当 CPID 为空时，以 SPID 进行结算 ContentID30Text填写中国联通已分配了 ContentID 的内容 ID Service_Type2Text业务类型 取值见 VAC 接口规范附录 A（业务类别） CDRType 4 Text CDR 类型，如点到点、点到应用等 1：MOAT（移动用户始发、应用终止） 2：AOMT（应用始发、移动用户终止） 3：MOMT（移动用户始发、移动用户终止） 8 方向： VAC SCP 6.1.1.2批价请求响应消息参数(SM_ACC_RESP) 字段长度（字节）类型说明 Operate_Result1IntegerSM_ACC 命令是否 成功。 0：执行成功 其它：错误码 Reserve8Text保留，扩展用 方向： VAC SCP 10 6.2.1.2结果通知响应消息参数（SM_FM_REP） 字段长度（字节）类型说明 Operate_Result1IntegerSM_FM 命令是否成 功。 0：执行成功 其它：错误码 Reserve8Text保留，扩展用 6.2.1.3错误处理 应用层的错误在结果通知响应结果中定义。 SCP/PDSCP 用户正常使用时，VAC 产生话单(当 VAC 与 SCP/PDSCP 断链，仍允许用户使 用时，仍产生本话单)格式见 VAC 与 BSS 接口规范 6.1.6.3.2 节，存放目录如下： / 当 VAC 与 SCP/PDSCP 断链，仍允许用户使用时，VAC 产生的用于给运营商补款的话单 格式见 VAC 与 BSS 接口规范 6.1.6.3.2 节，存放目录如下： / 当计费成功，但向用户服务失败、同时 VAC 与 SCP/PDSCP 断链时，VAC 给用户补款话 单格式见附录 B，存放目录如下： / 7通信协议通信协议 7.1 VACVAC 与与 SCPSCP 之间的消息之间的消息 VAC 与 SCP 之间的通信目前主要支持以下消息： 消息说明 BIND服务器端接受客户端的登陆 11 BIND_RESP服务器端给客户端登陆信息的反馈 UNBIND客户端向服务器端发起关闭连接 UNBIND_RESP服务器端对关闭连接请求的响应 SM_ACC批价请求消息，VACSCP SM_ACC_RESP批价请求响应消息，SCP VAC SM_FMVAC向SCP提出结果通知消息 SM_FM_REPSCP对结果通知消息的响应 7.2 消息定义消息定义 定义的消息由消息头和消息体组成。 7.2.1数据类型数据类型 消息中的所有 Integer 类型的字段均采用网络字节顺序。所有消息中的序列号字段均 占 12 个字节，分为 3 个 4 字节整数；通信传输时每个整数都使用网络字节顺序，但整数的 次序并不改变。也就是说，通信传输的时候，序列号字段应该按照三个连续的 4 字节整数 来处理 7.2.2 消息头的格式消息头的格式 字段长度（字节）类型说明 Message Length4Integer消息的总长度(字节) Command ID4Integer命令 ID Sequence Number12Integer序列号 类型说明 Integer 无符号整数 Text定长字符串，左对齐存储，空余位置补0 12 7.2.3 消息体的格式消息体的格式 7.2.3.1BIND 消息 字段长度（字节）类型说明 Login Type1Integer登录类型。 1：VAC 向 SCP 建立的连接， 用于发送命令 2：SCP 向 VAC 建立的连接， 用于发送命令 其它：保留 Login Name16Text服务器端给客户端分配的 登录名 Login Passoword16Text服务器端和 Login Name 对 应的密码 Reserve8Text保留，扩展用 7.2.3.2BIND_RESP 消息 字段长度（字节）类型说明 Result1IntegerBind 执行命令是否成功。 0：执行成功 其它：错误码 Reserve8Text保留，扩展用 7.2.3.3UNBIND 消息 通信连接建立以后，客户端如果要停止通信，需要发送 Unbind 命令；服务器端收到 Unbind 命令后，向客户端发送 Unbind_Resp 相应，然后双方断开连接。 13 7.2.3.4UNBIND_RESP 消息 UNBIND_RESP 消息没有消息体 7.3 命令标志数值定义命令标志数值定义 命令宏定义数值说明 BIND0X1服务器端接受客户端的登陆 BIND_RESP0X80000001服务器端给客户端登陆信息的反馈 UNBIND0X2客户端向服务器端发起关闭连接 UNBIND_RESP0X80000002服务器端对关闭连接请求的响应 SM_ACC0X2000批价请求消息，VACSCP SM_ACC_RESP0X80002000批价请求响应消息，SCP VAC SM_FM0X4000VAC向SCP提出结果通知消息，由SCP与 VAC使用。 SM_FM_REP0X80004000SCP对结果通知消息的响应，由SCP与 VAC协商使用。 7.4 错误码定义错误码定义 错误码描述 0无错误，命令正确接收 1非法登录，如登录名、口令出错、登录名与口令不符等。 2重复登录，如在同一TCP/IP连接中连续两次以上请求登录。 3连接过多，指单个节点要求同时建立的连接数过多。 4登录类型错，指bind命令中的logintype字段出错。 5参数格式错，指命令中参数值与参数类型不符或与协议规定 的范围不符。 6非法手机号码，协议中所有手机号码字段出现非86130号码或 手机号码前未加“86”时都应报错。 7消息ID错 14 8信息长度错 9非法序列号，包括序列号重复、序列号格式错误等 10扩展 11扩展 21 用户号码已挂失 22用户号码已处于保留期 23用户号码处于冷冻期 24扩展 25扩展 26扩展 27扩展 28扩展 29计费用户不存在（当用户不存在时，网关要删除用户信息表 中相应的号码） 30计费用户不提供此功能 31非法设备 32系统失败 33扩展 34计费用户是和约用户 35计费用户余额不足 36计费用户不支持增值业务 其它其它错误码(待定义) 15 附录附录 A SOCKET 连接连接 通信双方以客户-服务器方式建立 TCP 连接，用于双方信息的相互提交。VAC 为客户 端，SCP 为服务端； 当客户端要发送命令时，主动向服务器端建立连接，然后向服务器端发送命令，并接 收应答；服务器端从客户端接收命令，返回应答。连接建立以后，客户端可以连续发送多 条命令。命令发送完并接收到所有应答后，客户端应该主动断开连接。 如果服务器端检测出一条连接长时间空闲(默认 90 秒，可配置)，可以主动断开该连接。 如果需要，客户端可以同时向一个服务器端建立多个连接。 VAC 向 SCP 发送消息后等待 T 秒后未收到响应，应立即重发，再连续发送 N-1 次后 仍未得到响应则停发。现阶段建议取值为：T=60 秒，N=3。 （可配置） 附录附录 B 用户补款话单格式用户补款话单格式 1、 话单文件命名 文件类型（2位）+文件标志（1位）+帐务周期月份（2位）+文件产生的时间（精确到 年月日时分）+SSID（3位）+序列号（4位）.后缀。 （1）文件类型 取值：20 （2）后缀 /下为req； /下为res； （3）序列号 以帐期为循环单位，每帐期从0001开始，同一帐期内连续进行累加。 （4）文件标志 取值：N表示正常文件；T表示测试文件。 2、 原始话单文件头 序号名称长度备注 1文件序列号(流水号)CHAR(4) 以帐期为单位，从 0001 开始，排 满 9999 后重新循环 2文件版本号CHAR(2)取值：02 3文件产生时间CHAR(14)Yyyymmddhhmmss 4文件生成方系统代码CHAR(8)902 5文件接收方系统代码CHAR(3)104 6记录开始日期时间CHAR(14)Yyyymmddhhmmss 7记录结束日期时间CHAR(14)Yyyymmddhhmmss 16 8总记录数CHAR(10)右对齐，左补 0 9备注CHAR(40) 10换行CHAR(1) 3、 回执文件头 4、 原始话单文件体 序号属性名字段类型最大长度是否 必填 备注 1流水号CHAR18M流水号，格式为时间戳+序列号： YYYYMMDDHHMMSSxxxx，其中 xxxx 为序列号，从 0001 开始，排满 9999 后重新循环 2TimeCHAR20M本话单记录产生的时间戳 3MessageIDCHAR20OVAC生成的唯一识别标识。标识多个请 求是属于同一个事务。 对增值侧发起的CheckPrice消息引起的 话单，填CheckPrice中的 SequenceNumber；对vac直接发起的计 费/扣费消息引起的话单，vac按照 CheckPrice中的SequenceNumber格式生 成MessageID；对CRM发起定购消息后 vac立即发起扣费的，MessageID填写 Web Service接口中的 RecordSequenceID。 4SPIDCHAR8MSP 代码,做三方结算用 5ServiceIDCHAR12MSP 的 SrvID，对应原 SGIP+协议的 ServiceType 6CPIDCHAR8OCP 代码，做结算用，当 CPID、SPID 字段均存在时，以 CPID 进行结算；当 序号名称长度备注 1文件序列号CHAR (4) 从 0001 开始排序，排满 9999 后重 新循环 2文件版本号CHAR (2)取值：02 3文件产生时间CHAR (14)Yyyymmddhhmmss 4文件生成方系统代码CHAR (3)902 5文件接收方系统代码CHAR (8)104 6总记录数CHAR (10)右对齐，左补 0 7正确处理记录数CHAR (10)右对齐，左补 0 8备注CHAR(40) 9换行CHAR (1) 17 CPID 为空时，以 SPID 进行结算 7ContentIDCHAR30O填写中国联通已分配了 ContentID 的内 容 ID 8 AccessNo CHAR21O联通在信、彩信产品接入号,业务使用 时的接入号 9ServiceTypeCHAR2O取值见附录 A7（业务类型） 10SourceDevice_TypeCHAR4O发送端设备类型 11SourceDevice_IDCHAR20O发送端设备标识 12CDRTypeinteger4MCDR 类型，如点到点、点到应用等 1：MOAT（移动用户始发、应用终止） 2：AOMT（应用始发、移动用户终止） 3：MOMT（移动用户始发、移动用户 终止） 4：MOET（移动用户始发、Email 终 止） 5：EOMT（Email 始发、移动用户终 止） 9：Other（其他） 13ProductIDCHAR8MCRM 侧产品 ID 14SPC_ProductIDCHAR12MCRM