Introduction

Alibaba open API is the ultimate business solution that makes it easy for SMBs to manage data,  including product information and order information, more efficiently between their proprietary (ERP) system and the marketplace system. More than 20 endpoints that are available on the open API allow your data to be stored in one place and synchronized with a couple of API calls. It is also a great tool ISVs (Independent Software Vendor) can use to help you develop your own product listing solutions.

It is powered by Alibaba Cloud and SDK central hub. The beta version of Alibaba open API is now provided free of charge for all paid GGS users. The open API supports JSON and XML formats, and call examples for JAVA, PHP, .NET, CURL, Python, C/C++, and NodeJS are provided for each endpoint.

Read How to Start first and enjoy using Alibaba's powerful open API. 

How to Start

You need to login to your Alibaba account before getting started. The process involves 3 steps.

     I. Developer Registration

     II. Authorization - Access Token

     III. API Calls

I. Developer Registration

Developers are required to register in order to get App key and App security. Alibaba.com needs this information to create a developer account for you.

Access the API portal by navigating to MyAlibaba, or go to the link below, and fill in your information.

https://activity.alibaba.com/pc/developer.html

[Callback URL] is the address to which Alibaba.com will return your authorization code. You can always edit this information on the basic configuration page of your developer account.

If you see the page shown above, you have successfully registered as a developer on Alibaba.com.

II. Authorization - Access Token

Access tokens are unique pieces of information used by Alibaba.com to identify a product or an order that belongs to a particular user. 

This process allows the ISVs (Independent Software Vendor) who have been authorized by their end-users to access the end-users' accounts on Alibaba.com.

The access token is required in every API request. There are 3 steps to acquire the access token.

     1. Create a URL for authorization

     2. Get authorization code

     3. Call Alibaba.com server and get your access token by providing authorization code 

1. Create a URL for Authorization

Your URL will look like this:

https://oauth.alibaba.com/authorize?response_type=code&client_id=YOUR_APP_KEY&redirect_uri=YOUR_CALLBACK_URL&State=1212&view=web&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.

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. Acquire Access (session) Token

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

1. Alibaba server call entry
2. Your App key
3. Your App security
4. 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.

Copy the code below and paste it into your code editor, then replace the four parameters in the code with your information. Your access token should be returned in the result once you run the code.

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.

III. API Calls

For each API call, you need to include both the common parameters and the parameter for the specific API you are calling. (Refer to the API list for details.) 

Common parameters are the parameters that must be included to call any API. Available parameters are listed below.

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.

FAQ 

Q: Why is Alibaba API not responding?

Make sure the server address are input correctly.

The beta version has limited service availability. If you do not receive a response from the API, please wait at least 10 minutes before repeating your request. We also recommend you store your previous request.

Q: What is the API call limit?

We count the total number of calls from all the API keys that belong to your account.

When your account exceeds the limit, we will not block your account immediately but will send you an automatic notification via email asking you to switch to one of our paid subscriptions within a  reasonable time frame. If we do not get any feedback from you, we will suspend your account. To renew your account, contact us at ALIBABA_OPEN_API@service.alibaba.com.

Q: Where do I report an error?

Log into your Alibaba account, navigate to seller workbench-MyAlibaba, and report errors to the chatbot located at the bottom of My Alibaba page. The chatbot is a built-in feature for Alibaba members to report bugs to our project management system. After you create a ticket for a bug, the ticket will be transferred to the product owner or the developer directly.

You can also contact us at ALIBABA_OPEN_API@service.alibaba.com.

Q: why "Invalid timestamp" ?

please check your sign,  timestamp must current time.