中文 | English
Home > Document > Development Specifications

Development Specifications

Guidance

I. Calling Introduction

II. Access of Calling Environment

III. Calling Parameters

IV. API Signature

V. HTTP Request Assembly

VI. Notes of API Calling

VII. Examples of API Calling

I. Calling Introduction

VOP serves as the data output of VIP Open Platform. Users only need to assemble a correct request URL as per VOP Specifications. Required data can be obtained after reaching VOP by means of HTTP request.

II. Access of Calling Environment

Explanation for environment access: when calling API, following addresses are required to be passed in so as to obtain data in corresponding environment.

Access address of sandbox environment: sandbox.vipapis.com

Access address of production environment: http://gw. vipapis.com

III. Calling Parameters

When calling API, system-level parameters and corresponding APP-level parameters must be passed in. See API file for input parameters of each API and return results.

System-level Parameters:

Name Type Compulsory Description
service String Yes Service Name
method String Yes Method Name
version String Yes Version No.
timestamp Integer Yes Call timestamp in Epoch format. Delta-T of the system shall not exceed 10min.
format String Yes Message format xml/json
appKey String Yes App ID is the unique identification that is distributed to APP by VOP.
sign String Yes Signature operation results according to the signature algorithm

Examples of APP-level Parameters :

Name Type Compulsory Example Value Default Value Description
id Integer Yes 1234 Integer
start_date String Yes 2014-05-08 String
warehouse Warehouse Yes Warehouse.VIP_NH enum
nav_category_id1 List<String> No ["123"] List

Assembly examples of VOP APP-level parameters are as follows:

Description Example
Standard json {
"url":"www.vip.com",
"start_time":"2014-06-10 14:53:21",
"hashcode":"abcdefg"
}
Standard xml
<request> <url>www.vip.com</url> <start_time>2014-06-10 14:53:21</start_time> <hashcode>abcdefg</hashcode></request>

IV. API Signature

It is required to sign the request parameters when API is called, and VOP server will verify the legitimacy of request parameters. It can also be verified by signing the verification tools. Signature Verification Tools

Signature Algorithm:

Step 1: arrange all system-level parameters except for appSecret in alphabetical order.
For example: arrange service, method, version, timestamp, format, appKey as appKey, format, method, service, timestamp, version.

Step 2: assemble the results of arrangement by parameter name + parameter value, and then assemble APP-level parameters.
For example: appKeyXXXXformatXXXXmethodXXXXserviceXXXXtimestampXXXXversionXXXXYYYY, where YYYY is the APP-level parameter.

Step 3: appSecret serves as appSecret to complete hmac-md5 encryption for the assembled character string.
For example: hmac-md5 (appKeyXXXXformatXXXXmethodXXXXserviceXXXXtimestampXXXXversionXXXXYYYY, appSecret) Results: 2CA5D80723A40B59E095A4D675D46449

Examples (