1. API Specification

Third parties calling Best WMS APIs must follow the specifications below.

1.1. API Invocation Overview

OPENAPI APIs are invoked over HTTP using POST form submission with UTF-8 encoding. Developers must wrap HTTP requests according to the OPENAPI protocol. The following sections describe how to invoke APIs by building HTTP requests manually.

Note: Appending parameters to the URL is not recommended because URL length limits may cause incomplete data to be received.

1.2. Invocation Flow

The main OPENAPI invocation flow is as follows:

1. Fill in message parameter fields
2. Generate the signature
3. Wrap the HTTP request
4. Receive the HTTP response
5. Parse the response result

1.3. Overseas Warehouse API Endpoint

OPENAPI provides a test environment for customers:

1.4. Overseas Warehouse API Parameters

The OPENAPI protocol requires the following parameters: bizData, sign, serviceType, and partnerId.

1.5. Digital Signature

1.5.1. Signature Process

To keep API invocation secure, every API call must include a signature. The Best overseas warehouse API server validates the signature against the request parameters and rejects invalid signatures. The API currently uses the MD5 signature algorithm. The process is as follows:

1. Build the string to sign

Concatenate the bizData and partnerKey parameter values from the API request, for example:

The bizData value is:

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

The partnerKey value is:

123456

The string to sign is:

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

2. Compute the signature

Convert the string to sign into a UTF-8 byte stream, apply the MD5 digest algorithm, and represent the result as a hexadecimal string.

For the example above, the signature is: c1046d06d453b40cc0389271abf6c73b

Note: MD5 produces a 128-bit digest. In hexadecimal form, each character represents 4 bits, so the signature is always 32 hexadecimal characters.

1.5.2. Signature Algorithm Examples

Java

Parameters: bizData + partnerKey, encoded as 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. Notes

a) Set the HTTP header Content-Type to application/x-www-form-urlencoded;charset=UTF-8.

b) All parameters are required.

c) Regarding URLEncode:

• i. Do not URLEncode before signing.
• ii. Check whether your HTTP client already performs URLEncode. If it does, do not encode again. For example, PHP http_build_query() performs URLEncode automatically.

d) Avoid sending requests with parameters appended to the URL whenever possible.

e) If signature validation fails, check the following:

• i. Whether the POST request encoding is set to UTF-8.
• ii. Whether the data to sign has been converted to a UTF-8 byte stream.