中国联通WAP业务平台标准接口规范.doc

中国联合通信有限公司中国联通CDMA WAP业务平台标准接口规范（Ver 2.1）中国联合通信有限公司2004-11-1目 录变更说明41概 述51.1 编写目的51.2用语解释52. 一次认证53CP/SP和业务接入方法63.1 CP/SP接入方法63.2 业务接入64. 计费处理的方法74.1 计费方式描述74.2 优惠方案描述85. Download fun（下载类服务）96. WAP PUSH106. 1 通过华友增值业务平台进行PUSH106.1.1接口描述106.1.2发起方系统106.1.3接收方系统106.1.4 接口协议106.1.5访问控制机制116.1.6调用函数116.1.7接口形式116.1.8 示例代码136.1.9 注意事项156. 2通过综合业务接入管理平台进行PUSH157. 关于获取手机用户的唯一标识158. 关于手机型号的参数获取方法169. 用户归属地机构获取方法1625变更说明变更日期变更者版本号变更内容2004-09-17孙宇张峰V2.02新增 章节9：用户归属地机构获取方法；删除 章节6. 1：通过PPG网关进行PUSH；删除 原章节9：CDMA返回上级规范，原规范内容请参见中国联通CDMA WAP业务返回规范；更改本规范名称为中国联通CDMA WAP业务平台标准接口规范；调整了部分语言描述。2004-11-2孙宇V2.1补充章节3.2：下载类业务计费URL要求；补充平台计费针对重定向页面的处理方式；修改章节4.1：将按栏目计费统一更名为按天计费；调整了部分语言描述；本次修改部分用红色标明。1概 述1.1 编写目的本文将主要解释中国联通CDMA WAP平台计费处理机制，提供针对联通CDMA WAP业务的计费、认证、用户信息获取等标准接口规范。1.2用语解释GW：Openwave WAP Gateway，Openwave WAP 网关CP/SP：内容提供商/服务提供商DF：Download FunPF：Portal FrameworkIM：Instant MessagingOPM：Openwave Provision ManagerHttp Request：Http请求Http Response：Http响应计费信息确认：用户确认收费策略，如包月、点击及收费金额计费：根据用户确认的收费策略，作计费处理，计算本次使用服务的费用2. 一次认证系统为手机用户提供对所有联通提供的WAP应用的一次认证（Single Authentication）功能。当手机用户使用WAP服务时，对所有CP/SP提供的所有需要认证的服务，只需登录一次，即可以使用这些服务。一次认证功能具有以下特点：l 为手机用户提供针对所有WAP服务统一认证l 采用Http Proxy作为实现的基本技术架构l 基于HttpSession管理的认证系统l 通过Web Service技术，为CP/SP提供一套完整的认证服务，帮助CP/SP认证用户身份l 用户信息的集中式管理，集成Openwave用户管理系统l 完善的安全机制l 兼容Openwave针对CP/SP开放的Http API。3CP/SP和业务接入方法3.1 CP/SP接入方法CP/SP接入本平台需要向中国联通提交接入申请，CP/SP的应用服务器可以通过互联网或者直接通过局域网、以及VPN和专线方式与中国联通的WAP平台系统相连接。3.2 业务接入如果CP/SP的接入申请经过中国联通审核接入了WAP平台系统，就可以提交业务申请， 当CP/SP提供一个业务的时候，在提供该业务的资费策略和优惠信息的同时，由于WAP平台系统是基于URL的内容计费， 因此CP/SP在接入业务之前需要提供该业务如下参数：参数名称参数举例用途描述业务入口URLhttp:/业务的入口URL，一般为业务首页面，供业务上线时链接使用。确认URL表示访问该URL时，如果用户未定制该URL对应的业务，则平台系统会弹出计计费提示信息和订购方式供用户查看和选择。计费URL收费服务标识对应收费URL，如果用户访问此URL，平台系统结合用户对此业务的订购策略进行对应计费处理。示例：财经新闻服务有目录索引文件如果确认URL取为：确认URL和计费URL联通建议不要取到业务的入口，应尽量在二级或者三级页面，使用户能够看到部分内容。取另请参照中国联通互动视界业务计费测试申请表范例。特殊说明：（1）对同一业务的计费URL和确认URL可以为包含关系或重复，并可以包含业务入口URL或与业务入口URL相同。（2）对于同一个业务入口URL只能有一个，但计费URL或确认URL，均可以为多个。（3）对不同的业务，一个业务的入口、计费或确认URL不允许与另外一个业务的入口、计费或确认URL相同；也不允许出现包含的情况。（4）由于手机支持的URL长度有限，而且不同的机型支持的长度也不一致，为了能够使各种机型均能够正常使用WAP业务，要求接入的业务内容的URL长度不能够超过128个字符，并不允许出现中文字符。（5）中国联通CDMA WAP系统只处理80端口，CP申请接入的业务必须使用80端口。不允许出现业务内容对应的URL为其他端口的情况。（6）中国联通CDMA WAP系统计费网关只针对页面返回的HTTP状态为“200”的页面进行计费过滤处理，对于重定向页面（返回的HTTP状态为“302”），计费网关不做任何处理。因此，CP不能提交有重定向功能的页面作为业务的确认URL和计费URL。示例：某业务有两个页面，A页面和B页面。A页面负责将用户请求重新定向到B页面。如果CP将A页面作为计费URL：当用户访问A页面时，计费网关将请求转发给CP 的web服务器，A页面作重定向操作后，返回给计费网关的状态码是“302”，计费网关对A页面不做计费处理。如果CP将B页面作为计费URL：当用户访问A页面时，计费网关将请求转发给CP 的web服务器，A页面作重定向操作后，返回给计费网关的状态码是“302”，计费网关对A页面不做计费处理。当网关或者手机接到该http响应信息后，会自动发起对B页面的请求。B页面的响应中如果其状态码为“200”，则计费网关对B页面做计费处理。（7）对于下载类业务，中国联通建议将确认URL设定为图片预览页面的URL，如preview.jsp，或者图片名称列表页面list.jsp，以便用户能够看到栏目足够信息后，再弹出定制提示页面。下载类业务的计费URL必须设定为CP业务接收网关下载状态的报告页面，并且必须加上STATUSOK的下载成功状态参数。示例：一铃声业务在传递给WAP网关的其接收下载状态的页面URL为：http:/wap.uni- （该页面为CP服务器上的页面，应当能够处理状态信息，并给予用户正确中文提示），则用户在进行该业务下的某一铃声下载后，WAP1.2网关会根据手机返回的信息，将用户的访问转到该接收下载状态的页面并在URL上附加下载状态信息，如用户下载成功，用户的请求将会网关被转发到http:/wap.uni- ，“STATUSOK”的内容为WAP1.2网关附加的。STATUS还存在其它内容，如：DOWNLOAD_FAILED, OUT_OF_MEMORY, BROWSER_ERROR等，这些状态都表示用户没有成功完成下载。只有当网关返回的为“OK”的情况下，才能对用户收取费用。因此，CP在上报该业务的计费URL时，应当填写：http:/wap.uni- 。4. 计费方式和优惠方案中国联通CDMA WAP业务平台负责中国联通WAP业务的计费工作，CP无需自己开发计费系统。中国联通CDMA WAP业务平台提供如下的业务计费方式和优惠方案。CP/SP在提交业务测试申请时，需要填写准确的业务的计费方式以及对应的优惠方案。4.1 计费方式描述对业务的基本计费方法分为：免费、按点击计费、按天计费和按包月计费。免费指用户免费使用CP提供的该项业务。中国联通CDMA WAP业务平台提供如下三种基本计费方式，一个业务可以同时选择一种或多种计费方式：按点击计费：按点击计费是用户在使用某CP申请并提供的某项业务时，在申请的地址之下的页面中每点击一次该服务计一次费，如：点击一条新闻计0.1元。按天计费：按天计费是用户在一天内使用该业务收取一次特定价格的费用，多次进出和重复使用不重复计费。包月计费：包月计费是按月一次性收取一定费用，在计费月中用户使用包月服务时，一次性收取包月费用。如用户使用某价格为5元的包月服务，每月初收取用户5元后，用户即可无限制的使用该包月业务，当月不再收取该业务其它信息费。用户在一个月的前半月定制包月计费方式的业务，当月收取包月费用的全价；在后半月定制包月业务，定制当月只收取包月费用的半价。定制后，若用户不退定该业务，则后续月每月均收取包月费用的全价。4.2 优惠方案描述收费业务的某一种计费方法可以分别采用如下几种优惠方案： 试用时长：在优惠开始和结束日期之内定制该业务，免费使用一段时间。CP/SP可以申请优惠开始和结束日期，以及试用时长。试用次数：在优惠开始和结束日期之内定制该业务，免费使用设定的次数。CP/SP可以申请优惠开始和结束日期，以及试用次数。折扣优惠：在优惠开始和结束日期之内，按照正式价格的折扣比例优惠。CP/SP可以申请优惠开始和结束日期，以及折扣比例。固定优惠价格：在优惠开始和结束日期之内，按照设定的优惠价格（小于正常的收费价格）进行优惠。CP/SP可以申请优惠开始和结束日期，以及优惠价格。特殊的优惠方案：服务包计费（优惠套餐）（包月计费）：服务包计费是把某一CP/SP的几项服务捆绑在一起向用户销售的策略，用户定制服务包后，在每月缴纳一定费用（如用户每月缴纳25元），就可以浏览某一内容提供商（CP）提供的服务包内包括的全部服务。示例：新闻财经业务选择同时有：（1） 按次计费，每次0.5元，按次计费方式同时选择按照80%折扣优惠，优惠开始和结束时间为：2003/5/1-2003/5/15。（即用户选择该种计费方式，则在2003/5/1-2003/5/15期间，每次使用只收费0.4元）（2） 按栏目计费，每天3元，按栏目计费同时选择按照2元固定价格优惠，优惠开始和结束时间为：2003/5/1-2003/5/15。（即用户选择该种计费方式，则在2003/5/1-2003/5/15期间，每天使用只收费2元）（3） 包月收费，每月10元，包月收费无优惠方案。（即用户如2003/5/11日选择该种计费方式，则在2003年5月，只收费（31-10）/31*10=6.77元，如果2003年6月份，用户未退定，则6月份收费10元）CP/SP提交的业务申请需要通过中国联通审核，如果通过审核，联通则会安排CP到联通指定的测试单位进行业务和计费测试等工作。联通在接收到测试单位测试通过报告后，将会安排业务正式开通。5. Download fun（下载类服务）对于下载类业务，CP/SP需要向中国联通申请该类服务，并提交下载内容服务器的主域名或IP地址给中国联通，由中国联通审核能否向CP/SP所提供的服务的主域或IP地址提供下载类服务权限，并在Openwave download fun server中进行相关控制配置。在填写Download的地址中的source时要后跟下载目标的实际URL。例如：a href=uplink:download?source=http:/uniinfo.U有关Download Fun更多内容请参考Openwave Download Fun公开技术规范，或者访问：获取更多信息。6. WAP PUSH PUSH目前可以采用两种方式：通过中国联通WAP业务综合平台下发PUSH；通过中国联通综合接入管理平台下发PUSH。6. 1 通过华友增值业务平台进行PUSH6.1.1接口描述CP/SP Server 调用华友移动增值业务管理平台WAP PUSH 的Web service 的接口，实现WAP PUSH 功能。CP/SP如果在业务中调用华友移动增值业务管理平台中的Push功能，CP/SP需要提出书面申请，申请通过后，才可以正常调用WAP Push的接口。6.1.2发起方系统CP/SP业务系统6.1.3接收方系统华友移动增值业务管理平台6.1.4 接口协议SOAP/HTTP。6.1.5访问控制机制只有通过认证的IP 地址才能调用该接口。 6.1.6调用函数pushMSG(fromUserMobile,toUserMobile,alertTitle,alertURL,needbilling);6.1.7接口形式 6.1.7.1 参数说明fromUserMobile 字符型说明：主叫号码，发送push 的手机号码。1. 如果CP/SP业务应用服务器未获得华友移动增值业务管理平台传送的手机号码，需向中国联通申请。2. 如果CP/SP业务应用服务器获得的为加密主叫号码（deviceid），可以直接使用deviceid来作为主叫号码，华友移动增值业务管理平台负责完成由diviceid到标准的手机号码的转换。3. 如果CP/SP业务应用服务器获得的为公开的主叫号码（X-up-calling-line-id），可以直接使用此主叫号码。toUserMobile 字符型说明：被叫号码，接收push 的手机号码，以133开头的11 位数或以86开头的13位数，支持同时发送给多个被叫号码，多个被叫号码之间用“,”隔开。alertTitle 字符型说明：用户在发送push 的时候输入的文字信息，不允许超过50个中文字符长度，由于大部分手机型号只支持UTF-8码，所以统一为UTF-8码。alertURL 字符型说明：需要push给被叫方的url。如果url中带有参数，要求使用”&”作为连接符。needBilling 布尔型说明：目前暂时未用，该参数目前统一为false。 6.1.7.2 返回值（1）如果发给1 个手机号码则返回：手机号码:状态码:状态信息（2）如果发给多个手机号码则返回：手机号码:状态码:状态信息|.|手机号码:状态码:状态信息手机号码：以133开头的11 位数或以86开头的13位数。状态码的详细说明如下：状态码说明-300其他错误-200user not support WAP or not access the Routed wap portal before!（漫游发送）-100user not support WAP or not access the Routed wap portal before! （本地发送）1000OK1001 Accepted for Processing2000Bad Request2001Forbidden2002Address Error2003Address Not Found2004Push ID Not Found2005Capabilities Mismatch2006Required Capabilities Not Supported2007Duplicate Push ID3000Internal Server Error3001Not Implemented3002Version Not Supported3003Not Possible3004Capability Matching Not Supported3005Multiple Addresses Not Supported3006Transformation Failure3007Specified Delivery Method Not Possible3008Capabilities Not Available3009Required Network Not Available3010Required Bearer Not Available4000Service Failure4001Service Unavailable5xxxMobile Client Aborted除-100、-200 和-300 为华友WAP 增值业务平台系统返回，其他返回值均为openwave 的ppg Server 返回。其中只有1000 和1001 是正确发送的情况。 6.1.7.3 service 地址web service 地址：http:/211.94.69.247/pushsender/services/PushSIServicePortwsdl 文件地址：http:/211.94.69.247/pushsender/services/PushSIServicePort?wsdlWSDL文档:Web Service描述语言（Web Services Descriptin Language，WSDL）文档，用于描述该Webservice所提供的服务的结构（包括方法名称，参数类型，返回类型）6.1.8 示例代码说明：该示例代码为SP开发调用此接口的程序代码，其中除华友移动增值业务管理平台提供的接口函数外，所调用的函数和类库均为SP开发的程序中自带的函数和类库，并不用调用华友移动增值业务管理平台的其他函数或者类库。public static void main(String args) String fromUserMobile= 13301331001 ; String toUserMobile= 13301338833; String alertTitle= 测试PUSH; String alertURL = http:/wap.uni- boolean needBilling = false; com.hs.wappush_generated.PushSIServicePortType binding; String result = ; try com.hs.wappush_generated.PushSIServiceRouter siRouter = new com.hs.wappush_generated.PushSIServiceRouter(); siRouter.PushSIServicePort_address = http:/xxxxxxxx/pushsender/services/PushSIServicePort; binding = siRouter.getPushSIServicePort(); result = binding.pushMSG(fromUserMobile , toUserMobile,alertTitle,alertURL,false); catch (javax.xml.rpc.ServiceException jre) System.out.println(-ServiceException at - + new java.util.Date()+ -); System.out.println(* ERROR - ServiceException ( + jre.getMessage() + ); result = jre.getMessage(); System.out.print(jre); catch (java.rmi.RemoteException re) System.out.println(-RemoteException at - + new java.util.Date()+ -); System.out.println(* ERROR - RemoteException ( + re.getMessage() + ); re.printStackTrace(); result = re.getMessage(); System.out.println( result); 6.1.9 注意事项由于PUSH Server的处理能力限制，对调用此接口的CP/SP有以下的注意事项：l 每次调用接口发送的PUSH信息不超过5条。l 调用接口频率不要超过每秒调用1次。l CP/SP不允许泄漏手机用户的资料。目前PUSH Server暂时还不能够处理用户漫游的的时候接受PUSH信息。6. 2通过综合业务接入管理平台进行PUSH此接口请参照中国联通增值业务综合管理及接入平台SP接口规范v1.1(WEB接口规范)。7. 关于获取手机用户的唯一标识CP/SP需要向中国联通提出申请，由中国联通在WAP业务管理系统中控制向CP/SP提供所提供服务的主域或IP地址传送手机用户唯一标识。1加密的手机号码：根据用户手机号码进行加密处理后的用户识别代码，与手机号码一一对应。中国联通WAP平台向CP Server（主域或IP地址）传送加密手机号码，CP Server获取该加密手机号码的方法为：在每次用户发送的请求http header中取“deviceid”。2公开的手机号码：中国联通WAP平台向CP Server（主域或IP地址）传送公开的手机号码，CP Server获取该公开手机号码的方法为：在每次用户发送的请求http header中取“x-up-calling-line-id”。（目前不对CP开放此权限）CP要获得以上两种手机用户标识信息，均需向中国联通业务管理部门提交申请。以上信息获得需要等待操作配置完成第二天才生效。8. 关于手机型号的参数获取方法CP/SP直接在http header中取“user-agent”。9. 用户归属地机构获取方法CP通过从HTTP HEADER中的Cookie部分取CUI参数值获取用户归属地信息。该CUI值代表城市编号（归属地）。例：CUI=438； 表示该用户为 内蒙古(省):呼和浩特 的用户。CUI值与归属省、地市对照关系见下表。省ID省名称城市ID城市名称CUI010内蒙古(省)101内蒙古(省):呼和浩特438 010内蒙古(省)102内蒙古(省):包头439 010内蒙古(省)103内蒙古(省):乌兰察布盟440 010内蒙古(省)104内蒙古(省):伊克昭盟441 010内蒙古(省)105内蒙古(省):巴彦卓尔盟442 010内蒙古(省)106内蒙古(省):乌海443 010内蒙古(省)107内蒙古(省):赤峰444 010内蒙古(省)108内蒙古(省):呼伦贝尔445 010内蒙古(省)109内蒙古(省):通辽446 010内蒙古(省)111内蒙古(省):锡林浩特447 010内蒙古(省)112内蒙古(省):哲里木盟448 010内蒙古(省)113内蒙古(省):兴安盟449 010内蒙古(省)114内蒙古(省):阿拉善盟(阿盟)450 010内蒙古(省)115内蒙古(省):呼盟451 010内蒙古(省)116内蒙古(省):集宁1221 010内蒙古(省)117内蒙古(省):东胜1222 010内蒙古(省)118内蒙古(省):临河1223 011北京(省)110北京(省):北京452 013天津(省)130天津(省):天津453 017山东(省)150山东(省):淄博454 017山东(省)151山东(省):滨州455 017山东(省)152山东(省):威海456 017山东(省)153山东(省):临沂457 017山东(省)154山东(省):日照458 017山东(省)155山东(省):潍纺459 017山东(省)156山东(省):东营460 017山东(省)157山东(省):枣庄461 017山东(省)158山东(省):济宁462 017山东(省)159山东(省):荷泽463 017山东(省)160山东(省):莱芜464 017山东(省)161山东(省):烟台465 017山东(省)166山东(省):青岛466 017山东(省)170山东(省):济南467 017山东(省)172山东(省):泰安468 017山东(省)173山东(省):德州469 017山东(省)174山东(省):聊城470 018河北(省)180河北(省):沧州471 018河北(省)181河北(省):唐山472 018河北(省)182河北(省):秦皇岛473 018河北(省)183河北(省):廊坊474 018河北(省)184河北(省):张家口475 018河北(省)185河北(省):邢台476 018河北(省)186河北(省):邯郸477 018河北(省)187河北(省):保定478 018河北(省)188河北(省):石家庄479 018河北(省)189河北(省):承德480 018河北(省)720河北(省):衡水481 019山西(省)190山西(省):太原482 019山西(省)191山西(省):晋中483 019山西(省)192山西(省):阳泉484 019山西(省)193山西(省):大同485 019山西(省)194山西(省):晋城486 019山西(省)195山西(省):长治487 019山西(省)196山西(省):运城488 019山西(省)197山西(省):临汾489 019山西(省)198山西(省):忻州490 019山西(省)199山西(省):朔州491 019山西(省)200山西(省):离石(吕梁)492 030安徽(省)300安徽(省):马鞍山493 030安徽(省)301安徽(省):蚌埠494 030安徽(省)302安徽(省):安庆495 030安徽(省)303安徽(省):芜湖496 030安徽(省)304安徽(省):六安497 030安徽(省)305安徽(省):合肥498 030安徽(省)306安徽(省):阜阳499 030安徽(省)307安徽(省):淮南500 030安徽(省)308安徽(省):铜陵501 030安徽(省)309安徽(省):巢湖502 030安徽(省)311安徽(省):宣城503 030安徽(省)312安徽(省):滁州504 030安徽(省)313安徽(省):宿州505 030安徽(省)314安徽(省):淮北506 030安徽(省)316安徽(省):黄山507 030安徽(省)317安徽(省):池州508 030安徽(省)318安徽(省):毫州1295 030安徽(省)318安徽(省):毫州10000000000016 031上海(省)310上海(省):上海509 034江苏(省)330江苏(省):无锡510 034江苏(省)334江苏(省):常熟511 034江苏(省)340江苏(省):南京512 034江苏(省)343江苏(省):镇江513 034江苏(省)346江苏(省):连云港514 034江苏(省)348江苏(省):盐城515 034江苏(省)349江苏(省):宿迁516 034江苏(省)350江苏(省):徐州517 034江苏(省)354江苏(省):淮安(淮阴)518 034江苏(省)358江苏(省):南通519 034江苏(省)430江苏(省):扬州520 034江苏(省)440江苏(省):常州521 034江苏(省)445江苏(省):泰州522 034江苏(省)450江苏(省):苏州523 036浙江(省)360浙江(省):杭州524 036浙江(省)362浙江(省):湖州525 036浙江(省)363浙江(省):嘉兴526 036浙江(省)364浙江(省):舟山527 036浙江(省)365浙江(省):绍兴528 036浙江(省)367浙江(省):金华529 036浙江(省)370浙江(省):宁波530 036浙江(省)468浙江(省):衢州531 036浙江(省)469浙江(省):丽水532 036浙江(省)470浙江(省):温州533 036浙江(省)476浙江(省):台州534 038福建(省)380福建(省):福州535 038福建(省)384福建(省):龙岩536 038福建(省)385福建(省):莆田537 038福建(省)386福建(省):宁德538 038福建(省)387福建(省):南平539 038福建(省)389福建(省):三明540 038福建(省)390福建(省):厦门541 038福建(省)395福建(省):漳州542 038福建(省)480福建(省):泉州543 050海南(省)501海南(省):海口544 050海南(省)502海南(省):三亚545 050海南(省)503海南(省):儋州546 051广东(省)510广东(省):广州547 051广东(省)520广东(省):湛江548 051广东(省)525广东(省):汕尾549 051广东(省)526广东(省):揭阳550 051广东(省)528广东(省):梅州551 051广东(省)530广东(省):佛山552 051广东(省)531广东(省):潮州553 051广东(省)533广东(省):潮阳554 051广东(省)535广东(省):清远555 051广东(省)536广东(省):肇庆556