1 Platform Guidelines

1.1 Overview

Taobao Global Open Platform is an end-to-end API development and operation integration platform that provides developers with programmatic access to data on products, orders, shipments, logistics and settlements of platform sellers and resellers, and provides a development environment for users to integrate applications through the API system to provide more diverse seller needs and share your applications to more Taobao global sellers.

The open platform has the following features and advantages.

• Open API library：it can cover rich API interfaces in the e-commerce sector, including product, order, user, marketing and logistics management, and can support up to 10 million calls per day.
• Stable performance：High parallelism and excellent API call success rates ensure your application's performance.
• Security framework：A reliable security framework for protecting the seller's business data.
• Data Board：Statistics on the success and failure rates of API calls initiated by the application.

 

2 Newbie guide

2.1 Access to the process

If you are new to the Taobao Global Open Platform, this guide will help you quickly understand how to start developing your application using the API, deploying it live and sharing your application to users of the Taobao Global Business.

 

2.2 Join the cross-border supply platforms

To enter the cross-border supply platform, note that you need to register in advance, to go for approval (about 1 to 2 people days), generally find their own business classmates to register. After registration, through the open platform of the authorization address link, looking for business students to log in cross-border supply platform for the corresponding authorization, and through the callback address to obtain the authorization code code, with code can call the creation of Token interface to generate a token!

https://distributor.taobao.global/apps/register/registration

Cross-border supply platform help document：

https://helpcenter-globalsupply.taobao.global/page/knowledge?pageId=216&category=1000005768&knowledge=1000056110&language=zh

2.3 Join the Open Platform

If you are a third-party developer who wishes to develop applications that integrate with the Taobao Global Open Platform business through APIs, then you can register as a developer on the Taobao Global Open Platform. Firstly, you can ask your business peers to register a developer account and sign the platform's developer agreement.

Register a developer account on the Taobao Global Open Platform by following these steps.

1) Open the Taobao Global Open Platform homepage at https://open.taobao.global and click on "Join Now".

2) Enter your email address and verification code on the page that opens, then click on "Send Email" to verify.

3) Open the verification email from your email address and click on the verification link, the account registration page will open again. Note: The verification email may be in a spam folder.

4) On the account registration page, set your password, read and check the box to accept the Taobao Global Open Platform Developer Agreement.

5) Click "Finish" to complete your account registration.

2.4 Create a developer application

Description: Once your Open Platform developer account has been added, you can start registering your app on the Taobao Global Open Platform.

• Go to the Create Application page

• Apply for the application type "Global Supply and Marketing Platform/全球供销平台" category

Description: The application type is used to initialise the data configuration when an application is added. It is a template that defines information about the application's licensing policy, licence duration, API licence rights group, API call restriction policy, etc. An application can only belong to one application type. The Supply and Sales Platform application type is "Global supply and marketing platform/全球供销平台".

Specific step-by-step details.：

A. Log in to the Taobao Global Open Platform and open the APP Console;

B. Click on "Add" to display a list of application types that can be applied for;

C. Read the app type description, find the app type you want to apply for and click "Apply';

D. Enter the business requirement for requesting the application type in the "Reason" field of the application window;

E. (Optional) Attach documentation to the request if required. The documentation can be a market analysis, a business plan or the design of the application;

F. Click 'OK' to submit the request;

G. The status of the application type will be displayed as 'Pending' and your request will be reviewed by the platform administrator (approximately 2-3 working days). If you are unable to find a suitable category for your application, please contact the Taobao Global Open Platform Operations team；

• Create a developer application

Description: Once the application type request is approved, the status of the application type will change to "valid", after which you can submit detailed information about your application. The steps are as follows:

Create application details:

A. On the request type page, click "Add APP ";

B. Enter information about the application, including: Application name, callback address (redirect URL for seller authorization), application LOGO；

C. Click on "Submit";

D. Once the app has been successfully added, click on "APP Overview" to view the list of apps, including the app name, app key, type and status of each application；

 

2.5 Application Management

2.5.1 Get AppKey and AppSecret

AppKey: It is the unique identifier of the application on the Taobao Global Open Platform. The App Key is one of the parameters that must be included when making an API call request and the application will be identified by the Taobao Global Open Platform through the App Key.

AppSecret: It is the password assigned to the app by Taobao Global Open Platform to ensure the security and reliability of the app source. You must keep the app key safe and do not share it with other third parties.

Once your app registration is complete, the App Key and App Secret will be generated automatically. You can view or reset the App Key from the App Console/App Preview page.

• From the list of apps, click 'Manage' to go to the App Preview page.
• The App Key will be displayed directly on the App Preview page.
• In App Secret click 'View' to view your App Key.
• Click 'Reset' to reset the App Key of your app. If there is an "App Key Expired" field, please select the expiry time (in hours) of your old APP key.
• After resetting the App key, you must update the information about your application.

As shown in the picture:

2.5.2 Apply for an API license

On the Taobao Global Open Platform, an API Permission Group defines a set of API groups with specific permission bindings. Without an API permission, API calls initiated by an application will be rejected.

An application type can contain multiple API permission groups. When the application is added, it will be granted some API permission groups, but other permission groups need to apply separately. The status of the API permission group is as follows:

• Valid: API permission groups are available by default or have been requested and approved as available.
• Invalid: API permission groups require a separate application or an unsuccessful application.

2.6 Seller's authorization

2.6.1 Authorisation notes

Configure Seller Authorization If your application needs to access the seller's business data, your application needs to be authorized by the seller. You need to guide them to complete the "Authorization with Taobao Global Account" process. After registering your application on Taobao Global Open Platform, you can start your application development. API reference-A complete reference document for each API.

2.6.2 Delegation Strategy

Taobao Global Open Platform uses OAuth 2.0 protocol for user authentication and provides different authorization policies for different application categories, which are predefined for the application category your application belongs to. You can view the detailed authorisation policies for your application on the Authorisation Management page, including the following:

• Licensing Policy: The overall policy of the application
• "Access Token' cycle: the period of validity of the application's Access Token
• "Refresh Token" period: the period for which the Refresh Token is valid (see the OAuth documentation for more information)
• Authorisation page: whether to display the authorisation page (the authorisation page is preset to be displayed)
• Authorisation protocol: OAuth 2.0 authorisation type
• Authorised user limit: maximum number of sellers for the authorised application

Important to note that the following two authorisation policies apply to different app categories:

• Allow tied user authorisation: This authorisation policy applies to categories that interface directly with the big seller's internal app or "customer service". This policy allows only sellers who have been set up in the 'Authorised Seller Whitelist' to authorise your app.
• Allow logged-in users: This policy applies to applications related to ERP systems such as "Product Management", "Order Management" and "Logistics Management".

2.6.3 Designated whitelist authorisation

If you have developed an app for a specific seller, you can limit the scope of authorisation by specifying a whitelist of sellers on the Taobao Global Open Platform, so that only these sellers can authorise your app to access their business data on the Taobao Marketplace. After your app has been deployed online, you will need to provide your sellers with the authorisation URL and when they log into your app for the first time, they will be prompted to complete the authorisation process.

Take the following steps to specify the short code of the seller who can authorise your application to access their business data:

Take the following steps to specify a shortcode for sellers who can authorize your application to access their business data:

1. Open APP Console, click APP Management -> Authentication Management.
2. In the Authorization Information section, view the description of the app authorization policy.
3. In the Authorised Seller Whitelist section, enter the seller account number in the Authorisation field. Multiple seller accounts can be separated by a semicolon.
4. Click "Submit ".
   Note: If you are a third party developer and your app is available to all users of the Taobao Global Open Platform business, then you only need to provide the URL of your app to the seller when the app is deployed online and the seller can follow the URL to complete the authorisation process. Please refer to the Seller Authorisation section for the authorisation process.

2.6.4 Seller's authorization steps

Description: If your application needs to access a seller's business data (e.g. product and order information) via the Taobao Global Open Platform, you will need to obtain the seller's authorisation, i.e. the 'Access Token' required to access the seller's information. You will need to guide the seller through the 'Application for Authorisation to Login using the Cross Border Supply Platform' process. This process uses the international OAuth 2.0 standard protocol for user authentication and authorisation.

The Taobao Global Open Platform uses the "Code for token" model, described as follows:

Server Address: https://api.taobao.global/oauth/authorize

Authorisation steps (as shown in the diagram):

2.6.4.1 Splicing Authorization URL

Spell out the authorised URLs and direct access to them by business students according to the following rules:

Note: Please replace "appkey" and "redirect_url" with your developer application configuration.

The list of authorization URL parameters is described below:

parameter	Is it necessary?	value	describe
client_id		xxx	The App Key of your application assigned by the open platform.
redirect_url		The file back URL provided when the application is created.	Redirect_url is the receiving code returned to you by the seller upon completion of authorization, which must be the same as the file URL provided when creating the application on taobao Global Open Platform.
response_type		code	The authorization type whose value is code.
force_auth		true	Refresh the Web browser Cookie to obtain the new authorization process.
state		It can be customized, for example, 1212.	The state of the application is the same as that of input and response.
uuid		uuid283118319	The identity assigned to the seller protects the returned authorization code.

2.6.4.2 Guide seller authorization

Guide the distributor to open the above authorization URL through the web browser, and the authorization login page as shown in the following figure will appear. The left side shows the permissions granted by the seller to the application after Authorization. You need to enter the cross-border supply platform account and password registered in step 2.2 (note that it is not an open platform account! Otherwise, it cannot be purchased normally), click "Log in and Authorize" to complete the authorization of the application.

2.6.4.3 Obtain the authorization code

After the seller completes the authorization, Taobao Global Open Platform returns the authorization code to the return URL address. Your application uses the authorization code to obtain the AccessToken. The URL will be the APP callback address you set + authorization code (code)

For example:

Note:

• this authorization code will expire within 30 minutes. You need to use this code to obtain the Access token before it expires.

2.6.4.4 Get AccessToken according to code

Description: Use the API "/auth/token/create" to get AccessToken

Note: The Access Token is valid within a certain time range. The seller does not need to re-authorize the application before it expires. You need to be properly Keep the latest token.

IopClient client = new IopClientImpl("https://api.taobao.global/rest", appkey, appSecret); 
IopRequest request = new IopRequest("/auth/token/create"); 
request.addApiParameter("code", "0_TryzT8Vd9T1pwS7VWZ2qlMOS5");
IopResponse response = client.execute(request); 
System.out.println(response.getBody());

Output parameters (for reference only):

The following table lists the token parameters and descriptions:

Key	Type	Sample	Description
access_token	string	50000601c30atpedfgu3LVvik87Ixlsvle3mSoB7701ceb156fPunYZ43GBg	Access token.
refresh_token	string	500016000300bwa2WteaQyfwBMnPxurcA0mXGhQdTt18356663CfcDTYpWoi	Refresh token, used to Refresh when refresh_expires_in >0.
expires_in	number	25920 (expires in 25920 seconds)	The Access token expires in seconds: 7 days for "test" applications, 30 days for "online" applications.
refresh_expires_in	number	25920 (expires in 25920 seconds)	Refresh Token expiration time 30 days for applications in test state 180 days for applications in online state refresh Token expiration time 30 days for applications in test state 180 days for applications in online state
account_id	string	706388888	User ID, which can be ignored when account_platform = seller_center.
account	string	xxx@126.com	User account.
account_platform	string	seller_center	User platform, supporting multiple platforms.

View the actual validity period:

Note: The application of the developer who has not been released and launched (in the test phase) will be shorter than the application that has been launched. Therefore, the developer must apply for the application to be released and launched after the docking is completed! You can adjust the refresh token policy accordingly. If your business needs to extend the token or refresh token validity time, you can find the owner of the open platform to adjust it.

Example (test phase):

2.6.4.5 Token refresh policy

Description: Use the API "/auth/token/refresh" to update the AccessToken.

IopClient client = new IopClientImpl(UrlConstants.API_GATEWAY_URL_TW, appkey, appSecret);
LazopRequest request = new LazopRequest();
request.setApiName("/auth/token/refresh");
request.addApiParameter("refresh_token", "50001600212wcwiOabwyjtEH11acc19aBOvQr9ZYkYDlr987D8BB88LIB8bj");
LazopResponse response = client.execute(request);
System.out.println(response.getBody());

Output parameters (for reference only):

With API "/auth/token/refresh", the data structure returned is the same as the data structure returned by obtaining access rights through the authorization code. You will get new access_token and refresh_token . You must save the latest refresh_token to get a new access_token . Note that the access_token duration is reset, but the refresh_token duration is not reset. After the refresh_token expires, the seller will need to reauthorize your app to generate new access_token and refresh_token.

2.6.4.6 Token aging description

Note:

• The seller does not need to authorize again before the RefreshToken expires.
• If refresh_expires_in = 0, Access Token cannot be refreshed. Call/auth/token/refresh API to refresh access only if refresh_expires_in> 0
• If you need to update the AccessToken, it is recommended to refresh within one week before the AccessToken expires.
• If the validity period of the current token has a greater impact on your business, the person in charge of the supply platform can be extended.

field	Application Status: Test (aging)	Application Status: Online (aging)
code	30 minutes	30 minutes
access_token	30 days	30 days
refresh_token	60 days	180 days

3 Development documentation

3.1 Usage 1: Use SDK request (recommended)

Description: The SDK is automatically generated for your application, including combining requests, generating encryption, response interpretation, and information monitoring. Use the SDK Call API operations are easy to understand. We recommend that you use the official SDK to call API operations.

Environmental requirements:

• JAVA SDK requires JAVA SE/EE 1.5 or newer version;
• Net SDK requires. Net Framework 2.0 or newer (Windows Phone is not supported);
• PHP SDK requires PHP 5 or an updated version;
• Python requires Python 3.0 or later;
• for Ruby, you can install it directly.

3.1.1 SDK download

Before downloading the SDK, you must register as a developer and log on. The downloaded SDK is directly associated with the application.

To download the SDK for an application, you can take the following steps:

• log in and open the APP console page.
• click "Manage" in the APP list to open the APP overview page.
• on the APP management navigation page, click "SDK download"
• click "Download" to complete the download of the SDK that meets a specific programming language.
• JAVA SDK requires JAVA SE/EE 1.5 or newer version;

Address: https://open.taobao.global/app/index.htm#/sdk/download, as shown in the following figure:

3.1.2 Call request address

Description: Before using the SDK, modify the request server

Call request address: https://api.taobao.global/rest

3.1.3 Call example

3.2 Usage 2: Use HTTP request API

3.2.1 API call process

Call the API of Taobao Global Open Platform by using HTTP requests. You can use the SDK provided by the platform to call an API (recommended), or assemble the request according to the custom format of the Taobao Global Open Platform protocol (only if the official SDK is not provided in this programming language). This topic describes how to assemble HTTP requests to call.

API calls require input data and return data as output responses. The general steps for calling an API by generating an HTTP request are as follows:

• fill in the parameters and values
• signature encryption algorithm
• assemble HTTP requests
• start the HTTP request
• get the HTTP response
• explain the JSON/SML response

For more information on open platform API calls, see API tutorials.

3.2.2 Call request address

Taobao Global Open Platform provides an online production environment. The data generated in this environment is real and valid online data, and provides a limited number of calls and permissions. The production environment shares data with the online system. The real data of online stores is directly affected by API operations. Be sure to operate with caution.

The call request address is: https://api.taobao.global/rest

3.2.3 Request and response

Taobao Global Open Platform API supports both HTTP and HTTPS communication protocols. To ensure data security, we recommend that you use the HTTPS protocol to send API requests. Although most APIs are called through GET, and some calls for additional request information are sent through POST, sometimes more information needs to be provided than the data that can be transmitted in the request parameters. In many cases, additional data is sent to the server through a POST request. The body of the request must be in XML format, and all data (including parameter names and values) must be utf8 encoded.

Each HTTP request URL must contain the API path. For example, a request to the/order/get API should be https://api.taobao.global/rest/order/get 。 Common parameters and business data are included in the request or sent through POST.

All API calls return a response document that shows the status of the operation (success or error) and may provide results and/or details related to the specified operation. The response format is JSON.

3.2.4 Request for input

In addition to the parameters associated with the application, the call to the API must also contain system parameters. Different APIs require different application-specific parameters.

System parameters

System parameters are required for HTTP requests for each API call, as shown in the following table:

Name	Type	Whether or not mandatory	Description
app_key	String	Yes	The app key assigned to the application.
access_token	String	Conditional	For APIs that require seller authorization, the seller authorization token is required.
timestamp	String	Yes	The time when the request is sent, in UTC or digital format, such as "2018-11-11 T12:00:00Z or 1517886554000". Note that the difference between the timestamp and the UTC time should not exceed 7200 seconds.
sign_method	String	Yes	The algorithm used for signature encryption.
sign	String	Yes	The password signature used to verify the request.

Business parameters

In addition to the system parameters that must be included in the API call request, the request service parameters are also required. For more information about the business parameters of each API, see the API documentation.

3.2.5 Parameter signature

Taobao Global Open Platform verifies the identity of each API request, and the server also verifies whether the call parameters are valid. Therefore, each HTTP request must contain signature information, and requests with invalid signatures will be rejected.

Taobao Global Open Platform uses the App Key and the key assigned to the application to verify the identity of the request. The App key is used to generate a signature string when requesting a URL and a server-side signature string. Please keep your key strictly confidential.

If you manually write HTTP requests without using the official SDK, you need to understand the following signature algorithms.

The process of generating a signature is as follows:

• sort all request parameters (including system and application parameters, except for "symbol" and byte array type parameters) according to the parameter name in the ASCII table.

3.2.6 HTTP request example

Taking the GetOrder (/order/get) API request as an example, the steps to form an HTTP request are as follows:

 

3.3 Error Code

All API calls return a value that shows the status of the operation (success or error) and may provide results and/or details related to the specified operation.

When an API call fails, the system also returns a request ID and an error code. There are three common API call errors:

• SYSTEM:API platform error
• ISV: Business data error
• ISP: Back-end service error

 

API platform error (ISV errors)

The API platform errors usually occur because the request from a user does not fulfill the basic verification. When encountering such errors, check the authority, frequency and other conditions of the applications. Then, check the uploaded parameters for completeness and validity based on the API documentation.

 

Business data error (ISP errors)

These errors are the result of a business logic error, these errors are caused if you do not follow the certain business rules set out by the Lazada Platform (e.g. product creation rules, platform policy rules, etc).

When encountering such errors, check whether the corresponding information is uploaded based on the error information. It is recommended to try again after correcting such errors. Should you still receive the error messages, please reach out to the Lazada Partner Seller Support to find out the business

 

Backend service error

The backend service errors are usually caused by the availability of API service. Please try again after some time, if the issue persists, please contact our technical support team.

For example

ErrorCode	ErrorMsg	Description
ServiceTimeout	The request has failed due to RPC timeout.	an error message that describes the timeout of an API call
502 Bad Gateway	The proxy server received an invalid response from an upstream server. Sorry for the inconvenience.	If the Qps is too high, the request fails to reach the gateway. We recommend that the distributor retry the request.
InternalError	The request processing has failed due to some unknown error, exception or failure.	The API call failed. Check whether the input parameters and API documents are correct.

4 Commissioning and maintenance

4.1 API testing tools

Taobao Global Open Platform provides you with an API testing tool to test APIs on the platform. The steps to start the API testing tool are as follows:

1. Open the application console and click the "Manage" button of the application;
2. On the APP management page, find and click "API Testing Tools" from the left-side navigation bar;
3. In the API test tool, enter the API name and click to obtain the parameters. The system will automatically bring out the API parameters.
   Note: The API testing tool uses online data from the production environment.

Parameter description. The API test tool parameter is described as follows:

Name	Description	Sample values
API Path	which describes the path of the API that you want to test.	/brands/get
HTTP Method	Most APIs are called through GET, and some calls that get additional request data are sent via POST.	GET or POST
App Key	The unique identity of your application on the open platform is generated when the application is created.	100126
Access Token	The token required for your application to access seller sensitivity data.
Business parameters	The business parameters of the API to be tested.	According to the selected API, different parameter fields can be filled in.
Request	When the parameters are specified, click the "Start Test" |button, and the request URL will be generated and displayed in the request field.
Response	The API response body of the specified parameter.

4.2 Test Application (Pending)

After completing the configuration of the application, you can start testing the application using the Taobao Global Unified Account. You need a seller account to complete the vendor authorization process for interface debugging. If you don't have a test account, Taobao Global Open will provide you with some test accounts to test your application. To obtain a test account, follow these steps:

interface debugging. If you don't have a test account, Taobao Global Open will provide you with some test accounts to test your application. To obtain a test account, follow these steps:

1. Open the APP console and click Test Account-> Borrow Account.
2. On the test account application page, enter the business requirements for the test account, click Submit, and a test account will be assigned.
3. Check the test account information, especially the password rules of the test account.

Important information:

The password for the test account consists of (your developer account) and (password).

For example, if your developer account on the open platform is test@mail.com, and your developer account password is ABC, then the password for the test account is test@mail.com | ABC.

Note: In order to successfully test the application, you should issue 1000 + calls to the Open Platform every day for two weeks with a success rate of at least 95%. If you do not have enough test API call records, you will not be able to respond to your application.

4.3 Deploy the application

Deploy applications When your application is developed and tested, you can deploy your application online to a hosting environment.
Do these steps to complete the deployment process:

1. In the application list, click Manage to open the overview page of the application.
2. On the APP overview page, you can find the "APP Status" field in the Basic Information section.
3. Click Online Application.
4. Enter a description of the application to be deployed online in the "Reason" field in the application box.
5. (Optional) Attach a document to the application as needed, which can be a test report for the application.
6. Click "OK".

Once the online deployment request is approved, the status of the application will be changed to online. The application can then be deployed to the requested or planned hosting environment.

4.4 Monitor application data

After the application is published online, you can monitor the statistics of API calls initiated by the application through the Data Dashboard page.

The data dashboard provides the following categories of statistics:

APP statistics-Statistics based on API calls over a period of time

• date
• the total number of APIs called by the application.
• total number of successful calls
• total number of failed calls
• verage QPS (query per second)

Seller Statistics-Seller's API call statistics over a period of time

• date
• Seller
• the total number of APIs called by the seller.
• average QPS (query per second)

Error code statistics-API error code statistics over a period of time

• API name
• Error type
• Error code
• Error message
• the total number of each error

5 Main API scenarios

5.1 Forward Transaction Scenario

5.1.1 Purchasing mode

Fast procurement process (recommended) 1: commodity collision-transaction

Scenario description: According to the Taobao product ID, you can obtain the product model of the cross-border supply platform by using the product ID of the Taobao product, and purchase the product that has successfully collided with the database.

 

 

Fast procurement process (recommended) 2: Taobao similar recommendations-transactions.

Scenario description: The entry parameter is the Taobao product ID. You can obtain a batch of similar products in the Taobao product pool and have low prices (from low to high). You can place orders from the returned batch of products according to their own needs. (When similar users shop on Taobao, they search through a picture of the target product, and then Taobao retrieves the corresponding similar product and shows it to you from low to high according to the price).

 

5.1.2 Shopping Guide Mode

Rapid procurement process (recommended) 1: Distribution-transaction

Scenario description: The platform selects a batch of goods from the product pool to the distributor according to the user's needs, or the distributor manually selects the required goods on the cross-border supply platform for distribution. After the product is successfully distributed, the supply and marketing platform system sends a successful delivery message to the distributor. The distributor can subscribe to the distribution message in the open platform developer application and analyze the message accordingly. Obtain product information (the message body mainly includes the channel product ID, distributor ID, etc.), call the cross-border supply platform product details interface based on the channel product ID to obtain the product details such as SKU, and persist to its own system platform, and then place orders for the product.

 

 

Quick procurement process (recommended) 2: Search (Post URL format)-transaction

Scenario: You can search for the same product in the cross-border supply platform based on the image of the purchased product or the channel product ID, and then obtain the returned product ID. You can call the cross-border supply platform to obtain the product details such as SKU, and then purchase the product.

 

 

Fast procurement process 3: cross-border supply platform with the same payment-transaction

 

 

5.2 Reverse Trading Scenario

5.2.1 After-sales process

Business description: distribution through the supply and marketing platform to initiate the purchase order, through the supply and marketing platform interface for the relevant after-sales operation, secondly, can also use the scene as shown in the following figure, through its own distribution platform after-sales capacity building, access to cross-border supply and marketing platform external OpenAPI to complete the after-sales purchase order. Before accessing the OpenAPI, it is necessary to go to the cross-border supply and marketing platform to experience the after-sales process to ensure that the overall process is familiar with the convenience of after-sales interface docking. (The following figure only shows the overall process. For other Reverse order queries, message queries, etc., you can consult the relevant interfaces, and don't forget the synchronization of reverse messages.)

 

 

6 API interface details

6.1 Related APIs

API document address:

https://open.taobao.global/doc/api.htm#/api?cid=8&path=/auth/token/refresh&methodType=GET/POST

 

6.1.1 System services

API name	Description	Version (must see)
/auth/token/create	When the seller and distributor complete the authorization, you can obtain the authorization code from the Call Back URL and use this API to further obtain the access token.
/auth/token/refresh	When the Access Token expires, use this API to obtain a new Access Token.

 

6.1.2 Goods and services

API name	Description	Version (must see)
/batch/src/products/check	Batch collision (you can understand batch query products) Note: The entry is Taobao product ID, which is the same as the single product collision Library.
/product/on/off/shelve	The status of the goods on the selling e-commerce platform.
/product/get	Single product collision Library (understandable query product) Note: The entry parameter is the product ID of Taobao.	upgrade -2022-05-23
/product/categories/get	Category tree query
/item/get	Taobao product query Note: The entry is Taobao product ID.
/mpId/get	Obtain the channel product ID based on Taobao product ID Note: For the time being, the product ID of Taobao is not available.
/product/spus/get	Query the list of products that have been sold or canceled by the distributor. Note: This interface only supports Shopping Guide scenarios! The purchasing scene is not used.
/product/details/query	Supply and marketing platform product details. Note: The input parameter is the mp_Id of the product on the supply and marketing platform, and the ID of the non-Taobao product.
/promotion/query	Big promotion commodity discount inquiry. Note: You can only participate in the price query of the product.
/product/similar/get	Search for product images. Note: Search for the same product in the cross-border supply platform based on the picture or the product ID of the supply and marketing platform market.
/product/recommend	Similar recommended queries. Note: The entry parameter is the Taobao product ID. You can obtain a batch of similar products in the Taobao product pool, and the price is low (the price is low to high).	upgrade -2022-05-23
/product/relation/build	Distributor distribution (establishing a commodity relationship), before purchasing the distributor must establish a binding relationship with the product. Note: At present, the order will be automatically laid out (the relationship between goods and merchants) can be discarded.
/product/same/query	Supply and marketing platform products with the same amount of query.

 

6.1.3 Order service

API name	Description	Version (must see)
/purchase/order/asyn/cancel	Cancel the purchase order. Note: After the merchant delivers goods, it will not be able to cancel it through this interface, and it needs to go to the cross-border supply platform to initiate after-sales reverse. (It is recommended that all paid purchase orders go through the after-sales interface).
/purchase/order/batch/pay	Purchase order bulk payment Note: The input parameter is the purchase order ID of the cross-border supply platform. This interface is executed asynchronously. It is only submitted for payment and the purchase order that cannot be paid is filtered out. The returned results are for reference only. In the end, information synchronization must be performed through the purchase query interface. Otherwise, data consistency problems will occur.
/purchase/order/create	Create a purchase order. Note: 1. The asynchronous logic used behind this interface allows you to synchronize data by subscribing to the purchase order status change message. 2. Product details in the entry (commodity ID must check the mp_id returned by the commodity interface, sku_id is also taken mp_sku_id, otherwise it cannot create a single normally! Because of the post-distribution data model) 3.outer_purchase_id is an idempotent field, remember that each order must be unique. 4. Market channel_order_type mainly depends on your specific application scenario: purchasing scene fill in: PANAMA_DG, shopping guide scenario: PANAMA (default)
/purchase/orders/query	Query the purchase order. Note: Pay attention to the input of this interface, and the shipped orders will have corresponding logistics.	2022-07-14 - purchase orders query

 

6.1.4 After-sales service

(1) Overall business process

（2) After-sales interface details

API name	Description	Version (must see)
/order/refund/render	Reverse order rendering interface Description: The distributor initiates a refund and calls this interface to obtain the reason for the refund and the maximum amount of the refund. Provide the reverse interface certainty information (refund type + cargo status) to determine the refund reason list, (refund type, cargo status, refund reason) to determine the maximum refund amount.
/order/refund/submit	Reverse order submission Description: The distributor initiates a refund. After filling in the information (the information can be obtained from the rendering interface), submit a reverse order.
/order/refund/modify	Reverse single modification interface Description: The distributor modified the reverse order information.
/order/refund/query	Reverse order details interface Description: The distributor can view the details of the reverse order.
/order/refund/queryList	Reverse single list query interface Description: Distributor Reverse order list query.
/order/refund/render/logistics	Return logistics rendering interface Description: The distributor initiates a refund of the return, and the seller agrees to obtain the logistics information.
/order/refund/submit/logistics	Return logistics submission interface Description: The distributor initiates a return refund. After the seller agrees, fill in the logistics information and submit the return logistics.
/order/refund/cancel	Reverse undo interface Description: The distributor cancels the reverse application.
/order/refund/submit/message	submit reverse Message Interface Description: The distributor submits a Reverse order message.
/order/refund/query/message	Message list query interface Description: Query the list of reverse messages, including paging.

 

（3) Reverse state enumeration

refundType

code	Description
1	Only Return Money
2	Return All （Return Money and Return goods）

goodsStatus

code	Description
1	Not to deliver goods
2	Has been shipped
3	Not received the goods
4	Have received the goods
5	Has been sent back
6	Seller confirms receipt of goods

Description: When applying for a refund, the refund type and the status of the goods can be transferred according to the specific scenario.

 

Description of refund types and good status

 

refund status

code	Description
0	Not applying for a refund
10	The buyer has applied for a refund and is awaiting approval from the seller
20	The seller has agreed to refund and wait for the buyer to return goods
30	The buyer has returned the goods and is waiting for the seller to confirm receipt
100	Refund success
-10	The seller refused to refund
-20	Refund close

7 Scenario issues

Solution ideas:

7.1 Distribution FAQ

API:/product/get

Common QA:

1. Common questions about failed distribution

ErrorCode	ErrorDescription	Solution
SYSTEM_ERROR	未查到淘宝商品	Did not find Taobao goods, indicating that the Taobao products have been deleted or off the shelves, please replace other sellers to buy
SYSTEM_ERROR	此商家商品不能通过分销方式售卖，请更换商家	This merchant goods can not be sold through distribution, please change the merchant, according to the prompt to change a merchant to purchase goods
SYSTEM_ERROR	暂不支持购买淘特商品	Does not support the purchase of tamote goods, currently does not support taote goods
SYSTEM_ERROR	撞库不是供销平台签约商品	Distribution is not a supply and marketing platform contracted goods, according to the prompt to replace a merchant for commodity procurement
SYSTEM_ERROR	铺货失败	Delivery failure, contact relevant supply and marketing platform technical person in charge to assist
SYSTEM_ERROR	批量撞库未查询到该商品的mpId	Batch collision Library did not find the mpId of the product contact the relevant supply and marketing platform technical director for assistance

7.2 Create Order FAQ

API:/purchase/order/create

Note:

1. The asynchronous logic used behind this interface allows you to synchronize data by subscribing to the purchase order status change message (see point 8 for details).
2. The product details in the entry parameter (the product ID must be checked for the mp_id returned by the product interface, and the sku_id is also taken.mp_sku_id, otherwise it is not normal to create a single.).
3. outer_purchase_id is an idempotent field, remember that each order must be unique.
4. The market channel_order_type mainly depends on your specific application scenario: purchasing mode to fill in: PANAMA_DG, shopping guide.
   Mode: PANAMA (default)

Common QA:

ErrorCode	ErrorDescription	Solution
GOODS_UN_BUILD_RELATION_OR_NOT_CORRECT	商家未和该商品建立关系，请检查商品的正确性（用跨境供货平台商品ID）后重试创单600037765030623443	(1) Check the channel channel_order_type Whether to fill in the error, according to the specific application scenario of the API. (2) the channel is correct, check whether the commodity parameters are correct; focus on itemI(mp_id), skuId (mp_sku_id), whether all are cross-border supply platform Channel commodity model attributes. (3) Check whether the product status is normal. (4) If there is no problem in the first few steps, find the technical person in charge to solve it.
B-10-00-005	GSP拆单异常	(1) Check whether the channel channel_order_type is wrong, the specific application scenario. (2) the channel is correct, check whether the commodity parameters are correct; focus on itemId(mp_id), skuId (mp_sku_id), whether all are cross-border supply platform commodity model attributes. (3) Check whether the goods are normal. (4) Check whether the authorized account is a cross-border supply platform account (rather than an open platform account). The two platform accounts are separate and not the same. (5) If there is no problem in the first few steps, find the technical person in charge to solve it.

7.3 Purchase order entry problem

API:/purchase/order/create

Field_name	Description
outer_purchase_id	IDs generated by the distributor's own system must be unique.
purchase_amount	estimated purchase amount
seller_order_number	order number generated by the distributor's own system
order_source	order source
order_line_list	order details [commodity ID must check the mp_id returned by the commodity interface, sku_id is also the mp_sku_id, otherwise the order cannot be created normally. ]
receiver	recipient information
warehouse_address_info	Distributor domestic warehouse address (generally sent to this)
channel_order_type	mainly depends on your specific application scenario: [PANAMA_DG | shopping guide mode: PANAMA]
support_partial_success	if the customer fills in the default parameter (false/empty), the online order creation logic goes "one sub-order fails, the whole main order fails", if the customer fills in the specified parameter (true), the online order logic goes "one sub-order fails, part of the sub-order succeeds, the main order returns success"
order_remark	supplier comments (limited to 35 words)

7.4 FAQ about Taobao product details

API:/item/get

Common QA:

ErrorCode	ErrorDescription	Solution
SYSTEM_ERROR	商品详情未查到淘宝商品	product details did not find Taobao goods, indicating that the Taobao products were deleted or off the shelves
SYSTEM_ERROR	商品详情暂不支持购买淘特商品	commodity details do not support the purchase of tamote goods, currently do not support taote goods

7.5 Payment FAQ

API:/purchase/order/batch/pay

Description: The input parameter is the purchase order ID of the cross-border supply platform. This interface is executed asynchronously. It is only submitted for payment and filters out purchases that cannot be paid.The returned results are for reference only. In the end, you must synchronize information through the purchase query interface. Otherwise, data consistency questions will occur.

The ginseng:

Note:

will_pay_purchase_order_ids does not indicate payment success! Instead, a payment order was submitted.

pay_failure_purchase_order_ids indicates payment cannot be submitted! The payment verification failed.

8 Message interface documentation

8.1 Configure Message Service

Developers can configure a callback URL on the open platform to receive message requests. This method can reduce the developer's attempts to obtain order updates through the polling mechanism.

1. Log in to Taobao Global Open Platform as a developer;
2. Select the APP console(APP console);
3. Select Manage on the right side of the application list;
4. Select Message service (Message Service);
5. Enter the callback address and select Verify. If the HTTP 200 status code is returned, the verification is successful;
6. Select the messages to be subscribed from the list;
7. Select Save;

For example:

For the design of the message receiving channel, see:

• use HTTP to receive messages

For more information about the message structure, see:

• cross-border supply platform

8.2 Receive messages using HTTP

Note: You need to provide a message receiving Channel in the form of HTTPS POST requests.

8.2.1 Callback address

To use Message Service, you must prepare a callback interface for receiving messages. Follow the following requirements:

1. Use the HTTPS protocol callback address;
2. Please use the certificate issued by CA, which requires OV/EV level;
3. After receiving the message, please return the HTTP 200 status code to confirm the signing message.

8.2.2 Message processing

1. Do not perform business processing while receiving the message;
2. Please receive the message, store it to the pending queue, and return the HTTP 200 status. After that, the message is consumed asynchronously;
3. The order contains only the necessary identification information. Please use the corresponding query interface to query the business details.

 

Message Example #1. Example of positive transaction information (generated by forward transaction behaviors such as placing orders, paying, shipping, and receiving goods)

 

Message Example #2. Examples of reverse transaction information (cancellation, return refund, and other reverse transaction behavior)

 

8.2.3 Retry and compensation

• the server for more than 500ms did not receive the 200 confirmation, and the server considered that the message push failed.
• After the failure, the message will be pushed again after half an hour. The maximum number of retries is 12 times.
• If the system interrupts more than 12 retries, please retrieve the data through the relevant query interface.

8.2.4 Signature

We recommend that you verify the validity of the received message.

Special note: Do not convert and modify the message body after receiving the message! Otherwise, signing again will not be inconsistent.

The request body is used as the message body, the AppSecret is the key, and the signature encryption algorithm is the HMAC-SHA256.

Signature to generate Sample Code

The data will be transmitted in clear text. For security reasons, please sign and compare the received messages!

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

/**
 * Signature tool class
 * @author jianyan
 * @date 2020/12/01
 */
public class SignatureUtil {
    private static final String HMAC_SHA256 = "HmacSHA256";

    private static final Logger LOGGER = LoggerFactory.getLogger(SignatureUtil.class);

    /**
     * Generates a Hmac-SHA256-based, 16-decimal encoded signature. 
     * @param base {AppKey} + {messageBody}
     * @param secret {AppSecret}
     * E.g.: AppKey = 123456, AppSecret = 3412gyo124goi3124
     * The body of the received message JSON ：{"seller_id":"1234567", "message_type":0, "data":{...}..}
     *
     * base = "123456" + "{\"seller_id\":\"1234567\", \"message_type\":0, "data":{...}..}"
     * secret = 3412gyo124goi3124
     * signature = getSignature(base, secret);
     * signature =  f3d2ca947f16a50b577c036adecd18bec126ea19cadedd59816e255d3b6104ab
     * @return signature
     */
    public static String getSignature(String base, String secret) {
        try {
            Mac sha256Hmac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), HMAC_SHA256);
            sha256Hmac.init(secretKey);
            return byteArraytoHexString(sha256Hmac.doFinal(base.getBytes()));
        } catch (Exception e) {
            LOGGER.error("Failed to generate signature");
        }
        return null;

    }

    /**
     * Hexadecimal Encode
     * @param bytes
     * @return
     */
    private static String byteArraytoHexString(byte[] bytes) {
        if(bytes == null) {
            return null;
        }
        StringBuilder sb = new StringBuilder();
        String stmp;
        for (byte aByte : bytes) {
            stmp = Integer.toHexString(aByte & 0XFF);
            if (stmp.length() == 1) {
                sb.append('0');
            }
            sb.append(stmp);
        }
        return sb.toString().toLowerCase();
    }
}

8.3 Message Service Subscription

Description: When a distributor calls an open platform API, it needs to use it with a messaging service. The main core is to synchronize data from the platform to its own system platform to maintain data consistency between the two sides.

8.3.1 Goods and Services messages

Note that only scenarios are supported: Shopping Guide Mode

Distributor selection

message_type:2

Trigger node: Distributor to/undistribute goods on cross-border supply platform (PANAMA Channel)

{
   "seller_id":"12345", // "seller_id" can be obtained when the distributor is authorized. For more information, see: Interface AccessToken 
   "message_type":2,
   "data":{
      "seller_id":"12345",
      "spu_ids_list":[
         "223244",
         "54543342"
      ]
   },
   "timestamp":123456789
}

 

Critical inventory change

message_type:1

Trigger Node: Each time an inventory update is triggered. Sending at "100", "20", and "0" (PANAMA Channel)

 

Commodity upper and lower shelves

message_type:0

Trigger node: The merchant or platform triggers the product to go up and down.

Among them, commodity messages, because the data is pushed to developers through the API, the order of the messages received by developers cannot be guaranteed. Therefore, please check the API after receiving the commodity messages and then do relevant business processing.

When the merchant is authorized, you can obtain the seller_id of the merchant. For more information, see API AccessToken.

 

Commodity price changes

message_type:7

Trigger node: changes in supplier commodity prices

8.3.2 Order service messages

Order status change

message_type:3

Trigger node: The status of the purchase order has changed.

Message body:

The order-related message will be given to the specific status, and developers can trust to use it directly, provided that the following processing has been done:

-The message is out of order. You must use the reverse check API(/purchase/orders/query) to obtain the purchase order for synchronization.

The value of the purchase order status:

Purchase order status	Description
BULIDING	BULIDING purchase order creation
WAIT_BUYER_P	WAIT_BUYER_P waiting for payment
WAIT_SELLER_SEND_GOODS	WAIT_SELLER_SEND_GOODS paid, to be shipped
WAIT_BUYER_CONFIRM_GOODS	WAIT_BUYER_CONFIRM_GOODS paid, shipped
TRADE_CLOSED	TRADE_CLOSED trading closed

 

Order price change message

message_type:8

Note: Messages are out of order. Finally, you need to reverse the API(/purchase/orders/query) to obtain the purchase order for synchronization.

Trigger node: Create an order and contact the Taobao seller to change the price of the order!

Precautions for price change

• the order price is applicable to the order created after the number 3.15, the order created before does not support the price change, please know.
• when the order is created and feels that it is possible to change the price, contact the Taobao seller to change the order price, and the order after payment does not support the order to change the price. There are some commodities that have business-specific rules, so not all commodities support price changes.
• some orders Taobao close the order time is very short (e. g. 30 minutes), if the time is not paid, the system will conduct risk control interception when placing the order (the order has been closed after the price change, and a new order has been re-generated). At this time, you need to contact Taobao sellers to change the price of the new order. If you have any other questions during the operation, you can directly consult the relevant technical director.

8.3.3 After-sales service news

Refund order/message synchronization message

Description: When the status of the reverse order is changed, if the seller agrees to refund or return the goods, it will trigger a message to notify the distributor. Secondly, if the message is added (the seller's message) or update (the message is overwritten by the message), the distributor needs to get the corresponding message, synchronize the reverse order, or leave the message to maintain data consistency with the supply and marketing platform.

message_type:9

9 Version update instructions

2022-05-23-Distribution

API (/product/get) to upgrade the full product

(1) Full commodity promotion

• Background

In order to help distributors in the cross-border supply platform can find more goods, avoid because the goods are not on the cross-border supply platform can not make orders, for this reason, the supply and marketing platform will be online in 2022-05-22 online "Tmall Taobao full quantity of goods" query, improve the success rate of commodity query. However, due to Tmall Taobao full access to goods need to follow

Taobao Compliance Regulations, non-cross-border goods will not provide product material information (pictures, descriptions, etc.). The original contracted goods are not affected by this. Before docking, Please query the document completely and understand the updated content of the interface to determine whether you need to adjust your own system to avoid affecting your business.

• Affect (needs to be developed according to rules)

（1）Distribution（/product/get）

（2）Recommended API for similar models（/product/recommend）

• Rule change point (parameter rule)

• Rule table

Item_type	Field Description	Response model
HAVE_MATERIAL	"HAVE_MATERIAL" means that this is a supply and marketing product, will contain the full product material.	All fields in response to the data are returned normally
WITHOUT_MATERIAL	"WITHOUT_MATERIAL" means that this is a full Taobao product, which only contains some product information (not including product pictures, descriptions, etc.)	Full product promotion and compliance: The response data is reduced by some SPU fields, and the SKU remains unchanged. 6 less SPU fields:： 1.category_path 2.category_id 3.product_unit 4.pic_urls 5.begin_amount 6.description

• Risk points

Instructions for distributors: Development must be carried out according to the above rule points, otherwise it will affect the rendering of materials in its own system, and there will be missing pictures, details and other content, which will affect the user experience and single volume.

 

 

 

2022-07-14 - purchase orders query

purchase orders query (/purchase/orders/query) adds a list of logistics to the suborder information

• Background

• In order to be compatible with merchants shipping from domestic merchants, Handao currently supports merchants in fulfillment to split packages for shipping in the sub-order dimension, i.e. a sub-order can be sent out in multiple packages, and multiple order numbers can be backfilled when backfilling in the system.
• However, when transmissions are given to distributors (either on the page or in the API), only the first parcel number is taken and displayed, resulting in the undisplayed parcels being treated as no-ownership in the case of multi-package shipments, which affects normal fulfilment.

• Affecting interfaces

(1) purchase orders query (/purchase/orders/query)

• Rule change points (out of reference rules)

Add logistic_orders field for returning a list of multiple logistics

There is a discrepancy between what is shown in the development platform documentation and the real return type, which is an array as shown below:

• Risk point

The original logistic information fields logistic_number, logistic_company_name, rts_time in /purchase/orders/query are obsolete and will not be maintained in the future. It is recommended to use the logistic_orders field to obtain logistics information.