# 接口规范

提供统一的访问入口，格式如下：

# 调用方式

 POST,GET

接口地址

https://api.yuewen.com/content/cp/ServiceBus.do

示例：

https://api.yuewen.com/content/cp/ServiceBus.do?service=CpNovel&action=bookinfo&CBID=22037867000124502&appKey=xxxxxxxxxx&appToken=xxxxxxxxx

# 请求通用参数

请求参数	是否必须	类型	说明
service	是	string	服务名称
action	是	string	相应的方法名称
appKey	是	string	Key 标志（参考阅文开放平台接入指南）
appToken	是	string	Key 密码 (参考通用签名算法）
<其他参数序列>	是	string	根据不同的 method 携带的参数信息

注：如果参数中涉及中文，需要先把中文转换为 UTF-8 编码，并对该编码后的中文进行 URL Encode

URL编码的示例代码（java）
value = java.net.URLEncoder.encode(value,"UTF-8")
并设置 Content-Type: header of application/x-www-form-urlencoded

# 通用签名算法

为了确保接口调用过程中的安全性，所有接口都需要携带 appToken，接口会根据请求参数，对签名进行验证，并拒绝签名不合法的请求，appToken 生成如下：

步骤	说明
1	取 appKey 的最后四位，后面加上 yyyyMMdd 格式的当日日期，组成字符串
2	用步骤 1 获取的字符串生成 MD5 值（32 位小写）
3	取生成的 MD5 值的前 12 位，即为 appToken

java 示例参考：

private static final  DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern("yyyyMMdd");
public String generateRequestToken(String appKey){
    if (org.apache.commons.lang3.StringUtils.isBlank(appKey)){
        return org.apache.commons.lang3.StringUtils.EMPTY;
       }
    try {
        String substring = appKey.substring(appKey.length() - 4);
        String dateFormat = DATE_TIME_FORMATTER.format(LocalDate.now());
        MessageDigest md = MessageDigest.getInstance("MD5");
        md.update((substring + dateFormat).getBytes(StandardCharsets.UTF_8));
        return new BigInteger(1, md.digest()).(16).substring(0, 12);
    }catch (Exception e){
           //do something
        return org.apache.commons.lang3.StringUtils.EMPTY;
    }
}

# 数据回传签名算法

为了确保接口调用过程中的安全性，数据回传 API 需要携带请求签名，接口会根据请求参数，对签名进行验证，并拒绝签名不合法的请求，签名过程如下：备注：获取 appflag 与 appsecret（参考阅文开放平台接入指南）

步骤	说明
1	本次调用接口请求参数的参数名(key)首字母以 ASCII 升序排列，首字母相同则从左往右使用下个字母，以此类推
2	排序后的结果按照参数名(key)参数值(value)进行拼接，不做任何编码，不添加其它字符（格式：key1value1key2value2…keyNvalueN）得到参数字符串 S1
3	在参数字符串 S1 头部拼接 appsecret，得到签名字符串 S2
4	对签名字符串 S2 使用 MD5 算法获取哈希值后转为大写，即为通用入参的 sign 值

各语言签名示例 (opens new window)

# 通用返回字段

返回信息：

字段名称	字段类型	说明	业务说明
returnCode	int	返回码	0 表示成功，其他表示失败
returnMsg	string	返回信息	返回信息描述
result	struct	结构体	业务数据信息

返回结果如下。

{
    "returnCode": 0,
    "returnMsg": "Success",
    "result": {
        "pageCount": 1,
        "resultData": [{
            "cBID": 20672206000949704,
            "cSVID": 212551,
            "cVID": 88786448708358100,
        }]
    }
}

# 通用错误码列表

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	书籍角色信息不存在

← 开发前必读 API 接口 →