导航
一、调用介绍
VOP作为唯品会开放平台的数据出口，用户只需要按照VOP的规范拼装一个正确的请求URL，通过HTTP请求到VOP，即能获取到所需的数据。
二、调用环境入口
环境入口释义：调用API时，需要传入如下地址，获取相应环境下的数据。
沙箱环境入口地址：
正式环境入口地址：
三、调用参数
调用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
是
-05-08
字符类型
warehouse
Warehouse
是
Warehouse.VIP_NH
枚举类型
nav_category_id1
List
否
["123"]
List类型
如下为VOP应用级参数拼装示例
描述
示例
标准json 类型
{
"url":"",
"start_time":"-06-10 14:53:21",
"hashcode":"abcdefg"
}
标准xml 类型
-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#参考示例：
