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

中国电信动漫产品平台接口规范 （试行） 中国电信集团公司 中国电信动漫产品平台接口规范 2 目 录 目 录 . 2 前 言 . 4 1 适用范围 . 5 2 引用标准 . 6 3 术语、定义和缩略语 . 7 4 网络结构 . 9 5 手机动漫平台与客户端接口定义 . 9 5.1 接口定义约定 . 9 5.2 终端和平台交互流程示例 .11 5.3 业务消息体约定 . 12 5.4 业务消息体大小约定 . 13 5.4.1 消息体长度约定： . 13 5.4.2 数据压缩传输： . 13 5.5 业务接口名称定义 . 13 5.6 响应结果码定义 . 15 5.7 业务接口定义 . 16 5.7.1 注册登录接口 . 16 注册接口（ register） . 16 客户端退出接口（ quit） . 18 5.7.2 个性化接口 . 18 绑定用户帐户接口（ addUserData） . 18 获取个人信息接口（ getProfile） . 19 个人信息更新接口（ setProfile） . 19 客户端皮肤获取接口（ getSkinPkg） . 20 5.7.3 内容信息同步接口 . 21 内容列表获取接口（ getContentList） . 21 内容详情获取接口（ getContentDetail） . 21 内容搜索接口（ search） . 22 内容列表节点（ Content） . 24 内容详细信息节点（ ContentDetail） . 26 产品信息节点（ product） . 28 5.7.4 订购接口 . 28 获取内容产品信息接口（ getContentProductInfo） . 28 订购内容接口（ subscribeContent） . 29 取消订购包月产品接口（ unsubscribeContent） . 29 获取已订购包月产品接口（ getCatalogSubscriptionList） . 30 获取按次订购内容列表接口（ getSubscriptionList） . 31 5.7.5 在线阅读接口 . 32 获取漫画分集内容接口（ getChapterInfo） . 32 添加书签接口（ addBookmark） . 32 删除书签接口（ deleteBookmark） . 33 中国电信动漫产品平台接口规范 3 获取用户书签列表接口（ getBookmark） . 33 获取收藏内容列表接口（ getFavorite） . 35 添加收藏内容接口（ addFavorite） . 35 删除收藏内容接口（ deleteFavorite） . 36 5.7.6 观看互动接口 . 36 获取评论接口（ getComment） . 36 用户评论接口（ submitComment） . 37 用户评分接口（ markContent） . 38 推荐内容接口（ recommendedContent） . 38 获取推荐列表接口（ getRecommend） . 39 删除推荐列表接口（ deleteRecommend） . 39 获取公告接口（ getBulletin） . 40 5.8 DRM 数字版权保护接口定义 . 41 5.8.1 DRM 数字版权保护业务流程 . 41 手机客户端软件激活业务流程： . 41 许可证获取业务流程 . 42 内容订购业务流程 . 42 版权重续业务流程 . 43 异常情况处理 . 44 恢复内容业务流程 . 45 5.8.2 DRM 加密体系 . 46 5.8.3 手机动漫客户端激活接口 . 47 5.8.4 许可证获取接口 . 48 产品许可证获取 . 48 内容许可证获取 . 49 获取产品许可证和内容许可证 . 50 许可证获取失败返回信息 . 51 5.8.5 HTTP 响应码说明 . 51 5.8.6 结果码 result-code 说明 . 52 附录 A： Ticket（许可证） . 52 中国电信动漫产品平台接口规范 4 前 言 本规范文档是 中国电信 动漫产品系列规范中的第三项。 动漫产品系列规范包括以下几个规范： 中国电信动漫产品业务规范 中国电信动漫产品平台技术规范 中国电信动漫产品平台接口规范 中国电信动漫产品客户端规范 中国电信动漫产品内容保护技术规范 本规范解释权属于中国电信集团公司。 本规范起草单位：中国电信股份有限公司上海研究院 本规范主要起草人： 中国电信动漫产品平台接口规范 5 1 适用范围 本规范定义了中国电信动漫产品平台和中国电信其他产品基地、电信全国 IT 系统、动漫产品客户端之间进行数据通信交互的接口。适用于向中国电信提供动漫产品系统 设备的提供商，以及周边设备和与此相关的内容和服务提供商（ CP/SP）。 中国电信动漫产品平台接口规范 6 2 引用标准 下列文件通过本文的参考而成为本规范的条款。凡是注日期的参考文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本文，凡是不注日期的参考文件，其最新版本适用于本文。 【 1】 中国电信动漫产品业务规范 【 2】 中国电信动漫产品平台技术规范 【 3】 中国电信动漫产品客户端技术规范 中国电信动漫产品平台接口规范 7 3 术语、定义和缩略语 下列术语、定义和缩略语适用于本标准： 名词 解释 手机客户端 安装在手机终端上通过与动漫产品平台进行数据交互，实现动漫下载和展示的客户端软 件。 手持阅读器 /专用阅读终端 带有无线接入模块，可连接至动漫产品平台，支持动漫内容的展现、订购、下载和阅读的专用手持式阅读设备。 动漫产品平台 指提供动漫产品核心业务能力的部分，提供动漫的管理、下载控制、用户管理、计费等功能。 频道 频道是对内容进行的一级分类。当用户进入首页界面或者内容导航界面时，看到的第一级内容导航分类就是频道。 分栏 分栏是内容组织的二级分类，与其关联的频道有关，不同的频道对应着不同的分栏。每个频道下有多个分栏，每个分栏只归属一个频道。分栏可以动态增加更多的层次。 书项 每 个书项对应一本动漫作品，每个分栏下包含多个书项，同一个书项也可属于不同的分栏。 内容项 内容项是内容组织的最小计费单元。每个书项中可包含多个内容项。内容项是书项的子集。内容项在计费模式上存在试读收费两种类型。 漫画 以图片、动画为主的动漫作品。 个人空间 个人空间是指用户个人属性的集合，包括个人书签、个人书架、个人批注、个人帐户、个人设置等。个人空间同时存在于前后端，并保持更新同步。 用户书签 用户在阅读过程中主动加入的书签。 系统书签 系统在用户退出阅读时自动记录的书签。 专区 同一家 CP/SP 提供的内容打包。 防盗链 同一个 URL地址只允许授权用户下载，不允许非授权用户直接通过 URL访问。 中国电信动漫产品平台接口规范 8 WAP/WEB 统一门户 中国电信动漫业务的全国统一门户，分为 WAP 和 WEB 两种。 CEB 中国电信电子书作品格式。由中国电信制定的动漫作品格式。 CP Content Provider 专业内容提供商，为平台和用户提供动漫作品资源。 CDMA Code-DivisionMultipleAccess 码分多址接入 ISMP Inegrated Service Management Platform 综 合业务管理平台 HTTP Hyper Text Transfer Protocol 超文本传送协议。 URL Uniform Resource Locator 统一资源定位。 WAP Wireless Application Protocol 无线应用协议。 中国电信动漫产品平台接口规范 9 4 网络结构 图 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 接口定义约定 手机动漫平台终端门户接口消息协议栈 如下图所示： 动漫平台 NSAG NMSC 全国 CP / SP 全国结算 其他基地 Brew 平台 终端自注册平台 第三方支付平台 客户端 IF 1 IF 2 IF 3 IF 4 IF 5 IF 6 IF 7 IF 8 IF 9 中国电信动漫产品平台接口规范 10 TCP/IP底 层 承 载HTTP会 话 层业 务 消 息图 5-1 接口消息协议栈示意图 接口消息采用 HTTP+XML 方式，终端首先同手机动漫平台建立会话，平台在消息应答中通过 Cookie 返回会话 ID，客户端在 Cookie 中携带会话 ID 继续进行其他接口消息交互。 同时客户端需要在 HTTP Header 中增加以下字段信息： 必选：必须携带的字段； 可选：指在满足某些情况下，可以携带的信息，不满足条件的情况下，可以不携带相关信息。 请求消息 字段名称 是否必选 描述 Client-Agent 必选 终端 系统 类型、终端屏幕大小（宽 *高）和厂商自定义信息三部分组成，三部分之间用“ /”分割，如： WINCE5.0/240*320/OtherInfomation x-up-calling-line-id 必选 用户手机号码 客户端需要通过 ctwap 接入点连接平台，该字段由 WAP 网关前传 user-id 必选 用户唯一标识，客户端首次启动时通过客户端注册接口获取； 除客户端注册接口不需要该字段外，其他消息均需上报该字段信息。 APIVersion 必选 消息协议版本号，以本规范版本号定义为 准，如：1.0.0 Content-Type 可选 消息体类型，使用 POST 方法上传数据时指定： application/xml Accept-Encoding 可选 支持的数据压缩传输格式，如： gzip Cookie 可选 传递客户端和平台会话 ID 客户端和平台未建立会话时，该字段不存在 客户端和平台建立会话后，后续消息交互客户端必须携带该字段参数上报会话 ID 中国电信动漫产品平台接口规范 11 该字段格式要求请参见 HTTP/1.1 RFC2616 Action 必选 调用接口名称 平台在应答的 HTTP Response Header 中包含以下字段信息： 应答消息 字段名称 是否必选 描述 Content-Encoding 可选 如果客户端支持压缩传输，平台返回内容的压缩格式 result-code 必选 客户端请求响应结果码，其中 0 表示成功，其他结果码表示对应的错误信息 Content-Type 可选 消息体类型 application/xml Content-Length 可选 应答消息长度，当平台应答消息包含消息体时需要指定消息体长度，不得使用 chunked 方式返回数据。 Set-Cookie 可选 如果客户端 请求中没有会话 ID 或者会话 ID 过期时，平台重新指定会话 ID 该字段格式要求请参见 HTTP/1.1 RFC2616 APIVersion 必选 消息协议版本号，以本规范版本号定义为准，如： 1.0.0 TimeStamp 必选 平台当前系统时间，时间格式： yyyy-MM-dd HH:mm:ss 如： 2008-11-08 15:14:04 5.2 终端和平台交互流程示例 终 端 电 信 动 漫 平 台终 端 登 陆 鉴 权 请 求鉴 权 通 过 并 产 生 会 话鉴 权 请 求 响 应终 端 保 存 会 话 信 息终 端 携 带 会 话 信 息 请 求 其 他 消 息其 他 消 息 应 答图 5-2 终端与平台交互流程 流程说明： 1. 终端启动时，向电信动漫平台发起登陆鉴权请求 （终端首次启动时发起注册请求）； 中国电信动漫产品平台接口规范 12 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、 请求消息体以 作为根节点，应答消息体以 作为根节点。如以下请求消息： 4、 请求消息 URI 中如果包含参数需要采用 UTF-8 编码并经过 URLEncode 编码。 5、 对响应消息的 XML 内容中 包含复杂信息的字段，如站内消息内容包含内容的链接，则使用 CDATA 语法表示，定义自定义标签用于标识特殊对象，自定义特殊标签对象定义如下： 标签名 标签参数说明 标签描述 content contentid：内容 ID 内容信息标签，如： 西游记 第一集 chapter contentid：内容 ID chapterid：章节 ID 章节信息标签，如： 第一章 白纸人 V1.0.0 examplehashcode 中国电信动漫产品平台接口规范 13 5.4 业务消息体大小约定 5.4.1 消息体长度约定： 请求消息：小于 4K； 返回消息：小于 8K； 参数长度不做限定，只约定请求消息和返回消息的总体大小； 5.4.2 数据压缩传输： 当客户端支持数据压缩传输时，需要在请求的消息头的“ Accept-Encoding”字段中指定压缩方式（ gzip），如消息可以被压缩传输则平台将应答的数据报文进行压缩作为应答数据返回， Content-Length 为压缩后的数据长度。详细可参见 HTTP/1.1 RFC2616。 5.5 业务接口名称定义 接口名称 Action 定义如下： 1 1 1234 2 false18912345678 2010-03-02 12:13:14 七龙珠 中国电信动漫产品平台接口规范 14 编号 Action 接口描述 客户端登陆注册 register 客户端注册接口 quit 客户端退出接口 个性化 addUserData 绑定用户帐户接口 getProfile 获取个人信息接口（包括积分，个人账户余 额） updateProfile 更新个人信息接口 getSkinPackage 客户端皮肤获取接口 内容信息同步 getContentList 获取分栏内容列表接口 getContentDetail 获取 内容详情接口 search 内容搜索接口 在线阅读 getChapterInfo 获取漫画分集内容接口 addBookmark 添加书签接口 deleteBookmark 删除书签接口 getBookmark 获取用户书签列表接口 getFavorite 获取收藏内容列表接口 addFavorite 添加收藏内容接口 deleteFavorite 删除收藏内容接口 业务订购 getContentProductInfo 获取内容产品信息接 口 subscribeContent 订购内容接口（ 包含多种订购方式 ） unsubscribeCatalog 取消订购包月分栏接口 getSubscriptionList 获取按次订购内容列表接口 getCatalogSubscriptionList 获取已订购包月栏目接口 互动阅读 getComment 获取评论接口 submitComment 用户评论接口 中国电信动漫产品平台接口规范 15 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 非法的用户状态 中国电信动漫产品平台接口规范 16 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|客户端 中国电信动漫产品平台接口规范 17 内置密码 ) welPage 是 Binary 是否显示欢迎页 请求消息体： 无 响应消息： 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 RegisterRsp Response 1 无 Action ClientInfo RegisterRsp 0.1 无 客户端需要升级时包含该节点 updateVersion ClientInfo 1 String 无 客户端升级版本号 updateURL ClientInfo 1 String 无 客户端升级地址 mustUpdate ClientInfo 1 Boolean 无 是否强制升级 updateMessage ClientInfo 0.1 String 无 客户端升级加强特性描述信息，用于用户提示，允许为空 UserInfo RegisterRsp 0.1 无 用户基本信息 客户端需要强制进行版本升级时该节点为空 userID UserInfo 1 String 无 用户唯一标识 amount UserInfo 1 Integer 无 用户当前余额 point UserInfo 1 Integer 无 用户当前积分 nickName UserInfo 1 string 无 昵称 homepageInfo RegisterRsp 0.1 无 推送信息 欢迎页数据 sysBookmarkList homepageInfo 1.n 上次观看内容系统书签 bookmarkId sysBookmarkList 1 String 无 书签 ID Time sysBookmarkList 1 书签添加时间 yymmddhhmmss chapterId sysBookmarkList 1 String 无 章节 ID chapterName sysBookmarkList 1 String 无 章节名称 pageId sysBookmarkList 1 Integer 无 书签页编号 pushContent homepageInfo 1 Content 针 对用户的推荐内容 Special RegisterRsp 1 主菜单专题栏目更新 spcPic Special 1 专题图片 中国电信动漫产品平台接口规范 18 spcName Special 1 专题名称 客户端退出接口（ quit） 接口描述 客户端退出接口 接口消息定义 请求方法： GET /portalapi 请求消息体： 参数名称 父节点标识 出现次数 数据类型 节点属性 描述 quitReq Request 1 Action lashBookmark quitReq 1 上报用户在线观看漫画的系 统书签 type lastBookmark 1 Integer 1：系统书签 2：用户书签 （此处强制为 1） contentId lastBookmark 1 String 内容 id pageId lastBookmark 1 Integer 页编号 响应消息： 无，通过 HTTP header 的响应结果码返回操作结果。 5.7.2 个性化接口 绑定用户帐户接口 （ addUserData） 接口描述 用户以非 CTWAP 方式访问动漫平台，客户端发起短信注册的同时，客户端上报平台用户填写的用户名和密码。 接 口消息定义 请求方法： POST /portalapi 请求消息体： 中国电信动漫产品平台接口规范 19 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 AddUserDataReq Request 1 userData AddUserDataReq 1 userName userData 1 String 用户名（邮箱或其他手机号） passWrd userData 1 String 用户密码 响应消息： 无，通过 HTTP header 的响应结果码返回操作结果。 获取个人信息接口（ getProfile） 接口描述 获取个人信息 接口消息定义 请求方法： Get/portalapi 请求消息体： 无 响应消息： 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 getProfileRsp Response UserInfo getProfileRsp 1 string 无 用户信息 nickName UserInfo 1 string 无 昵称 Mail UserInfo 个人邮箱 point UserInfo 1 Integer 无 用户积分 amount UserInfo 余额 个人信息更新接口 （ setProfile） 接口描述 更新 个人信息 接口消息定义 中国电信动漫产品平台接口规范 20 请求方法： POST/portalapi 请求消息体： 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 setProfileReq Request 1 UserInfo setProfileReq 1 string 用户信息 nickName UserInfo 1 string 昵称 Mail UserInfo string 个人邮箱 响应消息： 无，通过 HTTP header 的响应结果码返回操作结果。 客户端皮肤获取接口（ getSkinPkg） 接口描述 获取 客户端 皮肤配色方案 接口消息定义 请求方法： GET /portalapi 请求消息体： 无 响应消息： 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 GetSkinPkgRsp Response 1 无 skinPkg GetSkinPkgRsp 1.n 无 皮肤配色方案 border skinPkg 1 Rgb 值 边框 颜色 text skinPkg 1 Rgb 值 文 字 颜色 focus skinPkg 1 Rgb 值 焦点 色 button skinPkg 1 Rgb 值 按钮 背景色 listBkgnd skinPkg 1 Rgb 值 栏目列表 背景色 picture skinPkg 1 背景底纹图片 description skinPkg 1 无 描述信息 中国电信动漫产品平台接口规范 21 5.7.3 内容信息同步 接口 内容列表获取接口 （ getContentList） 接口描述 获取当前内容子内容列表信息 接口消息定义 请求方法： GET/portalapi?ContentID=xxx& ContentCount=xxx& Offset=xxx 参数名称 是否必选 数据类型 描述 长度 ContentID 是 String 当前选择的内容列表 ID 16 ContentCount 是 Integer 请求的本内容列表中的内容个数，若需要全部取出则此字段写为 0 8 Offset 是 Integer 需要显示的内容与第一条记录的偏移量 8 请求消息体： 无 响应消息： 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 GetContentListRsp Response 1 无 ContentCount GetContentListRsp 1 Integer 无 请求的内容列表中包含的内容个数 ContentList GetContentListRsp Content 请求内容列表 内容详情获取接口 （ getContentDetail） 接口描述 获取当前内容的详情 接口消息定义 请求方法： GET /portalapi?ContentID=xxx 中国电信动漫产品平台接口规范 22 参数名称 是否必选 数据类型 描述 长度 ContentID 是 String 当前选择的内容列表 ID 16 请求消息体： 无 响应消息： 节点标识 父节点标识 出现次数 数据类型 节点属性 描述 GetContentDetailRsp Response 1 无 ContentType GetContentDetailRsp 1 Integer 无 内容 ContentDetail GetContentDetailRsp ContentDetail 节目详细内容 PrevContentID GetContentDetailRsp String 节目列表中前一个节目 ID，如是第一个 ，该字段为空 NextContentID GetContentDetailRsp String 节目列表中后一个节目 ID，如是最后一个，该字段为空 ProductList GetContentDetailRsp Product 可订购的产品列表，包括订购章节或者包月 内容章节获取接口 （ getChapter） 接口描述 获取每个内容 ID 下的 内容章节列表，包括漫画章节列表和动画分级列表 接口消息定义 请求方法： GET /portalapi?ContentID=xxx&start=xxx&count=xxx 参数名称 是否必选 数据类型 描述 长度 ContentID 是 String 当前选择的内容列表 ID 16 start 否 Integer 起始页编号 count 否 Integer 需要显示的个数 缺省使用平台默认配置 中国电信动漫产品平台接口规范 23 请求消息体： 无 响应消息： 节点标识 父节点标识 出现次数