0.ISV Registration

We will help you to register as Alibaba ISV. To complete this, please provide below information to your Alibaba contact:

1. Your registered Alibaba.com buyer account

2.?Developer name，Developer Phone Number，Developer email

3. Your callback url

1. Manage your apps

https://console.aliexpress.com/

modify your callback url

SDK download

2. Ready to work

2.1 ?customer select service time

https://crosstrade.alibaba.com/ecology/service.htm?appKey=YOUR_APP_KEY

when customer click "Authorize", It will automatically jump to "https://oauth.alibaba.com/authorize?response_type=code&client_id=YOUR_APP_KEY&force_login=true&sp=icbu", which is described in 3.1

2.2 manage your service order

https://crosstrade.alibaba.com/ecology/serviceList.htm

3.customer OAuth authorization

3.1 ?Create a URL for Authorization

Use the customer's Alibaba account to access the link

https://oauth.alibaba.com/authorize?response_type=code&client_id=YOUR_APP_KEY&force_login=true&sp=icbu

Your App key and callback URL are required in this step. Replace the value of "client_id" with your App key and replace the value of "redirect_uri" with your callback URL.

3.2 Get Authorization Code

Paste the URL that contains your App key and callback URL into your browser address bar and call the URL. After the permission step, you should now see an error page or a blank page.

Pay attention to the URL bar. The authorization code is sent back to your callback URL as shown in the image above. The URL should look like this: (It is 30 digits high lighted in blue shown above)

http://YOUR_CALLBACK_URL/?code=YOUR_AUTHENTICATION_CODE&state=1212

You will need your authorization code to obtain your access token.

*Important Note for ISVs: You will need to instruct your end-users to open the URL you have created in their browser and log in to their alibaba.com account after the HTTP call. The authorization code will be sent back to the callback URL you have set. Each of your end-users should be associated with a unique authorization code.

3.3 Acquire Access (session) Token

4 parameters need to be configured to get an access token.

Alibaba server call entry

Your App key

Your App security

The authorization code ?call api ?taobao.top.auth.token.create

Alibaba Server Call Entry

Alibaba Server Call Entry is the URL of the server you are calling. Choose below server if your calls are initiated from European and American countries.

JAVA

TaobaoClient client=new DefaultTaobaoClient(“ALIBAB_SERVER_CALL_ENTRY”,”YOUR_ APP_KEY”,”YOUR_APP_SECURITY");
TopAuthTokenCreateRequest request=new TopAuthTokenCreateRequest();
request.setCode(“AUTHENTICATION CODE”);
TaobaoResponse response= client.execute(request);
System.out.println(response.getBody());

?

.NET

ITopClient client = new DefaultTopClient(“ALIBAB_SERVER_CALL_ENTRY”,”YOUR_ APP_KEY”,”YOUR_APP_SECURITY");
TopAuthTokenCreateRequest req = new TopAuthTokenCreateRequest();
req.Code(“AUTHENTICATION CODE”);
req.Uuid="abc"
TopAuthTokenCreateResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

?

Sample Result in JSON

{
  "access_token":"averylonglineofdigitsandalphabets",
  "refresh_token":"someotherdigits",
  "w1_valid":1581792753752,
  "refresh_token_valid_time":1579200753752,
  "w2_valid":1579202553752,
  "user_id":"13455657676",
  "expire_time":1581792753752,
  "r2_valid":1579459953752,
  "locale":"zh_CN",
  "r1_valid":1581792753752,
  "sp":"icbu",
  "user_nick":"youralibabaid"
}

?

You can access any APIs now with the access token shown as the value of "access_token" in the result.

We strongly recommend using SDKs as they provide appropriate API communications protocols and make things easier for you. If you use SDKs in any of the languages listed above, the entire configuration process will be automatically completed and all APIs can simply be accessed with your access token.

4. HTTP Request Signature

For security reasons, all API calls must include a valid signature. The TOP server (one of the Alibaba servers) will verify your signature based on the request parameters. Requests with invalid signatures will be rejected. 

To generate a signature to prevent malicious attacks, we suggest that you use MD5 for data encryption and use HEX function for hexadecimal conversion.

• MD5 (sign_method=md5)

All the API request parameters (including common parameters and API specific parameters, except for signature parameters and byte [] type parameters) must follow ASCII rules. 
Signature Generation

1. Replace the parameter values shown in the common parameter table. The key-values need to be sorted following the ASCII rules. Below is an example that shows the result of sorting by ASCII rules.? ?

App_key="12345678"
Fields="num_iid,title,nick,price,num"
Format="json"
Method="taobao. item. seller. get"
Num_iid=11223344
Session="test"
Sign_method="md5"
Timestamp="2016-01-01 12:00:00"
V="2.0"

?

2. Put together the?sorted?parameter?names?and?values. Delete all the special characters if any. See below.

app_key12345678fieldsnum_iid,title,nick,price,numformatjsonmethodtaobao.item.seller.getnum_iid11223344sessiontestsign_methodmd5timestamp2016-01-01 12:00:00v2.0

3. Use?UTF-8?to encode the assembled string (from Step 2 above) and apply the signature algorithm.

If you use MD5,?your?App?security?must?precede?the?assembled?string.?For?example:

MD5(APP_SECURITY+assembled parameter names and values in sequence+APP_SECURITY)

4. Use HEX function to convert?binary?data to hexadecimal. For example, the code below will be converted to "68656c6f776f72c64"

hex(
    MD5(
        APP_SECURITY+assembled parameter names and values in sequence+APP_SECURITY
      ).getBytes("UTF-8")
    )  

Note:

MD5 is 128-bit algorithms that are expressed in hexadecimal. One hexadecimal character represents 4?bits, therefore the length of a signed string is fixed to 32 hexadecimal characters.

Below is a demonstration of a complete URL using?the information in the examples above (Step 1-4 under Signature Generation): Server_Address + method = API& + String from Step 2 + signature.

https://api.taobao.com/router/rest?method=taobao.item.seller.get&app_key=12345678&session=test&timestamp=2016-01-01+12%3A00%3A00&format=json&v=2.0&sign_method=md5&fields=num_iid%2Ctitle%2Cnick%2Cprice%2Cnum&num_iid=11223344&sign=66987CB115214E59E6EC978214934FB8

JAVA Example

public static String signTopRequest(Map<String, String> params, String secret, String signMethod) throws IOException {
    // Step 1: make sure the parameters are sorted
    String[]keys=params.keySet().toArray(new String[0]);
    Arrays.sort(keys);
 
    // Step 2: put together all the parameter names and parameter values
    StringBuilder query = new StringBuilder();
    if (Constants.SIGN_METHOD_MD5.equals(signMethod)) {
        query.append(secret);
    }
    for (String key : keys) {
        String value = params.get(key);
        if (StringUtils.areNotEmpty(key, value)) {
            query.append(key).append(value);
        }
    }
 
    // Step 3: Use MD5/HMAC Encryption
    byte[] bytes;
    if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
        bytes = encryptHMAC(query.toString(), secret);
    } else {
        query.append(secret);
        bytes = encryptMD5(query.toString());
    }
 
// Step 4: convert binary to upper case hexadecimal (a valid signature consists of 32 upper case characters; use this method when needed)
    return byte2hex(bytes);
}
 
public static byte[] encryptHMAC(String data, String secret) throws IOException {
    byte[] bytes = null;
    try {
        SecretKey secretKey = new SecretKeySpec(secret.getBytes(Constants.CHARSET_UTF8), "HmacMD5");
        Mac mac = Mac.getInstance(secretKey.getAlgorithm());
        mac.init(secretKey);
        bytes = mac.doFinal(data.getBytes(Constants.CHARSET_UTF8));
    } catch (GeneralSecurityException gse) {
        throw new IOException(gse.toString());
    }
    return bytes;
}
 
public static byte[] encryptMD5(String data) throws IOException {
    return encryptMD5(data.getBytes(Constants.CHARSET_UTF8));
}
 
public static String byte2hex(byte[] bytes) {
    StringBuilder sign = new StringBuilder();
    for (int i = 0; i < bytes.length; i++) {
        String hex = Integer.toHexString(bytes[i] & 0xFF);
        if (hex.length() == 1) {
            sign.append("0");
        }
        sign.append(hex.toUpperCase());
    }
    return sign.toString();

C# Example

public static string SignTopRequest(IDictionary<string, string> parameters, string secret, string signMethod)
{
    //Step 1:sort the dictionary by key alphabetically
    IDictionary<string, string> sortedParams = new SortedDictionary<string, string>(parameters, StringComparer.Ordinal);
    IEnumerator<KeyValuePair<string, string>> dem = sortedParams.GetEnumerator();
 
    // Step 2: put together all the parameter names and values 
    StringBuilder query = new StringBuilder();
    if (Constants.SIGN_METHOD_MD5.Equals(signMethod))
    {
        query.Append(secret);
    }
    while (dem.MoveNext())
    {
        string key = dem.Current.Key;
        string value = dem.Current.Value;
        if (!string.IsNullOrEmpty(key) && !string.IsNullOrEmpty(value))
        {
            query.Append(key).Append(value);
        }
    }
 
    // Step 3: Use MD5/HMAC for encryption
    byte[] bytes;
    if (Constants.SIGN_METHOD_HMAC.Equals(signMethod))
    {
        HMACMD5 hmac = new HMACMD5(Encoding.UTF8.GetBytes(secret));
        bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
    }
    else
    {
        query.Append(secret);
        MD5 md5 = MD5.Create();
        bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
    }
 
    // Step 4: convert binary to upper case hexadecimal 
    StringBuilder result = new StringBuilder();
    for (int i = 0; i < bytes.Length; i++)
    {
        result.Append(bytes[i].ToString("X2"));
    }
 
    return result.ToString();
}

API Call Example

Let's take Taobao.item.seller.get?as an example to demonstrate an API call without SDK.

Step 1.?Set values for common parameters and API specific parameters.

Common parameters:

Method="taobao.item.seller.get"
App_key="12345678"
Session="test"
Timestamp="2016-01-0112:00:00"
Format="json"
V="2.0"
Sign_method="md5"

API specific parameters:

Fields="num_iid,title,nick,price,num"
Num_iid=11223344

Step 2.?Sort the parameters by following ASCII rules.

Step 3. Assemble parameter names and parameter values.

Step 4. Generate a signature.?Below is an example assuming?your App security is "helloworld".

hex (md5 (helloworld+concatenated parameter names and values in sequence + helloworld)="66987CB115214E59E6EC978214934FB8"

Step 5.?Assemble HTTP requests.

Use UTF-8 to encode all parameter names and values (the order parameter is optional, but the signature parameter must be included), and then use GET or POST (including byte [] type parameters) to initiate a request. See below:

http://api.taobao.com/router/rest?method=taobao.item.seller.get&app_key=12345678&session=test&timestamp=2016-01-01+12%3A00%3A00&format=json&v=2.0&sign_method=md5&fields=num_iid%2Ctitle%2Cnick%2Cprice%2Cnum&num_iid=11223344&sign=66987CB115214E59E6EC978214934FB8

Important Note

• All the requests and response data are encoded using UTF-8.

          URL encoding is required for all parameter names and values in the URL.

          If the Content-Type header shows application/x-www-form-url encoded, all parameter values in the HTTP Body should be URL encoded.

          If the Content-Type header shows a multipart/form-data format, the parameter values of each form field do not need to be encoded, however, each charset of each form field needs to be specified in UTF-8.

• When the length of your completely assembled URL that contains all the parameter names and values is less than 1024 characters, you can use GET to initiate a request.

          If the parameter type includes byte [] or the assembled request URL is too long, you must use POST to initiate a request. All APIs can use POST to initiate requests.

• You only need to generate a signature if you are not using the SDK. this step will be automatically completed if you use the SDK Alibaba provided.