1. 接口规范

第三方调用百世 WMS API 需遵循以下接口规范。

1.1. API 调用方法简介

开放平台（OPENAPI）的 API 基于 HTTP 协议调用，以 HTTP POST 表单提交方式发送，编码方式为 UTF-8。开发者需根据 OPENAPI 协议自行封装 HTTP 请求进行调用，以下针对自行封装 HTTP 请求的调用原理进行详细说明。

特殊说明：不推荐使用把参数拼接在 URL 后面的方式发送请求，因为 URL 拼接参数的长度有限制，可能会导致接收到的数据不完整。

1.2. 调用流程

OPENAPI 主要调用流程如下：

填充消息参数字段
生成签名
封装 HTTP 请求
拿到 HTTP 响应
解析响应结果

1.3. 海外仓 API 调用入口

OPENAPI 提供测试环境给客户使用：

环境	地址
测试环境	http://kytest.800best.com/gateway/api/glink
生产环境	http://edi-glink.800best.com/gateway/api/glink

1.4. 海外仓 API 调用参数

OPENAPI 协议中需要的参数包括：bizData、sign、serviceType、partnerId。

字段名	含义	类型	是否可空
bizData	业务数据，具体格式见各接口的请求参数说明	String	N
serviceType	业务接口类型，如 `GLINK_CREATE_ORDER_NOTIFY`	String	N
partnerId	合作伙伴 ID（商家 ID），用于客户路由与校验	String	N
sign	签名字符串	String	N

1.5. 数字签名

1.5.1. 签名过程简介

为了 API 的调用过程更加安全，调用任何一个 API 都需要携带签名，百世海外仓 API 服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。百世海外仓 API 目前使用的是 MD5 签名算法，签名大体过程如下：

1. 生成待签名字符串

将 API 请求参数中的 bizData 和 partnerKey 参数值取出，依次进行拼接，如：

参数 bizData 的值为：

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <customerCode>TEST2</customerCode>
  <orderNumbers>TC170501001</orderNumbers>
</request>

参数 partnerKey 的值为：

那么待签名的字符串就是：

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <customerCode>TEST2</customerCode>
  <orderNumbers>TC170501001</orderNumbers>
</request>123456

2. 计算签名

将待签名字符串以 UTF-8 的格式转成字节流，然后对该字节流使用 MD5 摘要算法得到签名字节流，再将得到的签名字节流结果使用十六进制字符串表示，即生成了数字签名。

如：上面的待签名字符串得到的签名为：c1046d06d453b40cc0389271abf6c73b

注：MD5 是 128 位长度的摘要算法，用 16 进制表示，一个 16 进制的字符能表示 4 个位，所以签名后的字符串长度固定为 32 个 16 进制字符。

1.5.2. 签名算法示例

Java 代码示例

参数为：bizData + partnerKey，encode 为 UTF-8

public static String makeSign(String data, String encode)
        throws NoSuchAlgorithmException, UnsupportedEncodingException {
    MessageDigest md = MessageDigest.getInstance("MD5");
    md.update(data.getBytes(encode));
    byte[] b = md.digest();
    StringBuilder output = new StringBuilder(32);
    for (int i = 0; i < b.length; i++) {
        String temp = Integer.toHexString(b[i] & 0xff);
        if (temp.length() < 2) {
            output.append("0");
        }
        output.append(temp);
    }
    return output.toString();
}

C# 代码示例

public static string MakeMd5Sign(string origin)
{
    MD5 md5 = new MD5CryptoServiceProvider();
    byte[] targetData = md5.ComputeHash(System.Text.Encoding.UTF8.GetBytes(origin));
    StringBuilder sb = new StringBuilder("");
    foreach (byte b in targetData)
    {
        sb.AppendFormat("{0:x2}", b);
    }
    return sb.ToString();
}

PHP 代码示例

$partnerKey = '12345';
$bizData = '<xml></xml>';
$origin = $bizData . $partnerKey;
$sign = md5($origin);

1.6. 注意事项

a) HTTP 需要设置头部信息参数（Content-Type, application/x-www-form-urlencoded;charset=UTF-8）；

b) 所有参数都是必传的；

c) 关于 URLEncode：

i. 做签名之前不要 URLEncode；
ii. 应检查发送 HTTP 请求的组件或方法里面是否有做 URLEncode，如果有则不用做额外的 URLEncode。比如 PHP 的 http_build_query() 方法就是自动做了 URLEncode。

d) 尽量避免使用在 URL 后面链接相关参数的方式发送请求。

e) 签名失败时请检查以下几项：

i. 提交 POST 请求时是否设置请求编码为 UTF-8；
ii. 待签名的数据是否已编码 UTF-8 转为字节流；

接口规范