接口服务接入指南

基于 HTTP 协议调用 API，基本调用流程为：

根据 API 填充参数生成签名拼装 HTTP 请求发起 HTTP 请求获取 HTTP 响应解析 json 结果

签名算法公共参数正确返回结果错误返回结果通用应答码请求示例

签名算法

在 HTTP 请求中需发送 Token 字段，Token 字段为将 AppId、Nonce、SecretKey 和TimeStamp 加密后的签名内容。签名算法为 lowercase(md5(AppId+Nonce+SecretKey+TimeStamp))

* 注意：如果用户的请求方法是 GET，或者请求方法为 POST 同时 Content-Type 为 application/x-www-form-urlencoded，则发送请求时所有请求参数的值均需要做 URL 编码，参数键和=符号不需要编码。非 ASCII 字符在 URL 编码前需要先以 UTF-8 进行编码。

* 注意：有些编程语言的网络库会自动为所有参数进行 urlencode，在这种情况下，就不需要对签名串进行 URL 编码了，否则两次 URL 编码会导致签名失败

公共参数（签名约定）

参数名称	类型	传递方式	是否必填	描述
Token	String	http header	是	验证加密值 Md5(AppId+Nonce+SecretKey+TimeStamp) 加密的32位小写字符串
TimeStamp	Long	http header	是	时间戳（毫秒），当前调用方时间戳
AppId	String	http header	是	AppId，线下邮件通知
Nonce	Integer	http header	是	六位随机数字

正确返回结果


  // data 为数组   
{
    //应答码
    "code":200,
    //查询是否成功
    "success":true,
    //响应信息
    "message":"Successful!",
    //响应数据
    "result":{
        "data":[
            {

            }
        ],
        //分页条数 
        "pageSize":10,
        //总条数
        "totalCount":10,
        //当前页码
        "pageNum":1
    }
}

// data 为对象
{
    "code":200,
    "success":true,
    "message":"Successful!",
    "result":{
        "data":{

        }
    }
}

错误返回结果


{
    "success":false,
    "message":"当前的 appId 无效或者还未生效中",
    "code":101
}

通用应答码

应答码	含义	级别
101	当前的 appId 无效或者还未生效中	系统级
102	当前 appId 已欠费	系统级
103	当前 appId 被暂停使用	系统级
104	接口正在维护中	系统级
105	接口已下线停用	系统级
107	被禁止的 IP	系统级
108	请求格式错误，请重试	系统级
109	请求超过系统限制	系统级
110	当前查询连续出错，请等 2 小时后重试	系统级
111	接口权限未开通	系统级
112	签名错误	系统级
113	当前接口已被删除，请重新申请	系统级
114	当前接口已被禁用，请联系管理员	系统级
115	身份验证错误	系统级
199	系统未知错误，请联系技术客服	系统级
200	查询成功	服务级
201	查询失败	服务级
202	查询参数错误，请检查	服务级
203	系统查询有异常	服务级
204	请至少输入一个参数	服务级
205	等待处理中	服务级
207	请求数据的条目数超过上限	服务级
208	此接口不支持此类型查询	服务级
213	参数长度不能小于 n	服务级
214	您还未购买过该接口，请先购买	服务级
215	不支持的查询关键字	服务级
216	此接口调用次数已达上限	服务级
299	无效的请求	服务级

请求示例

java php python node.js

import com.google.common.collect.Maps;
 import org.apache.commons.codec.digest.DigestUtils;
 import org.apache.http.client.methods.CloseableHttpResponse;
 import org.apache.http.client.methods.HttpGet;
 import org.apache.http.impl.client.CloseableHttpClient;
 import org.apache.http.impl.client.HttpClients;
 
 import java.io.IOException;
 import java.util.Map;
 
 
 public class JavaDemo {
     public static void main(String[] args) throws IOException {
         String AppId = "";
         String SecretKey = "";
         Long TimeStamp = System.currentTimeMillis();
         Integer Nonce = 123456; //使用随机六位数字
         String Token = getToken(AppId,SecretKey,String.valueOf(Nonce),String.valueOf(TimeStamp));
 
 
         String url = ""; //接口地址
         Map<String,Object> params = Maps.newHashMap();
         CloseableHttpClient httpclient = HttpClients.createDefault();
         HttpGet httpget = new HttpGet(url);
         httpget.setHeader("Token", Token);
         httpget.setHeader("TimeStamp", String.valueOf(TimeStamp));
         httpget.setHeader("AppId", AppId);
         httpget.setHeader("Nonce", String.valueOf(Nonce));
 
         CloseableHttpResponse response = httpclient.execute(httpget);
 
     }
 
     // 获取Token
     protected static final String getToken(String AppId, String SecretKey, String Nonce, String TimeStamp) {
        return  DigestUtils.md5Hex(AppId.concat(Nonce).concat(TimeStamp).concat(SecretKey)).toLowerCase();
     }