1. 对接环境

1.1. 文档中用到的名词

外部：可以是平台方，也可以第三方，泛指需要对接网仓的外部系统

host：网仓服务接口地址：http://ecmapi.iscs.com.cn/openapi/do

     测试地址：http://testapi.iscs.com.cn/openapi/do

 

appKey ：用于标识接入网仓的客户id

appSecret ：用于标识接入网仓的客户接口密钥，加密签名用，不需要提交

method：调用的API接口方法名称

format：响应格式。默认json,目前支持格式为xml/json

product: 商家编码 一个product下可以有多个sku 比如：衣服的款号

sku: 库存最小单位 规格 比如：某款衣服下一个具体的颜色尺寸就是一个sku

1.2. 双方约定

1.同一app（即同一外部系统）相同货主 下不允许出现相同条码

 2.接口中请求的格式数据url编码后（utf-8）赋值给v_data并以post方式传送。

 3.返回数据格式  以cancelTrade为例

Xml格式：

<?xml version=”1.0” encoding=”utf-8”?>

<xmlData>

<errorText>Api call error</errorText>

<subMessage>1001没有调用cancelTrade的权限</subMessage>

<data>

<flag>false</flag>

<reason>订单已发货</reason>

</data> 

<errorCode>540</errorCode>

</xmlData>

Json格式：

{“errorText”:””,”subMessage”:””,”data”:{“flag”:”true”,”reason”:””},”errorCode”:”100”}

{“errorText”:”code:189,message:未找到订单!”,”data”:””,”errorCode”:”190”}

接口中的返回的数据在<data></data>里

1. 请求数据最外面一个节点(xml格式时)与请求method一致，采用驮峰标识，其它节点都是小写字母+下划线组成，返回的data数据里面全部都是小写字母+下划线组成

2. 若采用json格式:请求、返回值均使用字符类型

3. 采用xml格式时 特殊字符需要转义

< < 小于号
> > 大于号
& & 和
' ' 单引号
" " 双引号

 

 

2. 接口说明

 

2.1. 二维码推送

外部通知网仓访客二维码

2.1.1. 接口描述

外部系统中的访客二维码注册到网仓

请求method： registerQRCode

字段说明

名称

类型

是否必须

示例值

默认值

描述

full_name

VARCHAR2(200)

Y

 

 

全称

sex

Int

N

0男性，1女性

0

性别

mobile

VARCHAR2(50)

N

 

 

联系电话

card_id

VARCHAR2(200)

N

 

 

证件号

stock_id

VARCHAR2(50)

N

 

 

访问仓库

begin_date

DATE

Y

2014-01-01 00:00:00

 

开始时间

end_date

DATE

Y

2015-01-01 00:00:00

 

结束时间

reception_person

VARCHAR2(50)

N

 

 

接待人

qr_code_url

VARCHAR2(200)

Y

http://10.10.0.5/qrcod.png

 

二维码

qr_code

VARCHAR2(500)

Y

 

 

二维码实际内容

 

 

 

 

 

 

 

2.1.2. 请求格式

Xml格式：

< registerQRCode >

<full_name></full_name>

<sex></ sex >

< mobile ></ mobile >

< cardId ></ cardId >

< stock_id ></ stock_id>

<begin_date></ begin_date >

< end_date ></ end_date >

< reception_person ></ reception_person >

< qrcodeurl > </ qrcodeurl >

< qrcode> </ qrcode >

 

</ registerQRCode >

JSON格式:

{

“full_name”: “张三”,

“sex”: 0,

“mobile”: “15908822773,

“cardid”: “330XXXXXXXXXX,

“stock_id”: “2018,

“begin_date”: “2014-01-01 00:00:00”,

“end_date”: “2015-01-01 00:00:00”,

“reception_person”: “王五”,

“qr_code”:” 5L2Z5pel56WlMTky5rWL6K+V5LqM57u056CB5YWl6Zeo”,

“qr_code_url”:” http://10.10.0.5/qrcod.png”

}

2.1.3. 输出格式

XML输出格式：

<flag>true or false</flag>

< stock_id >成功则返回的stock_id </ stock_id >

或：

<flag>true or false</flag>

<reason>失败原因</reason>

 

JSON输出格式:

        “flag”: “true”,

        “stock_id”: 260154

或

“flag”: “true”,

“reason”:”已注册”

2.1.4. 补充说明

一次注册一个二维码

3. 安全性及数据完整性

数据使用HTTP POST方式发送，请求方法的编码格式：application/x-www-form-urlencoded; charset=utf-8

调用接口(API)时需要对请求参数进行签名验证，API系统会对该请求参数进行验证是否合法，所有数据编码格式使用utf-8，以下是参数说明

 

参数

参数说明

备注

v_appkey

对应的APPKEY

上线后网仓分配

v_timestamp

时间戳，与服务器时间相差要在10分钟内

2012-10-31 17:45:40

v_appsign

加密签名

加密后数据

v_method

调用的api名称

请求的接口名称

v_data

提交的数据

数据经过url(utf-8)编码后赋值给v_data

v_format

数据格式

可选xml/json，默认json

 

加密签名算法

 

系统使用MD5加密方式将appkey + appsecret + timestamp拼接为字符串进行md5加密后，再转化成大写，格式是：byte2hex (md5(v_appkey+v_appsecret+v_timestamp))

注：byte2hex为自定义方法，JAVA中MD5是对字节数组加密，加密结果是16字节，需要转换为32位的大写字符串，如生成签名：32位大写MD5值: 5029C3055D51555112B60B33000122D5

 

4. 调用示例

http://ecmapi.iscs.com.cn/openapi/do?v_appkey=100001&v_appsign=5029C3055D51555112B60B33000122D5&v_format=xml&v_ timestamp=2012-10-31 17:45:40&v_method=pushProducts

String v_appkey = "1900001";

String v_appsecret = "wangyingapp130705";

String v_timestamp = DateUtil.toDateString(new Date(), "yyyy-MM-dd HH:mm:ss");

String v_format = "json";//请求数据格式

String v_method = "";//接口方法

String v_appsign ;

String v_data="";//具体的请求参数，xml格式或者json格式

try {

v_appsign = AppKeyCache.md5(v_appkey + v_appsecret + v_timestamp).toUpperCase();//加密得到签名

String v_url = "";//接口地址，文档开头已给出

String postData = "v_appkey=" + v_appkey + "&v_appsign=" + v_appsign + "&v_format=" + v_format + "&v_timestamp=" + v_timestamp + "&v_method=" + v_method + "&v_data=" + v_data;

Map<String, String> http_properties = new HashMap<String, String>();

http_properties.put("Content-type", "application/x-www-form-urlencoded;charset=" + "utf-8");

Document doc = null;

try {

doc = FileUtil.httpAccessUTF8(v_url, http_properties, "POST", postData, "utf-8");//http请求

} catch (Exception e) {

e.printStackTrace();

}

} catch (Exception e) {

e.printStackTrace();

}