電商物流服務接口規(guī)范說明

秘鑰信息查看方式

注冊賬號后，登錄后臺管理系統(tǒng)查看 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 (去掉空格、換行和\等)，逗號、引號 均使用英文格式

系統(tǒng)級參數

所有接口統(tǒng)一使用此系統(tǒng)級參數

簽名說明

簽名步驟

由接口方提供

示例參數：

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);// 發(fā)送post請求并接收返回結果
        System.out.println(resultData);//訂閱成功示例：{"success":true,"errorCode":null,"errorMsg":null}
    }


    /**
     * 以form表單形式提交數據，發(fā)送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);
            // 創(chuàng)建一個http客戶端
            CloseableHttpClient httpClient = HttpClientBuilder.create().build();
            // 發(fā)送post請求
            HttpResponse response = httpClient.execute(post);
            resultData = EntityUtils.toString(response.getEntity(), "UTF-8");// 返回正常數據
        } catch (Exception e) {
            System.out.println("接口連接失敗 e:" + e);
        }
        return resultData;
    }


}

收到請求后，以同樣的算法進行簽名，對比兩者是否相同。如不同，說明傳遞過程中發(fā)生數據篡改。

返回請求失敗：

{
success":false,
errorCode":"400"
errorMsg":"接口校驗失敗，請檢査sign是否正確
}

詳情查看鏈接：https://www.yuque.com/u34567120/gk2t1c/uexegonq46l34g7v