中国电信领航平台(ISMP-B)技术规范——省领航平台管理子系统产品接入接口(V3.0).doc

Q/CT XXXX-2014保密等级：公开发放中国电信集团公司企业标准Q/CT XXXX-2014中国电信领航平台(ISMP-B)技术规范省领航平台(ISMP-B)管理子系统产品接入接口（V3.0）Technical specifications of China Telecom Business Navigator PlatformInterface of Access product for Management subsystem of Bnet platform of Province V3.02014-04 发布 2014-04 实施中国电信集团公司 发布目 次目 次II前 言IV1、适用范围12、引用标准23、缩略语34、接口概述44.1方案概述44.2功能界定44.2.1客户受理产品44.2.2用户绑定/变更/解绑产品44.2.3用户登录使用产品54.2.4用户受理产品54.2.5用户操作行为同步接口64.2.6清单、业务使用情况采集接口64.2.7产品服务监控64.2.8产品平台对改号的支持64.2.9轻量认证鉴权接口64.2.10支付结果通知75、接口定义85.1SOAP&HTTP方式85.1.1客户开通/变更/退订产品接口85.1.2客户信息查询接口135.1.3用户绑定/变更/解绑产品接口195.1.4用户信息查询接口245.1.5用户使用产品认证鉴权接口285.1.6用户受理请求接口305.1.7使用客户端产品认证鉴权接口(可选)325.1.8轻量认证鉴权接口345.1.9工单报峻接口375.2数据库共享表方式(可选)385.2.1接口描述385.2.2接口数据表定义385.3FTP方式415.3.1使用清单采集接口415.3.2业务使用情况采集接口455.3.3用户操作行为同步接口505.4业务监控协议方式(可选)525.4.1产品平台监控接口52附录A54前 言本规范是中国电信领航平台系列规范之一，本规范定义了领航平台与产品平台的集成规范，包括功能界定、接口定义等。本规范由中国电信集团提出并归口。 本规范起草单位：中国电信股份有限公司广州研究院。修订记录如下：版本日期修订人概述修订2010-9-20李蓉蓉增加字段记录手机的IMSI信息修订2010-11-5李蓉蓉所有FTP接口均增补文件头修订2012-09-10李蓉蓉增加销售品、用户改号等商务领航5.0业务支持修订2013-11-13李蓉蓉增加用户受理接口增加用户操作行为同步接口增加话单同步接口修改使用客户端产品认证鉴权接口中增加0207用户改密接口修订2014-4-3舒大海增加轻量认证鉴权接口增加工单报竣接口增加报竣优化异常信息定位（XX平台返回）III1、 适用范围本规范适用于中国电信领航平台的设计及研发，提供给为中国电信开发领航平台的相关厂商。本规范是中国电信各级运营单位进行领航平台招标采购、工程设计、网络运营、管理、维护等方面的技术依据。2、 引用标准下列文件通过本文的参考而成为本规范的条款。凡是注日期的参考文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本文，凡是不注日期的参考文件，其最新版本适用于本文。1) 中国电信集团领航平台业务规范6.0 版。3、 缩略语缩略语中文全名FTP文件传输协议SOAP简单对象访问协议XML可扩展的标记语言其他缩略语参见中国电信领航平台(ISMP-B)技术规范总册。4、 接口概述4.1 方案概述在SI产品接入领航平台时，主要完成接口相关工作包括：1) 首先，领航平台与SI产品在线下完成产品基础信息的确认工作，领航平台提供产品平台的数据包括：SI产品标识、领航平台的接口webservice地址、产品的相关参数字典说明；产品平台需要提供给领航平台的基础信息包括：产品平台接受HTTP请求的地址。2) 其次，领航平台与SI产品平台的接口完成同步数据接口，主要包括客户、用户信息同步。3) 然后，实现客户使用领航平台，可以直接登录使用SI产品，即领航平台与SI产品平台实现单点认证。产品平台需要屏蔽原用户认证登录功能，全部改成用户登录时与领航平台进行认证的方式。在SI产品与领航平台接入接口对接工作完成后，与产品相关的操作流程：1) 在CRM完成客户产品受理后，同步数据到领航平台。2) 领航平台通过产品接入接口同步客户、用户相关数据信息给产品平台。产品平台能通过客户、用户信息查询接口，获取客户、用户的个性化产品属性信息内容。3) 客户在使用产品时，产品平台必须先通过领航平台的产品认证鉴权接口，验证用户的合法性，方能提供用户具体使用产品的功能项。4.2 功能界定4.2.1 客户受理产品4.2.1.1 产品平台产品开通：从客户开通产品接口接收省领航平台(ISMP-B)管理子系统发送的客户基础信息，并通过客户信息查询接口查询客户开通产品属性信息，执行产品系统内部新增客户功能后，通过应答返回客户开通结果给省领航平台(ISMP-B)管理子系统。产品变更：从客户变更产品接口接收省领航平台(ISMP-B)管理子系统发送的客户变更产品属性信息，并通过客户信息查询接口查询客户开通产品属性信息，执行产品系统内部变更客户产品属性信息后，通过应答返回客户变更结果给省领航平台(ISMP-B)管理子系统。产品退订：从客户退订产品接口接收省领航平台(ISMP-B)管理子系统发送的客户退订产品信息，执行产品系统内部注销客户信息后，通过应答返回客户退订结果给省领航平台(ISMP-B)管理子系统。4.2.1.2 省领航平台(ISMP-B)管理子系统产品开通：接收CRM派送的客户开通产品信息，通知能力网关新增客户产品配置数据，通知产品平台新增客户产品配置数据，返回受理结果给CRM系统。产品变更：接收CRM派送的客户变更产品属性信息，通知能力网关更新客户产品配置数据，通知产品平台更新客户产品配置数据，返回受理结果给CRM系统。产品退订：接收CRM派送的客户退订产品信息，通知能力网关注销客户产品配置数据，通知产品平台注销客户产品配置数据，返回受理结果给CRM系统。4.2.2 用户绑定/变更/解绑产品4.2.2.1 产品平台用户绑定产品：从用户绑定产品接口接收省领航平台(ISMP-B)管理子系统发送的用户基础信息，并通过用户信息查询接口查询用户绑定产品的个性化信息，执行产品系统内部新增用户功能后，通过应答返回用户绑定产品结果给省领航平台(ISMP-B)管理子系统。用户变更产品：从用户变更产品接口接收省领航平台(ISMP-B)管理子系统发送的用户变更信息，并通过用户信息查询接口查询用户绑定产品的个性化信息，执行产品系统内部更新用户信息后，通过应答返回用户变更结果给省领航平台(ISMP-B)管理子系统。用户解绑产品：从用户解绑产品接口接收省领航平台(ISMP-B)管理子系统发送的用户解绑产品信息，执行产品系统内部注销用户产品绑定关系，并通过应答返回用户解绑产品结果给省领航平台(ISMP-B)管理子系统。4.2.2.2 省领航平台(ISMP-B)管理子系统用户绑定产品：从CRM接收用户绑定产品信息，通过用户绑定产品接口通知产品平台用户信息，返回处理结果给CRM系统。 用户变更产品：从CRM接收用户变更产品属性信息，通过用户变更产品接口通知产品平台用户变更产品属性信息，返回处理结果给CRM系统。用户解绑产品：从CRM接收用户解绑产品信息，通过用户解绑产品接口通知产品平台用户解绑，返回处理结果给CRM系统。4.2.3 用户登录使用产品4.2.3.1 产品平台a) 企业管理员或用户可在产品平台直接登陆，有两种方式。1) 产品平台调用领航平台提供的URL登录页面，以保证各个产品平台登录页面的一致性。如果产品平台属于手机客户端登陆等领航平台暂时不提供的登陆方式，则需要产品平台按照领航平台登陆界面要求实现自己账号登陆，但是密码不要在产品平台进行变更。2) 省领航平台(ISMP-B)管理子系统与客户端产品服务端实现用户统一认证接口，用户通过认证鉴权后使用产品b) 用户登录领航平台使用产品：用户使用产品前，需经过集团领航平台(ISMP-B)管理子系统提供的用户认证数据接口，通过认证鉴权后使用产品4.2.3.2 省领航平台(ISMP-B)管理子系统a) 在产品平台登录时，有两种情况：1) 领航平台提供统一URL登录页面，供产品平台调用，以保证产品平台登录界面的一致性2) 领航平台提供客户端用户统一认证接口，产品平台调用接口鉴权认证用户b) 用户登录使用产品：领航提供统一登录界面，并且提供认证鉴权服务，为产品平台进行用户认证鉴权。4.2.4 用户受理产品4.2.4.1 产品平台用户订购产品：将用户订购数据送集团领航平台(ISMP-B)管理子系统，通过集团领航平台(ISMP-B)管理子系统调用翼支付进行费用支付。用户取消订单产品：将用户取消订单数据送集团领航平台(ISMP-B)管理子系统，集团领航平台(ISMP-B)管理子系统做订单取消操作。用户续费产品：将用户续费数据送集团领航平台(ISMP-B)管理子系统，通过集团领航平台(ISMP-B)管理子系统调用翼支付进行费用支付。4.2.4.2 省领航平台(ISMP-B)管理子系统用户订购产品：接收产品平台的用户订购数据，然后通过调用翼支付接口进行费用支付。用户取消订单产品：接收产品平台的用户取消订购数据。用户续费产品：接收产品平台的用户续费数据，然后通过调用翼支付接口进行费用支付。4.2.5 用户操作行为同步接口4.2.5.1 产品平台将用户在产品平台的操作行为通过ftp同步到集团领航平台。4.2.5.2 集团领航平台(ISMP-B)管理子系统接收产品平台的用户操作行为数据。4.2.6 清单、业务使用情况采集接口4.2.6.1 产品平台生成清单：根据业务需要，按照指定格式生成客户、用户的使用产品详细清单数据。业务使用情况：根据业务需要，提供省领航平台(ISMP-B)管理子系统查询客户、用户使用具体产品的业务使用日志情况。4.2.6.2 省领航平台(ISMP-B)管理子系统清单采集：根据业务需要，采集产品平台提供的客户、用户的使用产品详细清单数据。业务使用情况采集：根据业务需要，采集查询产品平台提供的客户、用户使用具体产品的业务使用日志情况。4.2.7 产品服务监控4.2.7.1 产品平台支持监控协议：支持SNMP、TCP/IP等多种协议，对产品平台进行监控。4.2.7.2 省领航平台(ISMP-B)管理子系统监控产品：省领航平台(ISMP-B)管理子系统发起对正式上线的产品平台监控请求，主要监控的内容是监控产品平台的运行状况，包括产品平台服务器设备运行状态、产品功能服务状态等。4.2.8 产品平台对改号的支持产品平台需要支持用户号码的改号，改号的主要调用方式：1) 个人单订购客户：产品平台通过客户变更接口接受改号请求, 然后通过客户信息查询接口查询客户改号信息。2) 个人/企业双订购的个人客户：产品平台通过用户变更产品接口接受改号请求，然后通过用户信息查询接口查询客户改号信息。4.2.9 轻量认证鉴权接口业务轻量加载产品，业务加载时，省领航平台跟产品平台之间无需对接原有客户开通/变更/退订等接口；在业务使用过程中，产品平台需要调用省领航平台的轻量认证鉴权接口进行认证鉴权，省领航平台认证鉴权完成后，向业务平台返回认证鉴权结果，业务平台根据认证鉴权结果，向客户/用户提供相应的服务。4.2.10 支付结果通知4.2.10.1 产品平台将支付结果告知省领航平台(ISMP-B)管理子系统。4.2.10.2 省领航平台(ISMP-B)管理子系统接收支付结果通知，并将处理结果返回给产品平台。5、 接口定义注：下列SOAP的超时时间定义为30秒（发起方发起请求开始计时），超过30秒后自动断开连接；http请求的响应时间为60秒；5.1 SOAP&HTTP方式省领航平台(ISMP-B)管理子系统与产品平台的业务数据通过省领航平台(ISMP-B)管理子系统提供的WebService服务进行交换。省领航平台(ISMP-B)管理子系统作为服务端，提供TradeService.wsdl文件供SI产品平台引用；产品平台作为客户端，只需提供一个URL地址接受省领航平台(ISMP-B)管理子系统发起的通知消息。具体接口方法及格式定义说明：1) 省领航平台(ISMP-B)管理子系统提供的wsdl文件地址：在TradeService.wsdl中包含的方法有：public String getPortalRequest(String streamingno,String rand)；/依据流水号以及随机令牌取得交易明文public String getPortalResult(String reqXML)；/依据XML请求报文取得相应的XML应答报文public String getEncodeString(String decode)；/依据明文取得相应密文2) 产品平台提供省领航平台(ISMP-B)管理子系统的URL地址： 其中productid为产品编号，provinceid为省标识。在省领航平台(ISMP-B)管理子系统触发调用产品平台提供的HTTP请求时，产品平台URL中包括参数：流水号streamingno、随机令牌rand和密文信息encode。格式如：?streamingno=1111&rand=1234&encode=xxxx。3) 加密协议领航平台采用MD5 算法作为系统关键域的加密协议。考虑到各类开发语言基于MD5 算法的实现方面可能存在差异性，为了实现平台整体的开发语言无关性，平台将MD5算法进行了相应封装，并提供相关的WEBSERVICE 服务供外界系统调用（getEncodeString）。5.1.1 客户开通/变更/退订产品接口5.1.1.1 接口协议概述l 接口名称：客户开通/变更/退订产品。l 接口描述：省领航平台(ISMP-B)管理子系统把客户开通/变更/退订产品的数据信息经过产品接口同步到产品平台（注：客户产品属性通过客户信息查询接口获取）。个人单订购，客户单订购，双订购的客户订购走此接口。l 触发条件：省领航平台(ISMP-B)管理子系统向产品平台发送客户开通/变更/退订产品请求时触发产品平台调用此接口。l 接口协议：SOAP(Document Style)。 l 接口调用方向：产品平台 省领航平台(ISMP-B)管理子系统。l 命名空间：l 接口方法：getPortalRequest、getPortalResult。5.1.1.2 接口流程主要涉及到的接口调用流程:图 1客户开通/变更/退订产品接口流程1) 客户管理员在集团领航平台管理子系统中客户工作台开通/变更/退订产品；2) 集团领航平台管理子系统生成相关参数StreamingNo、rand和encode,并存入日志表中；3) 集团BNET管理子系统调用产品平台提供的HTTP请求，在请求中加入关键字信息，格式如下：?StreamingNo=xxxx&rand=xxxx&encode=xxxx。其中StreamingNo为明文数字（其中通过时间戳和4位随机数组合而成），rand为4位随机数字，encode为开户请求数据包通过MD5加密后的字符串；4) 产品平台从HTTP请求中获取的交易关键字StreamingNo、rand、encode，加入到调用集团BNET管理子系统的webservice接口方法getPortalRequest中，发起从集团BNET管理子系统获取客户信息的请求；5) 集团BNET管理子系统根据收到的接口参数，判断校验通过后，返回产品平台客户数据内容包，并注销本次交易流水记录； 6) 产品平台根据获取的客户数据内容包，调用getEncodeString加密获取数据包；7) 集团BNET管理子系统根据产品平台的请求包加密后返回给产品平台；8) 产品平台获取加密后的数据包与第四步中获取的encode进行验证；9) 第八步验证通过后，产品平台调用集团BNET管理子系统的webservice接口方法getPortalResult, 发起从集团BNET管理子系统的查询某一客户信息请求；10) 集团BNET管理子系统获取产品平台发起请求报文中的查询密码，并与原先在集团BNET管理子系统设定的产品查询密码进行比较验证；11) 第十步验证通过后，集团BNET管理子系统返回产品平台客户数据内容包；12) 产品平台获取客户数据包内容，进行本地的客户信息处理；13) 产品平台将客户信息处理后的结果返回给集团BNET管理子系统；14) 集团BNET管理子系统根据产品平台的处理结果进行了相应的客户产品处理；15) 集团BNET管理子系统处理完成以后，返回给产品平台一个包含重定向地址的数据内容包；16) 产品平台获取返回的报文，解析出其中的重定向的url，然后重定向操作。5.1.1.3 数据信息定义5.1.1.3.1 领航平台返回产品平台要素定义表 1领航平台返回产品平台要素定义参数名类型出现次数长度注释StreamingNoString132流水号OPFlagString140101：客户开通0102：客户变更0103：客户退订0107:客户停机0108:客户复机0109:改号TimeStampString118当前时间戳YYYYMMDDHHMISSProductIDString18产品标识SIIDString120SI标识OfferIDString0.120销售品ID销售品标识，本期只涉及一个产品包含多个销售品，但一个销售品只对应一个产品BizIDString120客户产品计费标识PasswordString132产品查询密码（可为空）AreaCodeString15客户地区CustIDString120客户标识CustAccountString1100客户帐号CustNameString1256客户名称IMSIString0.120手机的IMSI(手机用户个人单订购使用)AccessNoString121接入号SummaryString0.164备注5.1.1.3.2 产品平台返回领航平台应答要素定义表 2产品平台返回领航平台应答要素定义参数名类型出现次数长度注释StreamingNoString132流水号OPFlagString140101：客户开通0102：客户变更0103：客户退订0107:客户停机0108:客户复机0109:改号ReturnStatusString14应答返回状态SummaryString11024备注 当处理失败时，将全量校验和失败的详细错误信息说明加入“XX产品平台返回”5.1.1.3.3 产品平台返回领航平台应答结果返回码表 3产品平台返回领航平台应答结果返回码结果码错误原因备注以下为通用返回码00000交易成功00001交易失败00002参数要素不全00003非业务时间00004业务未授权00005查询结果为空00006系统无此业务数据库异常00201查询数据库异常00202插入数据异常00203修改数据异常00204删除数据异常00205过程执行异常业务逻辑错误00401关键数据项不能为空00402业务数据内容不存在00403数据格式不正确00404业务逻辑执行错误网络通讯错误00601连接服务异常00602断开服务异常00603发送数据失败00604接收数据失败5.1.1.3.4 接口数据包示例l 客户开通产品，领航平台返回产品平台数据包格式： 1141010120030009 300666666571026aptest中国电信测试企业客户开通产品l 客户开通产品，产品平台发送应答数据包到领航平台格式： 1141010100000 客户开通产品l 客户信息变更，领航平台返回产品平台数据包格式： 1141010220030009 300666666571026aptest中国电信测试企业客户变更产品l 客户信息变更，产品平台发送应答数据包到领航平台格式： 1141010200000 客户变更产品l 客户退订产品，领航平台返回产品平台数据包格式： 1141010320030009 300666666571026aptest中国电信测试企业客户退订产品l 客户退订产品，产品平台发送应答数据包到领航平台格式： 1141010300000 客户退订产品5.1.2 客户信息查询接口5.1.2.1 接口协议概述l 接口名称：客户信息查询。l 接口描述：产品平台通过客户信息查询接口，能查到对应产品的客户、用户和产品属性信息。l 触发条件：产品平台发起查询产品相关的客户、用户、产品属性信息。l 接口协议：SOAP(Document Style) 。 l 接口调用方向：产品平台 省领航平台(ISMP-B)管理子系统。l 命名空间：l 接口方法：getPortalResult。5.1.2.2 接口流程主要涉及到的接口调用流程:图 2客户信息查询接口流程1) 产品平台根据分配的ProductID和密码（MD5加密后的密文），加上当前时间戳、查询条件，调用省领航平台(ISMP-B)管理子系统的webservice接口方法getPortalResult，发起从省领航平台(ISMP-B)管理子系统的查询某一客户信息请求；2) 省领航平台(ISMP-B)管理子系统根据收到的接口参数，判断校验通过后，返回产品平台客户数据内容包。5.1.2.3 数据信息定义5.1.2.3.1 产品平台查询请求要素定义表 4客户信息查询接口产品平台查询请求要素定义参数名类型出现次数长度注释StreamingNoString132流水号OPFlagString140104：客户查询SIIDString18SI编码TimeStampString118当前时间戳YYYYMMDDHHMISSBizIDString120客户产品计费标识（可为空）AreaCodeString15客户地区（可为空）ProductIDString18产品编码OfferIDString18销售品编码PasswordString132查询密码CustIDString120客户编码CustAccountString1100客户帐号CustNameString1256客户名称AccessNoString121接入号SummaryString0.164备注5.1.2.3.2 领航平台返回产品平台查询结果要素定义表 5客户信息查询接口领航平台返回产品平台查询结果要素定义参数名类型出现次数长度注释StreamingNoString132流水号OPFlagString140104：客户查询ProductIDString18OfferIDString18销售品编码BizIDString120客户产品计费标识AreaCodeString15CustIDString120客户编码CustAccountString1100客户帐号CustNameString1256客户名称ProductInfoProduct0.n产品属性信息ReturnStatusString14应答返回状态SummaryString11024 备注当处理失败时，将全量校验和失败的详细错误信息说明加入“XX领航返回”表 6客户信息查询接口领航平台返回产品平台查询结果要素定义数据项定义：Product参数名类型出现次数长度注释ProductInstIDString132产品属性实例IDProductTypeString132产品属性标识ProductValueString1100产品属性值ParentTypeString0.132上级属性标识ProductParentInstIDString132父节点产品属性实例ID（如果没有父节点，就填空）5.1.2.3.3 领航平台返回产品平台应答结果返回码表 7客户信息查询接口领航平台返回产品平台应答结果返回码结果码错误原因备注以下为通用返回码00000交易成功00001交易失败00002参数要素不全00003非业务时间00004业务未授权00005查询结果为空00006系统无此业务数据库异常00201查询数据库异常00202插入数据异常00203修改数据异常00204删除数据异常00205过程执行异常业务逻辑错误00401关键数据项不能为空00402业务数据内容不存在00403数据格式不正确00404业务逻辑执行错误网络通讯错误00601连接服务异常00602断开服务异常00603发送数据失败00604接收数据失败5.1.2.3.4 接口数据包示例l 产品平台发送应答数据包到领航平台格式： 0104 SI0001 1244690606890 200 300 3644a684f98ea8fe223c713b77189a77 6 ap 客户查询l 领航平台返回产品平台数据包格式： 0104 323002000 40825826451003 020 GD990947809 eshoretestxm06121 test 1 11002001000000000000 1 2 11002004000000000000 0 3 11002005000000000000 0