导航

一、调用介绍

VOP作为唯品会开放平台的数据出口，用户只需要按照VOP的规范拼装一个正确的请求URL，通过HTTP请求到VOP，即能获取到所需的数据。

二、调用环境入口

环境入口释义：调用API时，需要传入如下地址，获取相应环境下的数据。

沙箱环境入口地址： http://sandbox.vipapis.com

正式环境入口地址：https://vop.vipapis.com

三、调用参数

调用API时，必须传入系统级参数和对应的应用级参数。各个API的输入参数和返回结果详见API文档

系统级参数(必须拼接在URL后面，作为Query String)：

名称

类型

是否必须

描述

service

String

是

服务名称

method

String

是

方法名称

version

String

是

版本号

timestamp

Integer

是

调用时间戳，Epoch格式，精确到秒，系统接受的时间差不超过10分钟

format

String

是

报文格式 xml/json

appKey

String

是

应用ID，唯品会开放平台分配给应用的唯一标识

accessToken

String

否

OAuth授权token，对于“需要授权”的接口，该字段必填

sign

String

是

根据签名算法的签名运算结果

应用级参数示例(必须放在POST请求的消息主体(entity-body)中)：

名称

类型

是否必须

示例值

默认值

描述

id

Integer

是

1234

整数值

start_date

String

是

2014-05-08

字符类型

warehouse

Warehouse

是

Warehouse.VIP_NH

枚举类型

nav_category_id1

List

否

["123"]

List类型

如下为VOP应用级参数拼装示例

描述

示例

标准json 类型

{

"url":"www.vip.com",

"start_time":"2014-06-10 14:53:21",

"hashcode":"abcdefg"

}

标准xml 类型

www.vip.com2014-06-10 14:53:21abcdefg

四、API签名

调用API时需要对请求参数进行签名，VOP服务器端会验证请求参数是否合法。 也可以通过签名验证工具进行验证

签名验证工具

签名算法：

第1步、对除appSecret外的所有系统级参数进行按照首字母先后顺序排列

例如：将service,method,version,timestamp,format,appKey排序为appKey,format,method,service,timestamp,version

第2步、 把排序后的结果按照参数名+参数值的方式拼接后再拼接上应用级参数

例如：appKeyXXXXformatXXXXmethodXXXXserviceXXXXtimestampXXXXversionXXXXYYYY,其中YYYY是应用级参数

第3步、 以appSecret作为秘钥对拼装好的字符串进行hmac-md5加密

例如：hmac-md5(appKeyXXXXformatXXXXmethodXXXXserviceXXXXtimestampXXXXversionXXXXYYYY,appSecret)

得到结果：2CA5D80723A40B59E095A4D675D46449 ---字母要大写

示例(以下示例只体现逻辑)

调用vipapis.address.AddressService.getFullAddress，假设appKey=yourappKey、appSecret=yourappSecret

1、系统级输入参数：

service=vipapis.address.AddressService

method=getFullAddress

version=1.0.0

timestamp=1406851200

format=json

appSecret=yourappsecret

appKey=yourappkey

2、应用级输入参数：

{"area_code":"0","is_show_gat":"SHOW_GAT","is_bind":false}

3、把除appSecret外的所有系统级参数按照字母顺序排列

appKey=yourappKey

format=json

method=getFullAddress

service=vipapis.address.AddressService

timestamp=1406851200

version=1.0.0

4、把排序后的系统级参数按照参数名+参数值连接起来，并把应用级参数值放在最后，形成最终的拼接字符串

appKeyyourappKeyformatjsonmethodgetFullAddressservicevipapis.address.AddressServicetimestamp1406851200version1.0.0{"area_code":"0","is_show_gat":"SHOW_GAT","is_bind":false}

5、以appSecret作为秘钥对上述拼装好的字符串进行hmac-md5加密，得到签名结果：

2880112276AB2FB2187DABA140B4DACC

五、拼装HTTP请求

调用API时，将所有的系统级参数转换成UTF-8编码，以拼接在URL后面，作为Query String；应用级参数放在POST的消息主体(entity-body)中，提交到正式(或沙箱)环境入口地址，就可以获取接口返回的数据。

六、API调用注意事项

• 所有的API请求和响应数据编码皆为UTF-8格式，URL里的所有参数值请做urlencode编码

• API请求的应用级参数需要转换成xml或json格式

• 返回结果格式与你选择的请求格式一致

• 签名方式为 hmac-md5(params,appSecret)，其中params是按参数名字母顺序排序后拼接而成的

• 输入参数请按照规范进行拼接，应用级输入参数不应该出现在系统级参数中

• 设置contentType为application/json或application/xml

七、API调用示例

JAVA参考示例：

PHP参考示例：

C#参考示例：