中国电信动漫产品平台接口规范.doc

中国电信动漫产品平台接口规范中国电信动漫产品平台接口规范（试行）中国电信集团公司目 录目 录2前 言41适用范围52引用标准63术语、定义和缩略语74网络结构95手机动漫平台与客户端接口定义95.1接口定义约定95.2终端和平台交互流程示例115.3业务消息体约定125.4业务消息体大小约定135.4.1消息体长度约定：135.4.2数据压缩传输：135.5业务接口名称定义135.6响应结果码定义155.7业务接口定义165.7.1注册登录接口注册接口（register）客户端退出接口（quit）175.7.2个性化接口绑定用户帐户接口（adduserdata）获取个人信息接口（getprofile）个人信息更新接口（setprofile）客户端皮肤获取接口（getskinpkg）205.7.3内容信息同步接口内容列表获取接口（getcontentlist）内容详情获取接口（getcontentdetail）内容搜索接口（search）内容列表节点（content）内容详细信息节点（contentdetail）产品信息节点（product）255.7.4订购接口2获取内容产品信息接口（getcontentproductinfo）2订购内容接口（subscribecontent）2取消订购包月产品接口（unsubscribecontent）2获取已订购包月产品接口（getcatalogsubscriptionlist）2获取按次订购内容列表接口（getsubscriptionlist）285.7.5在线阅读接口2获取漫画分集内容接口（getchapterinfo）2添加书签接口（addbookmark）30删除书签接口（deletebookmark）30获取用户书签列表接口（getbookmark）3获取收藏内容列表接口（getfavorite）3添加收藏内容接口（addfavorite）3删除收藏内容接口（deletefavorite）335.7.6观看互动接口3获取评论接口（getcomment）3用户评论接口（submitcomment）3用户评分接口（markcontent）3推荐内容接口（recommendedcontent）3获取推荐列表接口（getrecommend）3删除推荐列表接口（deleterecommend）3获取公告接口（getbulletin）375.8drm数字版权保护接口定义385.8.1drm数字版权保护业务流程3手机客户端软件激活业务流程：3许可证获取业务流程3内容订购业务流程40版权重续业务流程4异常情况处理4恢复内容业务流程435.8.2drm加密体系445.8.3手机动漫客户端激活接口455.8.4许可证获取接口4产品许可证获取4内容许可证获取4获取产品许可证和内容许可证4许可证获取失败返回信息495.8.5http响应码说明495.8.6结果码result-code说明50附录a：ticket（许可证）50前 言本规范文档是中国电信动漫产品系列规范中的第三项。动漫产品系列规范包括以下几个规范：中国电信动漫产品业务规范中国电信动漫产品平台技术规范中国电信动漫产品平台接口规范中国电信动漫产品客户端规范中国电信动漫产品内容保护技术规范本规范解释权属于中国电信集团公司。本规范起草单位：中国电信股份有限公司上海研究院本规范主要起草人：1 适用范围本规范定义了中国电信动漫产品平台和中国电信其他产品基地、电信全国it系统、动漫产品客户端之间进行数据通信交互的接口。适用于向中国电信提供动漫产品系统设备的提供商，以及周边设备和与此相关的内容和服务提供商（cp/sp）。2 引用标准下列文件通过本文的参考而成为本规范的条款。凡是注日期的参考文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本文，凡是不注日期的参考文件，其最新版本适用于本文。【1】 中国电信动漫产品业务规范【2】 中国电信动漫产品平台技术规范【3】 中国电信动漫产品客户端技术规范3 术语、定义和缩略语下列术语、定义和缩略语适用于本标准：名词解释手机客户端安装在手机终端上通过与动漫产品平台进行数据交互，实现动漫下载和展示的客户端软件。手持阅读器/专用阅读终端带有无线接入模块，可连接至动漫产品平台，支持动漫内容的展现、订购、下载和阅读的专用手持式阅读设备。动漫产品平台指提供动漫产品核心业务能力的部分，提供动漫的管理、下载控制、用户管理、计费等功能。频道频道是对内容进行的一级分类。当用户进入首页界面或者内容导航界面时，看到的第一级内容导航分类就是频道。分栏分栏是内容组织的二级分类，与其关联的频道有关，不同的频道对应着不同的分栏。每个频道下有多个分栏，每个分栏只归属一个频道。分栏可以动态增加更多的层次。书项每个书项对应一本动漫作品，每个分栏下包含多个书项，同一个书项也可属于不同的分栏。内容项内容项是内容组织的最小计费单元。每个书项中可包含多个内容项。内容项是书项的子集。内容项在计费模式上存在试读收费两种类型。漫画以图片、动画为主的动漫作品。个人空间个人空间是指用户个人属性的集合，包括个人书签、个人书架、个人批注、个人帐户、个人设置等。个人空间同时存在于前后端，并保持更新同步。用户书签用户在阅读过程中主动加入的书签。系统书签系统在用户退出阅读时自动记录的书签。专区同一家cp/sp提供的内容打包。防盗链同一个url地址只允许授权用户下载，不允许非授权用户直接通过url访问。wap/web统一门户中国电信动漫业务的全国统一门户，分为wap和web两种。ceb中国电信电子书作品格式。由中国电信制定的动漫作品格式。cpcontent provider 专业内容提供商，为平台和用户提供动漫作品资源。cdmacode-divisionmultipleaccess码分多址接入ismpinegrated service management platform综合业务管理平台http hyper text transfer protocol 超文本传送协议。urluniform resource locator 统一资源定位。wapwireless application protocol无线应用协议。4 网络结构动漫平台nsagnmsc全国cp/sp全国结算其他基地brew平台终端自注册平台第三方支付平台客户端if1if2if3if4if5if6if7if8if9图4-1 动漫平台接口图手机动漫平台与其他网元的接口包括：1. if1：手机动漫平台与其他基地的接口；2. if2：手机动漫平台和全国cp/sp之间的接口，使用http或ftp；3. if3：手机动漫平台与brew平台的接口；4. if4：手机动漫平台与终端自注册平台的接口；5. if5：手机动漫平台与第三方支付平台的接口；6. if6：手机动漫平台与客户端之间的接口；7. if7：手机动漫平台与nmsc之间的接口； 8. if8：手机动漫平台与isag之间的接口；9. if9：手机动漫平台与全国结算平台的接口。5 手机动漫平台与客户端接口定义if6接口为手机客户端和手机动漫平台之间的接口，客户端通过此接口获取用户和内容信息，并且完成用户操作数据的上传。5.1 接口定义约定手机动漫平台终端门户接口消息协议栈如下图所示：图5-1 接口消息协议栈示意图接口消息采用http+xml方式，终端首先同手机动漫平台建立会话，平台在消息应答中通过cookie返回会话id，客户端在cookie中携带会话id继续进行其他接口消息交互。同时客户端需要在http header中增加以下字段信息：必选：必须携带的字段；可选：指在满足某些情况下，可以携带的信息，不满足条件的情况下，可以不携带相关信息。请求消息字段名称是否必选描述client-agent必选终端系统类型、终端屏幕大小（宽*高）和厂商自定义信息三部分组成，三部分之间用“/”分割，如：wince5.0/240*320/otherinfomationx-up-calling-line-id必选用户手机号码客户端需要通过ctwap接入点连接平台，该字段由wap网关前传user-id必选用户唯一标识，客户端首次启动时通过客户端注册接口获取；除客户端注册接口不需要该字段外，其他消息均需上报该字段信息。apiversion必选消息协议版本号，以本规范版本号定义为准，如：1.0.0content-type可选消息体类型，使用post方法上传数据时指定：application/xmlaccept-encoding可选支持的数据压缩传输格式，如：gzipcookie可选传递客户端和平台会话id客户端和平台未建立会话时，该字段不存在客户端和平台建立会话后，后续消息交互客户端必须携带该字段参数上报会话id该字段格式要求请参见http/1.1 rfc2616action必选调用接口名称平台在应答的http response header中包含以下字段信息：应答消息字段名称是否必选描述content-encoding可选如果客户端支持压缩传输，平台返回内容的压缩格式result-code必选客户端请求响应结果码，其中0表示成功，其他结果码表示对应的错误信息content-type可选消息体类型 application/xmlcontent-length可选应答消息长度，当平台应答消息包含消息体时需要指定消息体长度，不得使用chunked方式返回数据。set-cookie可选如果客户端请求中没有会话id或者会话id过期时，平台重新指定会话id该字段格式要求请参见http/1.1 rfc2616apiversion必选消息协议版本号，以本规范版本号定义为准，如：1.0.0timestamp必选平台当前系统时间，时间格式：yyyy-mm-dd hh:mm:ss如：2008-11-08 15:14:045.2 终端和平台交互流程示例图5-2 终端与平台交互流程流程说明：1. 终端启动时，向电信动漫平台发起登陆鉴权请求（终端首次启动时发起注册请求）；2. 电信动漫平台进行终端和用户合法性校验，验证通过后平台生成响应的会话信息；3. 平台将鉴权结果（result-code字段）和会话信息（set-cookie字段）返回终端；4. 终端保存会话信息用于后续其他消息的交互；5. 终端携带会话信息（cookie字段）和平台进行其他消息的交互。5.3 业务消息体约定1、 请求消息和应答消息体采用xml编码方式，xml格式采用w3c的1.0规范，字符编码采用utf-8。要求每个xml消息格式都是以起始。2、 消息格式采用xmlschema来定义，遵循/2001/xmlschema的国际标准。3、 请求消息体以作为根节点，应答消息体以作为根节点。如以下请求消息： v1.0.0 examplehashcode 4、 请求消息uri中如果包含参数需要采用utf-8编码并经过urlencode编码。5、 对响应消息的xml内容中包含复杂信息的字段，如站内消息内容包含内容的链接，则使用cdata语法表示，定义自定义标签用于标识特殊对象，自定义特殊标签对象定义如下：标签名标签参数说明标签描述contentcontentid：内容id内容信息标签，如：西游记 第一集chaptercontentid：内容idchapterid：章节id章节信息标签，如：第一章 白纸人 1 1 1234 2 false18912345678 2010-03-02 12:13:14 !cdata您的好荐您一部漫画七龙珠 5.4 业务消息体大小约定5.4.1 消息体长度约定：请求消息：小于4k;返回消息：小于8k;参数长度不做限定，只约定请求消息和返回消息的总体大小；5.4.2 数据压缩传输：当客户端支持数据压缩传输时，需要在请求的消息头的“accept-encoding”字段中指定压缩方式（gzip），如消息可以被压缩传输则平台将应答的数据报文进行压缩作为应答数据返回，content-length为压缩后的数据长度。详细可参见http/1.1 rfc2616。5.5 业务接口名称定义接口名称action定义如下：编号action接口描述客户端登陆注册register客户端注册接口quit客户端退出接口个性化adduserdata绑定用户帐户接口getprofile获取个人信息接口（包括积分，个人账户余额）updateprofile更新个人信息接口getskinpackage客户端皮肤获取接口内容信息同步getcontentlist获取分栏内容列表接口getcontentdetail获取内容详情接口search内容搜索接口在线阅读getchapterinfo获取漫画分集内容接口addbookmark添加书签接口deletebookmark删除书签接口getbookmark获取用户书签列表接口getfavorite获取收藏内容列表接口addfavorite添加收藏内容接口deletefavorite删除收藏内容接口业务订购getcontentproductinfo获取内容产品信息接口subscribecontent订购内容接口（包含多种订购方式）unsubscribecatalog取消订购包月分栏接口getsubscriptionlist获取按次订购内容列表接口getcatalogsubscriptionlist获取已订购包月栏目接口互动阅读getcomment获取评论接口submitcomment用户评论接口markcontent用户评分接口recommendedcontent推荐内容接口getrecommend获取推荐列表接口deleterecommend删除推荐接口getbulletin获取公告接口5.6 响应结果码定义响应结果码描述0成功2001协议版本不支持2002非法的用户标识2003非法的客户端2004非法的请求接口2005请求参数缺失2006无效的参数2007不支持的操作2008会话超时2009不支持的用户信息参数2010无效的手机号码2012无效的频道分栏标识2013无效的内容标识2014无效的排行榜类型2015无效的时间格式2016用户未订购2017重复的记录2018书签已存在2019内容已被收藏2020更新通知已预定2021更新通知未预定2022非法的用户状态2023业务订购失败2024业务取消订购失败2025没有内容的访问权限2026验证码错误或者验证码已过期2027用户操作已达到每日次数限制（推荐/赠送）2028用户操作已达到上限（收藏/书签）2028用户已投票2999其他客户端请求错误3001请求超时3002服务器忙3003服务器维护中3004服务器数据库异常3010服务器暂时不支持此功能31003199服务器自定义错误码3999其他服务器错误5.7 业务接口定义5.7.1 注册登录接口 注册登录接口（register）接口描述客户端首次启动，需要进行客户端注册，获取相关用户信息，以及欢迎页。注册成功后即自动登录。接口消息定义请求方法：get /portalapi?clientversion=xxx&clienthash=xxx&welpage参数名称是否必选数据类型描述长度clientversion是客户端版本clienthash是客户端hash摘要，用于验证客户端合法性clienthash=base64(md5(clientversion|客户端内置密码)welpage是binary是否显示欢迎页请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述registerrspresponse1无actionclientinforegisterrsp0.1无客户端需要升级时包含该节点updateversionclientinfo1string无客户端升级版本号updateurlclientinfo1string无客户端升级地址mustupdateclientinfo1boolean无是否强制升级updatemessageclientinfo0.1string无客户端升级加强特性描述信息，用于用户提示，允许为空userinforegisterrsp0.1无用户基本信息客户端需要强制进行版本升级时该节点为空useriduserinfo1string无用户唯一标识amountuserinfo1integer无用户当前余额pointuserinfo1integer无用户当前积分nicknameuserinfo1string无昵称homepageinforegisterrsp0.1无推送信息欢迎页数据sysbookmarklisthomepageinfo1.n上次观看内容系统书签bookmarkidsysbookmarklist1string无书签idtimesysbookmarklist1书签添加时间yymmddhhmmsschapteridsysbookmarklist1string无章节idchapternamesysbookmarklist1string无章节名称pageidsysbookmarklist1integer无书签页编号pushcontenthomepageinfo1content针对用户的推荐内容specialregisterrsp1主菜单专题栏目更新spcpicspecial1专题图片spcnamespecial1专题名称 客户端退出接口（quit）接口描述客户端退出接口接口消息定义请求方法：get /portalapi 请求消息体：参数名称父节点标识出现次数数据类型节点属性描述quitreqrequest1actionlashbookmarkquitreq1上报用户在线观看漫画的系统书签typelastbookmark1integer1：系统书签2：用户书签（此处强制为1）contentidlastbookmark1string内容idpageidlastbookmark1integer页编号响应消息：无，通过http header的响应结果码返回操作结果。5.7.2 个性化接口 绑定用户帐户接口（adduserdata）接口描述用户以非ctwap方式访问动漫平台，客户端发起短信注册的同时，客户端上报平台用户填写的用户名和密码。接口消息定义请求方法：post /portalapi 请求消息体：节点标识父节点标识出现次数数据类型节点属性描述adduserdatareqrequest1userdataadduserdatareq1usernameuserdata1string用户名（邮箱或其他手机号）passwrduserdata1string用户密码响应消息：无，通过http header的响应结果码返回操作结果。 获取个人信息接口（getprofile）接口描述获取个人信息接口消息定义请求方法：get/portalapi请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述getprofilerspresponseuserinfogetprofilersp1string无用户信息nicknameuserinfo1string无昵称mailuserinfo个人邮箱pointuserinfo1integer无用户积分amountuserinfo余额 个人信息更新接口（setprofile）接口描述更新个人信息接口消息定义请求方法：post/portalapi请求消息体：节点标识父节点标识出现次数数据类型节点属性描述setprofilereqrequest1userinfosetprofilereq1string用户信息nicknameuserinfo1string昵称mailuserinfostring个人邮箱响应消息：无，通过http header的响应结果码返回操作结果。 客户端皮肤获取接口（getskinpkg）接口描述获取客户端皮肤配色方案接口消息定义请求方法：get /portalapi请求消息体：无 响应消息：节点标识父节点标识出现次数数据类型节点属性描述getskinpkgrspresponse1无skinpkggetskinpkgrsp1.n无皮肤配色方案borderskinpkg1rgb值边框颜色textskinpkg1rgb值文字颜色focusskinpkg1rgb值焦点色buttonskinpkg1rgb值按钮背景色listbkgndskinpkg1rgb值栏目列表背景色pictureskinpkg1背景底纹图片descriptionskinpkg1无描述信息5.7.3 内容信息同步接口 内容列表获取接口（getcontentlist）接口描述获取当前内容子内容列表信息接口消息定义请求方法：get/portalapi?contentid=xxx& contentcount=xxx& offset=xxx参数名称是否必选数据类型描述长度contentid 是string当前选择的内容列表id 16contentcount 是integer请求的本内容列表中的内容个数，若需要全部取出则此字段写为08offset是integer需要显示的内容与第一条记录的偏移量8请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述getcontentlistrspresponse1无contentcount getcontentlistrsp1integer无请求的内容列表中包含的内容个数contentlistgetcontentlistrspcontent请求内容列表 内容详情获取接口（getcontentdetail）接口描述获取当前内容的详情接口消息定义请求方法：get /portalapi?contentid=xxx参数名称是否必选数据类型描述长度contentid 是string当前选择的内容列表id 16请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述getcontentdetailrspresponse1无contenttype getcontentdetailrsp1integer无内容contentdetailgetcontentdetailrspcontentdetail节目详细内容prevcontentidgetcontentdetailrspstring节目列表中前一个节目id，如是第一个，该字段为空nextcontentidgetcontentdetailrspstring节目列表中后一个节目id，如是最后一个，该字段为空productlistgetcontentdetailrspproduct可订购的产品列表，包括订购章节或者包月 内容章节获取接口（getchapter）接口描述获取每个内容id下的内容章节列表，包括漫画章节列表和动画分级列表接口消息定义请求方法：get /portalapi?contentid=xxx&start=xxx&count=xxx参数名称是否必选数据类型描述长度contentid 是string当前选择的内容列表id 16start否integer起始页编号count否integer需要显示的个数缺省使用平台默认配置请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述getchapterrspresponse1无totalcaptergetchapterrsp0/1无当前内容的漫画章节总数chapterlist getchapterrsp0/1.n无查询到的漫画章节列表chapteridchapterlist1无章节idseriesnumchapterlist1序号statuschapterlist1string鉴权信息表示章节的：免费、权限及是否可以收看状态。headurlchapterlist1无漫画章节首地址（依格式而定）downloadurlchapterlist1无下载地址totalvideogetchapterrsp0/1无当前内容的动画章节总数videolist getchapterrsp0/1.n无查询到的动画章节列表videoidvideolist1无视频内容idseriesnumchapterlist1序号statuschapterlist1string鉴权信息表示章节的：免费、权限及是否可以收看状态。smoothurlvideoliststring流畅版播放地址cleanurlvideoliststring清晰版播放地址 内容搜索接口（search）接口描述搜索平台中的动漫内容接口消息定义请求方法：get /portalapi请求消息体：节点标识父节点标识出现次数数据类型节点属性描述searchreqrequest1keywordsearchreq1string需要查询的关键字searchtypesearchreq1binary查询的内容类型使用二进制位描述搜索类型，“1”代表该类型有效，“0”表示该类型无效。字节位检索类型1分类检索2动画3漫画4资讯5我的动漫searchcountsearchreq1integer需要搜索的条数，0为全部获取offsetsearchreq1integer搜索结果中与第一条的偏移量响应消息：节点标识父节点标识出现次数数据类型节点属性描述searchrspresponse1无contentlist searchrsp1content无查询到的内容列表contentcountsearchrspcontentdetail查询到的内容条数resultdescsearchrspstring结果描述 搜索热点词获取接口（gethotword）接口描述获取当前搜索输入相关的热门搜索关键字接口消息定义请求方法：get /portalapi?keyword=xxx参数名称是否必选数据类型描述长度keyword 否string当前输入的搜索关键字 16请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述gethotwordrspresponse1无hotwordlistgethotwordrsp1string无相关热门关键词列表 内容列表节点（content）参数名称数据类型描述contentidinteger内容idnamestring内容名称contenttypeinteger内容类型1、 漫画2、 动画3、 专题4、 资讯5、 labeltype栏目类型请求栏目的时候才返回1. 分类2. 连载更新3. 最新入库4. 系统推荐5. 排行榜6. 相关内容leafflaginteger是否有叶节点0、 没有子内容列表1、 有子内容列表latesttimetime更新时间favoriateflgboolean是否已经收藏0、 没有收藏1、 已经收藏subscribeflgboolean是否已经订购0、 没有订购1、 已经订购levelflginteger评分等级（放在此处或者详情，跟随ui展示）0、等级11、等级22、等级33、等级4gridpicurlstring宫格图片地址listpicurlstring列表图片地址descstring内容描述clicktimesinteger被点击次数contentbminteger内容书签 内容详细信息节点（contentdetail）contentdetail类分为动画类、漫画类、产品类。动画类参数名称参数类型说明contentidinteger内容idparentidinteger所属剧集idnamestring内容名称descriptionstring内容简介finishboolean该产品包是否完成未完成，连载已完成currentprograminteger所属节目的级数programcountinteger所属节目总级数，finish为0时，该字段为空authorstring作者名称gridurlstring海报地址sumittimestring发布日期(yymmdd)durationinteger节目时长（hhmmss）statusboolean是否可用，鉴权没有权限（未曾订购）有权限bsmoothboolean该内容是否可用清晰版收看（drm）bclearboolean该内容是否可用流畅版收看（drm）bdownloadboolean该内容是否可下载（drm）recomlistcontent相关内容推荐（热词、相关级数、相关内容展示）keywordstring（1个或者多个）该级内容关联词语levelflginteger评分等级（放在此处或者详情，跟随ui展示）0、等级11、等级22、等级33、等级4clicktimeinteger该节目点击次数漫画类参数名称参数类型说明contentidinteger内容idparentidinteger所属父节点idnamestring内容名称descriptionstring内容简介finishboolean该产品包是否完成0、 未完成1、 连载已完成currentprograminteger所属节目的级数programcountinteger所属节目总级数，finish为0时，该字段为空authorstring作者名称gridurlstring封面图片地址sumittimestring发布日期(yymmdd)durationinteger节目时长（hhmmss）statusboolean是否可用，鉴权没有权限（未曾订购）有权限recomlistcontent相关内容推荐（热词、相关级数、相关内容展示）keywordstring（1个或者多个）该级内容关联词语levelflginteger评分等级（放在此处或者详情，跟随ui展示）0、等级11、等级22、等级33、等级4clicktimeinteger该节目点击次数systembmboolean是否有系统书签0、 没有系统书签1、 有系统书签systembmposinteger系统书签位置列表manualbmboolean是否有手动书签0、 没有手动书签1、 有手动书签manualbmposinteger手动书签位置列表 产品信息节点（product）参数名称数据类型描述productidinteger产品idproductnamestring产品名称feeinteger产品价格purchasetypeinteger计费类型0、免费1、按产品包订购2、 按次订购（按照使用次数进行计费，无需再次订购）3、 ppv（一次性计费，下次使用仍然计费）purchasetimestring产品购买时间yymmddhhmmssexpiretimestring产品过期时间yymmddhhmmssproductdescstring产品描述levelflginteger评分等级（放在此处或者详情，跟随ui展示）0、等级11、等级22、等级33、等级4gridpicurlstring宫格图片地址listpicurlstring列表图片地址purcheastimesinteger被购买次数5.7.4 订购接口 获取内容产品信息接口（getcontentproductinfo）接口描述客户端获取漫画资源的计费产品信息接口消息定义请求方法：get /portalapi?bookid=xxx&chapterid=xxx参数名称是否必选数据类型描述bookid是string书idchapterid否string话id，按话计费时必选请求消息体：无响应消息：节点标识父节点标识出现次数数据类型节点属性描述productinforspresponse1无产品信息，内容非免费时返回相应的内容资费描述信息。返回可订购产品的列表productli