电商物流服务接口规范说明

秘钥信息查看方式

注册账号后，登录后台管理系统查看 AppId 和 AppSecret

报文及报文编码

报文格式：JSON
Content-Type：application/x-www-form-urlencoded;charset=utf-8

接口数据包结构

请求头入参示例图

请求报文入参示例图

请求示例

以订阅接口为例展示一串完整的请求报文

{
	"requestData": {
		"cpCode": "STO",
		"mailNo": "43320782358888",
		"pushType": "1",
		"receiverAddress": {
			"address": "测试"
		},
		"receiverTel": "18888888888",
		"subCallBackParam": "2222"
	},
	"appid": "您的appid",
	"sign": "2a41271d67a81a6ba4e0c146adxxxx"
}

为方便展示, 报文做了格式化处理, 实际请求时 请自行压缩JSON (去掉空格、换行和\等)，逗号、引号 均使用英文格式

系统级参数

所有接口统一使用此系统级参数

签名说明

签名步骤

由接口方提供

示例参数：

appSecret = test3as9dj1kj08488c49b69ead19339

requestData = {"cpCode":"JITSD","mailNo":"JT888888888"}

算法：

requestData+appSecret

{"cpCode":"JITSD","mailNo":"JT888888888"}test3as9dj1kj08488c49b69ead19339

79603da5f7aa33d5a1ae6ac9e161b2da

相关工具Code

getSign（JAVA）

    /**
     * 进行加签
     *
     * @param appSecret   用户的appSecret
     * @param requestData json入参
     * @return 处理后，返回的签名值
     */
    public static String getSign(String appSecret, String requestData) {
        String signValue = requestData + appSecret;//按顺序将参数拼接起来 如：requestData+appSecret
        System.out.println("原参数拼接:" + signValue);
        String md5SignValue = MD5Utils.MD5Encode(signValue, "utf8");//形成MD5加密后的签名
        System.out.println("MD5加密:" + md5SignValue);
        return md5SignValue;
    }

MD5Utils（JAVA）

/**
 * MD5
 */
public class MD5Utils {

    private static final String hexDigIts[] = {"0","1","2","3","4","5","6","7","8","9","a","b","c","d","e","f"};

    /**
     * MD5加密
     * @param origin 字符
     * @param charsetname 编码
     * @return
     */
    public static String MD5Encode(String origin, String charsetname){
        String resultString = null;
        try{
            resultString = new String(origin);
            MessageDigest md = MessageDigest.getInstance("MD5");
            if(null == charsetname || "".equals(charsetname)){
                resultString = byteArrayToHexString(md.digest(resultString.getBytes()));
            }else{
                resultString = byteArrayToHexString(md.digest(resultString.getBytes(charsetname)));
            }
        }catch (Exception e){
        }
        return resultString;
    }


    public static String byteArrayToHexString(byte b[]){
        StringBuffer resultSb = new StringBuffer();
        for(int i = 0; i < b.length; i++){
            resultSb.append(byteToHexString(b[i]));
        }
        return resultSb.toString();
    }

    public static String byteToHexString(byte b){
        int n = b;
        if(n < 0){
            n += 256;
        }
        int d1 = n / 16;
        int d2 = n % 16;
        return hexDigIts[d1] + hexDigIts[d2];
    }

}

相关Demo示例

加签（JAVA）

public static void main(String[] args) {
    String appSecret = "test3as9dj1kj08488c49b69ead19339"; //替换你的appSecret
    String requestData = "{\"cpCode\":\"JITSD\",\"mailNo\":\"JT888888888\"}";
    String sign = getSign(appSecret, requestData);
    System.out.println("sign:" + sign);//sign:79603da5f7aa33d5a1ae6ac9e161b2da
}

物流信息订阅接口（JAVA）

import org.apache.http.HttpResponse;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class SubDemoUtil {

    public static void main(String[] args) {
        String url = "https://express.xuanquetech.com/express/v2/subscribeExpressRoutes";//请求路径
        //请求头
        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
        //组装参数
        String requestData = "{\"cpCode\":\"JITSD\",\"mailNo\":\"JT88888888\",\"pushType\":\"1\",\"receiverAddress\":{\"address\":\"测试地址\"},\"receiverTel\":\"13590860188\"}";
        Map<String, String> params = new HashMap();
        params.put("appid", "您的appid");//您的appid
        params.put("sign", "xxx");//签名
        params.put("requestData", requestData);//订阅接口入参字段
        String resultData = httpPostWithForm(url, params, headers);// 发送post请求并接收返回结果
        System.out.println(resultData);//订阅成功示例：{"success":true,"errorCode":null,"errorMsg":null}
    }


    /**
     * 以form表单形式提交数据，发送post请求
     *
     * @param url
     * @param params
     * @param headers
     * @return
     */
    public static String httpPostWithForm(String url, Map<String, String> params, Map<String, String> headers) {
        // 用于接收返回的结果
        String resultData = "";
        try {
            HttpPost post = new HttpPost(url);
            //设置头部信息
            if (headers != null && !headers.isEmpty()) {
                for (Map.Entry<String, String> entry : headers.entrySet()) {
                    post.setHeader(entry.getKey(), entry.getValue());
                }
            }
            List<BasicNameValuePair> pairList = new ArrayList<>();
            for (String key : params.keySet()) {
                pairList.add(new BasicNameValuePair(key, params.get(key)));
            }
            UrlEncodedFormEntity uefe = new UrlEncodedFormEntity(pairList, "utf-8");
            post.setEntity(uefe);
            // 创建一个http客户端
            CloseableHttpClient httpClient = HttpClientBuilder.create().build();
            // 发送post请求
            HttpResponse response = httpClient.execute(post);
            resultData = EntityUtils.toString(response.getEntity(), "UTF-8");// 返回正常数据
        } catch (Exception e) {
            System.out.println("接口连接失败 e:" + e);
        }
        return resultData;
    }


}

收到请求后，以同样的算法进行签名，对比两者是否相同。如不同，说明传递过程中发生数据篡改。

返回请求失败：

{
success":false,
errorCode":"400"
errorMsg":"接口校验失败，请检査sign是否正确
}

详情查看链接：https://www.yuque.com/u34567120/gk2t1c/uexegonq46l34g7v