# 接口规范
# 调用方式
请求方式：GET、POST
请求地址：
| 接入类型 | 请求地址 |
|---|---|
| 接入点 1 | https://cpapi-i.yuewen.com/api/v1/ |
| 接入点 2 | https://cpapi-n.yuewen.com/api/v1/ |
接入点 1 支持动态 CDN 的就近接入能力，速度优于接入点 2，请优先使用，如果接入点 1 出现故障，请路由至接入点 2。
请求头：
| 说明 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Content-Type | string | 是 | application/x-www-form-urlencoded |
请求和响应的字符集编码均为 UTF-8
# 请求通用参数
通用入参：以下参数在所有接口调用均需传入，各接口不再重复说明。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| appflag | string | 是 | 接入方唯一标识，在阅文开放平台获取的 appflag（参考阅文开放平台接入指南 ） |
| timestamp | int | 是 | 服务器当前 unix 时间戳（秒），接口允许时间差为 ±300 秒 |
| sign | string | 是 | 签名（参考签名算法） |
# 通用返回字段
通用出参：以下参数在所有接口返回值中均存在，各接口不再重复说明。
| 参数 | 类型 | 说明 | 业务说明 |
|---|---|---|---|
| code | int | 返回码 | 业务状态码，0 为成功，其它参考错误码列表 |
| msg | string | 返回信息 | 业务状态码对应的信息 |
| data | any | 结构体 | 各接口返回对象 |
# 签名算法
为了确保接口调用过程中的安全性，所有接口都需要携带请求签名，接口会根据请求参数，对签名进行验证，并拒绝签名不合法的请求，签名过程如下： 备注：获取 appflag 与 appsecret（参考阅文开放平台接入指南）
| 步骤 | 说明 |
|---|---|
| 1 | 本次调用接口请求参数（包含通用参数与业务参数但不包含 sign 参数）的参数名(key)首字母以 ASCII 升序排列，首字母相同则从左往右使用下个字母，以此类推 |
| 2 | 排序后的结果按照参数名(key)参数值(value)进行拼接，不做任何编码，不添加其它字符（格式：key1value1key2value2…keyNvalueN）得到参数字符串 S1 |
| 3 | 在参数字符串 S1 头部拼接 appsecret，得到签名字符串 S2 |
| 4 | 对签名字符串 S2 使用 MD5 算法获取哈希值后转为大写，即为通用入参的 sign 值 |
# 常见错误码列表
| returnCode | returnMsg |
|---|---|
| 0 | Success |
| -1 | 时间跨度太大，不要超过两天（书籍更新与书籍下架接口） |
| -3 | 参数错误 |
| -4 | 无法获取 epub 文件 |
| -1000 | 对应书籍不存在 |
| -1001 | 未查到评分信息 |
| -1002 | 未查到评分信息 |
| -1004 | 未知错误 |
| -1007 | 过滤规则未配置 |
| -1008 | 该书籍已下架 |
| -2001 | key 验证未通过 |
| -2002 | 接口未上线 |
| -2003 | 无接口访问权限 |
| -2004 | 无接入信息 |
| -2005 | 无接入控制信息或处于终止状态 |
| -2006 | IP 无访问权限 |
| -2007 | 当前时间只能为测试状态 |
| -2008 | 接口调用频率过高 |
| -2009 | 接口内部错误 |
| -2023 | 书籍角色信息不存在 |