ICP接口规范.doc

ICP接口规范 APTECH
Confidential

网上购物消费平台
ICP接口规范

Version:1.0.0
Update: 2003/12/19

目 录
1 引言 3
1.1 编写目的 3
1.2 范围 3
1.3 参考资料 3
1.4 名词缩写 3
2 ICP服务内容、结构要求 3
2.1 服务内容 3
2.2 用户要求 4
2.3 组织结构 4
2.4 价格标识 4
3 ICP允许的计费方案 4
4 与ICP的通信流程 5
4.1 Http接口 5
4.2 Http接口各函数实现 8
4.2.1 EJB接口位置及访问名 8
4.2.2 用户身份认证 8
4.2.3 支付能力确认 8
4.2.4 账单传送 9
4.2.5 返回信息描叙 9

北大青鸟 第 9 页 / 共 9 页
1 引言
1.1 编写目的
本规范的目的是明确接入增值平台的ICP需要满足的条件，定义ICP如何与增值平台通信，能够采用的计费方式，以及如何对账、结算等。

1.2 范围
适用于IP增值业务管理平台管理方、建设方的所有人员，以及所有希望接入此平台的ICP开发商。

1.3 参考资料
1.4 名词缩写
SP
Service Provider
服务提供商

2 ICP服务内容、结构要求
2.1 服务内容
ICP必须提供服务内容清单，包括：
服务名称、类型
服务栏目
计费方式、价格
是否包月

增值平台将每一个ICP服务定义为一个栏目，然后将栏目对应的栏目代码返回给ICP，让ICP填入到用户访问详单。
ICP提供的内容可以属于新闻、流媒体、游戏、在线教育、软件下载等。增值平台对游戏的支持目前仅限于购买游戏服务。
2.2 用户要求
ICP应提供书面说明，明确对用户的要求，如浏览器、视频播放器类型、版本，由增值平台加以说明。如果ICP对用户使用的软件有特殊要求，需要在显目位置提供下载的连接和相关说明。
作为一个基本要求，ICP应支持用户使用目前最流行的浏览器和播放器访问，包括：
Microsoft IE 5.0及以上版本
MediaPlayer 7.0及以上版本
RealPlayer 8.0及以上版本

2.3 组织结构
ICP应该以栏目的方式组织自己的服务。同一个栏目提供的服务都属于同一种类型，如视频点播或新闻；同一个栏目下的所有服务和商品价格都相同。

2.4 价格标识
ICP应明确标出自己每一个栏目的价格，一个栏目下的商品价格必须相同。ICP应定期提供一份价格清单表给增值平台，作为计费依据。ICP提供的价格必须与自己网页上标示价格保持一致。ICP修改价格需要与增值平台协商，双方同意才能修改。增值平台在计费时以ICP提供的价格清单为准。

3 ICP允许的计费方案
增值平台目前允许ICP采用的计费方式为：1+X方式。
1表示包月。对于任何一种服务类型，包括流媒体、新闻、游戏等，都提供包月的支持。
X表示3选一，从按次、按流量、按时长任选一种方式作为用户没有申请包月时的计费方式。

ICP应提供计费标准，格式如下：
栏目代码：如果为URL，由ICP决定；如果为代码，由增值平台给出。
栏目名称：栏目的描叙，如九州影院。
计费方式为按次计费、按流量计费、按时长计费三种任选一种。
栏目价格：计次价格、计流量价格(单位为M)、计时长价格(单位为分钟)。如果计费方式为按时长或流量，还需给出单个影片起始消费的最低余额，在冻结该最低余额对应货币后用户才能访问。
栏目是否允许包月及包月价格。

目前仅提供对栏目包月的支持。对于一个ICP有多个栏目，每个栏目可以包月，所有栏目也可以包月的情况，暂不考虑。

4 与ICP的通信流程
增值平台与ICP通信实现的主要功能有：用户认证、用户编码获取、支付能力确认、账单传送。
实现技术为Http，Http方式为ICP通过Web请求访问IP增值平台实现。
用户认证：增值平台用户访问ICP时，都会携带一个增值平台发送的网票(Session_id) 。ICP通过传递用户网票到增值平台认证，确认用户合法性。
用户编码获取：如果ICP需要取得访问用户的编码，记录到自己的账单中，准备在将来与增值平台对帐，可以通过用户编码获取，取得用户公开编码。也可以通过订单号对帐。
支付能力确认：在用户获得服务前，ICP需要认证用户是否能够支付该项服务。
账单传送：在用户获得服务后，ICP传递账单给增值平台。

4.1 Http接口
1. 用户登录增值平台网站,输入账号名、密码登录；

2. 用户在增值平台网站点击ICP的连接，访问ICP网站。然后跳转到第4步
在ICP连接的URL后面付带了增值平台发给用户的网票，格式为：http://<ICP_auth_url>?ISP_ID=hunan&session_id=<Ticket>
其中：ICP_auth_url为ICP的认证URL，它截取附在url后的用户信息，然后转发给增值平台认证
ISP_ID 为增值平台标志，表示为增值平台联接过来的用户。
session_Id为Ticket(网票)，当用户登录时有系统随机生成

3. 或者用户直接访问ICP，ICP将用户引导到增值平台认证页面，认证通过后返回ICP。这种方式下增值平台提供的认证连接为：http://<sp_login_url>?参数1
参数如下：
return_url 认证成功后返回到到ICP位置
sp_login_url：http://wsgwpt/SpWebGate/SpWebLogin.jsp

4. 用户被引导回ICP，并购买服务，ICP到增值平台认证用户身份、支付能力
认证连接:http://<wsgwpt_service_auth_url>?参数1&参数2&…
参数如下：
return_url 返回连接 String
icp_id ICP代码 String
serv_id 栏目名称 String
service_name 服务(商品)名称 String
amount 数量 String
request_time 请求时间 String YYYYMMDDHHMISS
session_id session_id String
client_ip 客户的IP String
order_id ICP的流水号 String
md 加密时戳 String

wsgwpt_service_auth_url: http://wsgwpt/SpWebGate/SpWebServiceAuth.jsp

5. 增值平台将认证结果返回给ICP：http://<return_url >?result_code=&result_info=&md=。
6. ICP允许用户享受服务。
7. ICP发送实际扣款请求：
扣款连接:http://<wsgwpt_service_commit_url>?参数1&参数2&…
参数如下：
return_url ICP扣款请求返回连接 String
icp_id ICP代码 String
serv_id 栏目名称 String
service_name 服务(商品)名称 String
amount 数量 String
service_time 服务时间 String YYYYMMDDHHMISS
session_id session_id String
client_ip 客户的IP String
order_id ICP的流水号 String
md 加密时戳 String

wsgwpt_service_commit_url: http://wsgwpt/SpWebGate/SpWebServiceCommit.jsp

8. ICP返回扣款结果
ICP提供扣款结果返回联接：http://<return_url>?result_code=<result_code>&result_info=<result_info>&md=.

9. 如果ICP需要用户公开编码，执行下叙连接
http://<isp_get_pub_use_id_url>?参数1=&参数2=&参数3=…
参数如下：
return_url ICP接收用户公开编码的连接
session_id 需要取得用户公开编码的网票
client_ip 用户使用的网络地址
md MD加密字串

wsgwpt_get_pub_use_id_url:http://wsgwpt/SpWebGate/SpWebPubUserId.jsp

10. 返回用户公开编码
http://<return_url>?pub_user_id=&result_code=&result_info=&md=
参数如下：
pub_user_id 用户公开编码
result_code 结果代码
result_info 错误描述
md 加密字串

注：以上所有URL中传递的属性名/值对，属性名都为小写。

备注：所有的result_code代码描述如下：
0 成功
-1 系统故障
-2 数据库故障
-3 网票不存在
-4 用户网票与使用的网络地址不匹配
-5 用户不存在
-6 用户状态异常，可能被冻结、注销或其他
-7 账面余额不足
-8 消费达到日限额
-9 请重新登录
-10 申请服务不存在
-11 ICP停止服务
-12 服务价格错误

4.2 Http接口各函数实现
4.2.1 EJB接口位置及访问名
EJB接口服务器地址：xx.xx.xx.xx
EJB接口访问名：IcpGate

4.2.2 用户身份认证
public int authSession(String inSessionID,String inUserIP)；
inSessionId 用户网票
inUserIp 用户网络地址
如果成功，返回0，其他返回代码参见《返回信息章节》

4.2.3 支付能力确认
public int requestService(String icpId,String servId,String serviceName,String sessionID,String clientIP,int amount,String orderId);
icpId ICP代码
servId 栏目代码
serviceName 服务名称
sessionID 用户网票
clientIP 用户网络地址
amount 购买服务(商品)数量
orderId ICP提供的订单号

返回代码参见《返回信息章节》
4.2.4 账单传送
public int commitService(String icpId,String servId,String serviceName,String sessionID,String clientIP,String serviceTime,int amount,String orderId)
serviceTime 服务完成时间，格式 YYYYMMDDHH24MISS
返回代码参见《返回信息章节》

4.2.5 返回信息描叙
result_code代码描叙：
0 成功
-1 系统故障
-2 数据库故障
-3 网票不存在
-4 用户网票与使用的网络地址不匹配
-5 用户不存在
-6 用户状态异常，可能被冻结、注销或其他
-7 账面余额不足
-8 消费达到日限额
-9 请重新登录
-10 申请服务不存在
-11 ICP停止服务
-12 服务价格错误