中文 | 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 (following examples only show logic)

Call com.vip.ospserver.api.OtherService, and hypothesize appKey=yourappKey、appSecret=yourappSecret

1) System-level input parameters:

service=com.vip.ospserver.api.OtherService
method=getPopReplaceIntoAfterSaleAddress
version=1.0.0
timestamp=1406851200
format=json
appSecret=yourappsecret
appKey=yourappkey

2) APP-level input parameters

{
 "url":"www.vip.com",
 "start_time":"2014-06-10 14:53:21",
 "hashcode":"abcdefg"
}

3) Arrange all the system-level parameters except for appSecret in alphabetical order.

appKey=1
format=json
method=getPopReplaceIntoAfterSaleAddress
service=com.vip.ospserver.api.OtherService
timestamp=1406851200
version=1.0.0

4) Link the system-level parameters that have been ordered by parameter name + parameter value, and APP-level parameter values come last to obtain final assembly character string.

appKey1formatjsonmethodgetPopReplaceIntoAfterSaleAddressservicecom.vip.ospserver.api.OtherServicetimestamp1406851200 version1.0.0{"url":"www.vip.com","start_time":"2014-06-10 14:53:21","hashcode":"abcdefg"}

5) appSecret serves as the key to complete hmac-md5 encryption for above assembled character string. Signature results:

2CA5D80723A40B59E095A4D675D46449

V. HTTP Request Assembly

All system-level parameters will be transformed to UTF-8 code and be submitted by means of GET in API calling. APP-level parameters will be submitted to the access address of production (or sandbox) environment by means of POST, and interface return data can be obtained.

VI. Notes of API Calling

• All API requests and response data codes are in UTF-8 format, and urlencode code will be completed for all the URL parameter values.

• API requested APP-level parameters are required to be transformed into xml or json format.

• Format of return results is in conformity with the request format you select.

• Signature is completed by means of hmac-md5(params,appSecret), where params is assembled after being ordered in alphabetical order of parameter names.

VII. Examples of API Calling

About a complete reference example, please download attachment Complete Reference Example testservice.zip http://vop.vip.com/view/doc/testservice.zip