1接口规范

1.1通信协议

平台采用HTTPS协议跟第三方应用交互，建议以POST方式请求，返回结果为JSON格式。

所有请求和响应数据编码皆为utf-8格式，请求的Content-Type请使用application/x-www-form-urlencoded。

1.2公共请求头参数

通用请求头（Headers）：

字段标识说明数据类型可空
X-Request-ID唯一值，随机生成，建议uuidStringN

1.3公共请求body参数

通用请求体（body）：

字段标识说明数据类型可空
appKey申请应用时分配的应用ID（APPID）StringN
timeStamp时间戳，单位毫秒LongN
accessToken获取accessToken接口返回的accessTokenLong除获取accessToken接口外，其余都不能为空
paras使用XXTea加密方式对接口定义的所有参数（除appKey,timeStamp,accessToken,sign）拼接后的字符串加密，如params=XXTea((e189AccessToken=xxx&参数2=xxx),                            appSecret)，其中appSecret是申请应用时平台生成的应用秘钥，参数拼接无顺序要求。1024N
signsign参数是对除sign外其他参数的RSA加密值，加密算法如下：sign=RSA(accessToken+appKey+paras+timeStamp, RSA_Private_key) 需要注意参数拼接key升序排序。其中RSA_Private_key是合作方的RSA私钥，合作方需要向开放平台提供RSA公钥，（请在“管理中心--我的应用--查看详情”中进行配置），公钥格式要求为：1024bit pkcs#8 格式，用于访问接口时的验签。具体rsa加密获得sign请查看https://id.dlife.cn/api?initialSrc=/html/api_detail_622.html中的RSAUtil和XXTeaUtil1024N

2天翼云盘用户信息查询

2.1获取用户基本信息

承载协议HTTPS
承载网络公网
请求方式POST
数据格式application/json;charset=UTF-8;响应数据以json格式返回
接口URL

https://api.cloud.189.cn/newOpen/user/getUserInfo.action

请求头： 参考1.2公共请求头参数


请求参数：

无

响应参数：

字段标识说明数据类型可空
res_code

错误码，0-成功，非0为失败

String

Y

res_message

错误码描述

String

Y

loginName

用户登录名

String

Y

capacity

用户存储总容量（字节）

Long

Y

available

剩余可用空间（字节）

Long

Y

maxFilesize

单个上传文件最大值（字节）

Long

Y

orderAmount

订购套餐金额(元)  0或空：普通用户，VIP套餐用户包含：5、10、20、30

Integer

Y

hasFamily

是否存在家庭云，1-存在，0-不存

Integer

Y

示例：

请求（代码参考附录1的getUserInfo方法）：

响应：

正常（状态码200）：

{

    "res_code": 0,

    "res_message": "成功",

    "available": 64424424296,

    "capacity": 64424509440,

    "extPicAvailable": 0,

    "extPicCapacity": 0,

    "extPicUsed": 0,

    "hasFamily": 1,

    "loginName": "18924296220@189.cn",

    "mail189UsedSize": 0,

    "maxFilesize": 4294967296,

    "orderAmount": 0,

    "provinceCode": "000000"

}

异常（状态码400）

{

    "res_message": "Internal error",

    "res_code": "InternalError"

}



2.2获取个人云和家庭云信息

承载协议HTTPS
承载网络公网
请求方式POST
数据格式application/json;charset=UTF-8;响应数据以json格式返回
接口URL

https://api.cloud.189.cn/newOpen/user/

getUserInfowithFamily.action

备注

若需要展示云盘剩余空间，需将个人云和家庭云的剩余空间加起来；若用户已使用空间用超，剩余空间字段会返回负数，合作方需自行处理这种情况

请求头： 参考1.2公共请求头参数


请求参数：无

响应参数：

字段标识说明数据类型可空
res_code

错误码，0-成功，非0为失败

String

Y

res_message

错误码描述

String

Y

loginName

用户登录名

String

Y

capacity

用户存储总容量（字节）

Long

Y

available

剩余可用空间（字节）

Long

Y

maxFilesize

单个上传文件最大值（字节）

Long

Y

orderAmount

订购套餐金额(元)  0或空：普通用户，VIP套餐用户包含：5、10、20、30

Integer

Y

extPicAvailable

铂金会员图片剩余空间（字节）

Long

Y

extPicCapacity

铂金会员图片总空间（字节）

Long

Y

extPicUsed

铂金会员图片已使用（字节）

Long

Y

familyAvailable

家庭云剩余空间（字节）

Long

Y

familyCapacity

家庭云总空间（字节）

Long

Y

familyId

家庭云id

Long

Y

familyMaxFilesize

家庭云文件传输最大值（字节）

Long

Y

示例：

请求（代码参考附录1的getUserInfo方法）：

响应：

正常（状态码200）：

{

    "res_code": 0,

    "res_message": "成功",

    "available": 64349037416,

    "capacity": 64424509440,

    "extPicAvailable": 0,

    "extPicCapacity": 0,

    "extPicUsed": 0,

    "familyAvailable": 6597069696618,

    "familyCapacity": 6597069766656,

    "familyId": 14969,

    "familyMaxFilesize": 4294967296,

    "loginName": "18924296220@189.cn",

    "maxFilesize": 4294967296,

    "orderAmount": 0,

    "provinceCode": "000000"

}

异常（状态码400）

{

    "res_message": "Internal error",

    "res_code": "InternalError"

}



2.3统计不通类型文件数

承载协议HTTPS
承载网络公网
请求方式POST
数据格式application/json;charset=UTF-8;响应数据以json格式返回
接口URL

https://api.cloud.189.cn/newOpen/xygj/getUserInfo.action

描述

包括个人云和家庭云总和，异步计算（数据存在延迟），本次请求获取上一次计算结果

请求头： 参考1.2公共请求头参数


请求参数：无

响应参数：

字段标识说明数据类型可空
res_code

错误码，0-成功，非0为失败

String

Y

res_message

错误码描述

String

Y

userInfo

用户信息

UserInfo

Y

userInfo:

字段标识说明数据类型可空

capacity

总空间，单位：B

Long

Y

usedSize

已使用空间，单位：B

Long

Y

familyId

家庭云ID

Long

Y

loginName

登录账号

String

Y

picCount

图片数量

Long

Y

videoCount

视频数量

Long

Y

docCount

文档数量

Long

Y



示例：

请求（代码参考附录1的getUserInfo方法）：

响应：

正常（状态码200）：

{

    "res_code": 0,

    "res_message": "成功",

    "userInfo": {

        "capacity": 4462471020544,

        "docCount": 0,

        "familyId": 14969,

        "loginName": "18924296220@189.cn",

        "picCount": 0,

        "usedSize": 75542062,

        "videoCount": 0

    }

}

异常（状态码400）

{

    "res_message": "Internal error",

    "res_code": "InternalError"

}



3错误码

3.1常用错误码列表

错误码描述HTTP状态码
AccessDenyOfHighFrequency由于访问频率过高，拒绝访问400 Bad Request
ErrorDownloadFileNotFound下载时文件不存在400 Bad Request
ErrorDownloadFileDeleted下载时文件已被删除400 Bad Request
ErrorDownloadFileInvalidParam下载时无效的下载参数400 Bad Request
ErrorDownloadFileInternalError下载时内部错误400 Bad Request
ErrorDownloadFileInvalidSessionKey下载时无效的sessionKey下载时无效的sessionKey
ErrorDownloadFileShareTimeOut下载时分享文件超时400 Bad Request
FileAlreadyExists文件或文件夹已存在400 Bad Request
FileNotFound文件或文件夹不存在400 Bad Request
FileTooLarge上传文件超过最大限制400 Bad Request
InsufficientStorageSpace剩余存储空间不足400 Bad Request
InternalError内部错误500 Internal Server Error
InvalidArgument非法参数400 Bad Request
InvalidPassword密码不正确400 Bad Request
InvalidParentFolder无效的父目录400 Bad Request
InvalidSessionKey非法登录会话Key400 Bad Request
InvalidSignature非法签名400 Bad Request
MoveFileValidError文件移动类型检查错误400 Bad Request
MyIDQRCodeNotLoginMyID二维码未登录400 Bad Request
MyIDSignatureVerfiyFailedMyID数字签名验证失败400 Bad Request
NoSuchUser用户账号不存在400 Bad Request
ParentNotFolder父文件夹类型不正确400 Bad Request
PermissionDenied访问权限不足400 Bad Request
QRCodeNotBind二维码未绑定400 Bad Request
QRCodeNotFound二维码不存在400 Bad Request
ServiceNotOpen云存储服务尚未开通400 Bad Request
UploadFileAccessViolation上传文件访问冲突400 Bad Request
UploadFileNotFound上传文件不存在400 Bad Request
UploadFileSaveFailed上传文件保存至云存储失败400 Bad Request
UploadFileVerifyFailed上传文件校验失败400 Bad Request
ShareSpecialDirError共享特殊目录400 Bad Request
SpecialDirShareError特殊目录分享400 Bad Request
BatchOperSuccessed批量操作部分成功400 Bad Request
BatchOperFileFailed批量操作失败400 Bad Request
ShareInfoNotFound没有找到分享信息400 Bad Request
InvalidUploadFileStatus无效的上传文件状态400 Bad Request
ShareOverLimitedNumber分享次数超限400 Bad Request
NotFoundPersonQuestion没有设置个人问题400 Bad Request
ShareOverLimitedNumber分享次数超限400 Bad Request
InfoSecurityErrorCode违反信安规则410 Bad Request
CopyFileOverLimitedSpaceError转存文件总大小超限400 Bad Request
CopyFileOverLimitedNumError转存次数超限400 Bad Request
InfosecuMD5CheckError违反信安规则400 Bad Request
ShareAuditNo/ShareAuditNotPass分享审核不通过400 Bad Request
TextAuditErrorCode敏感词检查不通过400 Bad Request
UserInvalidOpenToken无效的天翼账号Token400 Bad Request
CommonOperNotSupport操作不支持，建议升级版本400 Bad Request
PhotoNumOverLimited照片数量超限400 Bad Request
FileCopyToSubFolderError父目录拷贝或移动至自身子目录错误400 Bad Request
UserDayFlowOverLimited用户当日流量超过上限400 Bad Request
PayMoneyNumErrorCode支付金额有误400 Bad Request
UserOrderNotExists用户订单不存在400 Bad Request
CreateSaleOrderErrorCode创建用户订单异常400 Bad Request
ShareDumpFileNumOverLimited分享转存文件数超限400 Bad Request
ShareAuditWaiting分享审核中400 Bad Request
UploadSingleFileOverLimited上传单文件大小超限400 Bad Request
PrivateFileError异常操作私密空间文文件错误400 Bad Request
SpeedOrderRecordExist已经生成订购关系400 Bad Request
SpeedOrderRecordNotExist没有找到订购关系400 Bad Request
SpeedProdAlreadyOrder该宽带已订购该产品400 Bad Request
SpeedDialaccountNotFound找不到宽带账号400 Bad Request
SpeedNotGdBroadbandUser非广东宽带拨号用户400 Bad Request
SpeedUnOrder智能提速套餐未订购400 Bad Request
SpeedInfoNotExist智能提速套餐信息不存在400 Bad Request
SpeedInfoAlreadyExist智能提速套餐信息已存在400 Bad Request
UnSpeedUpError用户处于未提速状态400 Bad Request
NotOpenAccount手机号未创建天翼帐号400 Bad Request
ObjectIdVerifyFailedobjectId校验失败400 Bad Request
ErrorAccessCode分享访问吗错误400 Bad Request
ShareNotReceiver好友分享，访问者非接受者400 Bad Request
CommonInvalidSessionKey分享相关接口时，好友分享，需要登陆400 Bad Request
ParasTimeOutparas参数超时400 Bad Request
TokenAlreadyExist该天翼云盘已绑定400 Bad Request
PrivateFileErrorprivate space file400 Bad Request
FileStatusInvalidFMUserFile fileStatus is invalid400 Bad Request
ShareNotFoundFlatDir分享平铺目录未找到400 Bad Request
ShareDumpFileOverload分享转存文件数目超限400 Bad Request
ShareNotFound分享未找到400 Bad Request
ShareAccessOverload分享访问次数超限400 Bad Request
ShareCreateFailed分享创建失败400 Bad Request
ShareExpiredError分享已过期400 Bad Request
ShareFileNotBelong文件不属于当前分享文件或目录400 Bad Request
ShareCreateOverload用户创建分享次数超限400 Bad Request
AccountNoAccess出口ip不在白名单列表中400 Bad Request
ErrorLogin登录账号失败，paras只有1分钟有效，且只能请求一次400 Bad Request
InvalidAccessTokenAccessToken无效400 Bad Request

3.2REST错误响应

当出现错误时，HTTP响应包含以下Header信息：


HTTP响应码，3xx, 4xx, or 5xx

附录1：

获取AccessToken及获取用户基本信息代码Demo：

import java.util.HashMap;

import java.util.Map;

import java.util.UUID;

public class CloudUtil {

    //appKey和appSecret按实际修改，或改成配置中心保存

    private static final String APP_KEY = "test";

    private static final String APP_SECRET = "test";

    private static final String ACCEPT = "application/json;charset=UTF-8";

    private static final String DOMAIN = "https://api.cloud.189.cn";

    private static final String HOST = "api.cloud.189.cn";

 

    /**

     * 获取云盘AccessToken方法

     * @param e189AccessToken 天翼账号AccessToken，具体参考账号接口规范

     * @return

     */

    public static String getAccessToken(String e189AccessToken){

        String uri = "/newOpen/oauth2/accessToken.action";

        Map<String, Object> headerMap = new HashMap<>();

        headerMap.put("Accept", ACCEPT);

        Map<String, Object> parameterMap = new HashMap<>();

        long now = System.currentTimeMillis();

        parameterMap.put("appKey", APP_KEY);

        String params="e189AccessToken=test";

String paras=XXTeaUtils.encrypt(params,appSecret);

parameterMap.put("paras", paras);

String signParams=appKey+paras+timeStamp;

        String sign;

        try {

            String privateKey = "MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBANdd76EASulM9uHHSz5r9HQFrkBK8puiiX3l33jUq9aeUuF70D5qdWJ5WY3DfifY7eHmcSvAS+4IO7Om4IOAqSt7DqqwN/AE4SJGAeBOHH6lv1CRj3VQW2DVqH6F2dfHoUSCA0wvG4fCEGoJLB+N5Fn4QogAcBFiKSEs+w/riDctAgMBAAECgYAK9MZqBF/LOpUcq0zSoh9Pf7J7ptRswnoII5eYyAjt5CQHQIs5gaTzG4VIxvc2A70mTtjXBvNV6qlO3GBzkCoK6lP9Vrq/h4KoZcoZUjo/mjnpqthMdkzouFAIcGzTr+tVOIyqHGm4sTRkmN6yEg3z7XaJOQfgupRfwqtCjpf+gQJBAPCAphSv+ZMRg4Do5JjRbmmldqZFIQv4nvg4yGxkO4XYlgYyqzpCb4iyC3KF+49Rvi492tGIfEZ5Xwr2oJU9O5ECQQDlPqX0IkepsiRXQeak5PPxCvaUEMs8wW5iD/rdAmy/K/QPQBG/Q+TcYDo/yHfJIPf5viKybdIKP6BrzkjNa5vdAkEAgcEG2ZZvkhca2cvMuV4Usc7hiqc1Qx4ptkX8a+5P5tCJcGKZ2t7JCfj1EB6VMCer8YrRqcZ3NhZ5XpLc5Gea4QJBANNm1nswMY3X7ZNZ/mwJhru+NG2Onx1D85sSyXCOD+KrkcGOf881uRNQ2eZ/45bihEsWf8CzbYJt8m34KULl/TECQBI6/w3RhjmPq4rqo+AEDODC8J0jQpl+TlSzpz8KogE2LWyyofkVd3LWi2GZxE8O+xqYstlA4MrKxJQ2ZaGfVxg=";

            RSAPrivateKey rsaPrivateKey = RsaUtilWithSHA1.loadPrivateKey(privateKey);

            sign= RsaUtilWithSHA1.sign(signParams,rsaPrivateKey);

        } catch (Exception e) {

            throw new RuntimeException(e);

        }

        parameterMap.put("timestamp", now);

        parameterMap.put("sign", sign);

        return OKHttpUtil.doPost(DOMAIN + uri, headerMap, parameterMap);

    }

    /**

     * 获取用户基本信息

     * @param accessToken 云盘AccessToken

     * @return

     */

    public static String getUserInfo(String accessToken){

        String uri = "/newOpen/user/getUserInfo.action";

        long now = System.currentTimeMillis();

        Map<String, Object> headerMap = new HashMap<>();

        headerMap.put("X-Request-ID", UUID.randomUUID());

        Map<String, Object> parameterMap = new HashMap<>();

        parameterMap.put(“appKey”:appKey);

        parameterMap.put(“timeStamp”:timeStamp);

        parameterMap.put(“accessToken”:accessToken);

        parameterMap.put(“paras”:paras);  

        parameterMap.put(“sign”:sign);

 

        return OKHttpUtil.doPost(DOMAIN + uri, headerMap, parameterMap);

    }

}