鉴权上次更新时间: 2020-11-02

注册

生成公私钥

客户使用密钥对生成工具生成一对公私钥，公钥提供给贝仓，私钥由客户保管。生成密钥位数为2048，格式为PKCS8，可由在线工具或者其他工具生成，参考支付宝开放平台开发助手。由于私钥对安全性要求比代码更高，所以私钥不能写在代码里，需妥善保管，防止泄露。

签名

算法

采用RSA2 SHA256WithRSA算法进行签名。

签名过程

签名字段名为bsign，该字段不参与签名。
将URL中的参数按照参数名字典顺序排序，并拼接为string1 = key1value1key2value2的格式。
将请求体（json）中的参数，按照参数名进行字典顺序排序，并拼接为string2 = key3value3key4value4的格式，注意签名只针对json中第一层value为String，Number，Boolean三种类型进行，嵌套json忽略，并拼接为string1 = key1value1key2value2的格式。
将string1与string2进行拼接成string3 = string1string2，客户使用私钥进行签名。
签名字段bsign放在URL中进行接口请求。
完整示例代码请见 ClientDemo.java

请求地址

https://gw.beicang.com/

测试和正式环境均使用此域名

公共参数

系统级公共参数为每次请求必带的参数，以URL参数方式传递。

参数名	必须	类型	说明
appId	是	String	客户appId
appKey	是	String	客户appKey
timestamp	是	Long	秒级时间戳，5分钟内的请求有效
bsign	是	String	签名
method	是	String	接口名
version	否	String	接口版本，默认为1

其他参数可以以URL参数方式传递，也可以content-type=application/json的请求体在POST中传递，例如：

https://gw.beicang.com/openapi?method=beicang.outer.brand.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1&pageNo=1&pageSize=20

返回结果

接口成功时http响应码为200，返回数据为业务接口结果，具体以业务接口文档为准，失败为5xx，4xx等，返回内容为错误信息。

{
    "message":"错误信息",
    "gwCode":"0001"
}

code为网关错误码，定义如下：

code	含义
0001	非法method
0002	非法appId
0003	非法appKey
0004	非法签名
0005	非法时间戳
0006	服务超时
0007	非法IP
0008	访问被限制
0000	其他错误

商品

以下接口涉及到价格的，单位统一为分。错误码：

code	含义
0001	非法method
0002	非法appId
0003	非法appKey
0004	非法签名

查询专场列表

请求地址：

https://gw.beicang.com/openapi?method=beicang.outer.brand.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
pageNo	是	Integer	当前页
pageSize	是	Integer	分页大小，不传默认20
gmtBegin	否	Integer	unix时间戳，专场开始时间最小值，需要和gmtBeginLimit配合使用
gmtBeginLimit	否	Integer	unix时间戳，专场开始时间最大值。当gmtBegin和gmtBeginLimit都传时，按照时间筛选专场，否则返回在售的品牌专场

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
brandList	List	专场列表
eventId	String	专场ID
unit	String	品牌商品个数单位
brandName	String	品牌名称
brandId	String	品牌ID
count	Integer	品牌商品个数
brandIcon	String	品牌图片
category	String	分类名称
categoryId	Integer	分类Id
isNormal	Boolean	是否实体店专场 [true:是 false:否]，实体店专场一般为一个月以上
nonDeliveryArea	String	不发货区域字段，目前默认都是同一个
gmtBegin	Long	专场开始时间戳
gmtEnd	Long	专场结束时间戳
brandDesc	String	品牌描述
brandImage	String	专场海报图
brandTagList	List	品牌标签，文案
content	String	内容
textColor	String	文本颜色
backgroundColor	String	背景色
hasMore	Boolean	是否有下一页
pageNo	Integer	当前页
pageSize	Integer	每页大小

查询专场素材

URL：

https://gw.beicang.com/openapi?method=beicang.outer.event.material.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
eventId	是	String	专场ID

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
materialList	List	素材列表
materialId	String	素材ID
eventId	String	专场ID
fileType	Integer	类型：[1:文件 2:视频]
imgs	List	图片集合
videoUrl	String	视频链接
videoFirstFrame	String	视频封面链接
content	String	文案
nick	String	昵称
avatar	String	头像
icon	String	昵称icon

查询专场商品列表

URL：

https://gw.beicang.com/openapi?method=beicang.outer.item.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
eventId	是	String	专场ID
iid	否	String	货号
keywords	否	String	模糊查询，如标题
pageNo	是	Integer	当前页
pageSize	是	Integer	分页大小，不传默认20

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
itemList	List	商品列表
iid	String	商品ID
title	String	名称
originPrice	Integer	原价
advicePrice	Integer	零售价
promotionPrice	Integer	贝仓大促价
price	Integer	拿货价 (单位:分)
itemStatus	Integer	商品状态 [1:有效]
gmtBegin	Long	开始时间
stockStatus	Integer	库存状态 [0:下架 1:有效]
itemSize	String	商品大小字符串 [36/37/38/39/40]
eventId	String	专场ID
intros	String	商品介绍
images	List	商品图片集合
shortNumber	String	短码
hasMore	Boolean	是否有下一页
pageNo	Integer	当前页
pageSize	Integer	每页大小

查询常态品牌列表

URL：

https://gw.beicang.com/openapi?method=beicang.outer.normal.brand.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
pageNo	是	Integer	当前页
pageSize	是	Integer	分页大小，不传默认20

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
brandList	List	品牌列表
brandId	String	品牌ID
brandName	String	品牌名称
brandIcon	String	品牌图片
brandDesc	String	品牌描述
hasMore	Boolean	是否有下一页
pageNo	Integer	当前页
pageSize	Integer	每页大小

查询常态商品列表

URL：

https://gw.beicang.com/openapi?method=beicang.outer.normal.item.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
categoryId	否	Long	分类ID
brandId	否	String	品牌ID
title	否	String	标题，支持模糊查询
pageNo	是	Integer	当前页
pageSize	是	Integer	分页大小，不传默认20

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
itemList	List	商品列表
iid	String	商品ID
title	String	名称
originPrice	Integer	原价
advicePrice	Integer	建议零售价
promotionPrice	Integer	贝仓大促价
price	Integer	拿货价 (单位:分)
itemStatus	Integer	商品状态 [1:有效]
gmtBegin	Long	开始时间
stockStatus	Integer	库存状态 [0:下架 1:有效]
itemSize	String	商品大小字符串 [36/37/38/39/40]
intros	String	商品介绍
images	List	商详图片集合，第一张为主图
brandId	String	品牌ID
brandName	String	品牌名称
brandLogo	String	品牌Logo
cids	List	所属分类ID集合，比如：2,19,77，分别代表一、二、三级类目ID，有几条数据就代表有几级类目
categoryNames	List	所属分类名称集合，比如：童鞋,靴子,皮靴，分别代表一、二、三级类目名，与上面的cids匹配
shortNumber	String	短码
hasMore	Boolean	是否有下一页
pageNo	Integer	当前页
pageSize	Integer	每页大小

查询场景商品列表

URL：

https://gw.beicang.com/openapi?method=beicang.outer.scene.item.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
sceneId	是	Integer	场景ID [1:大牌制造精选第一个为今日爆款；2：淘货]
categoryTab	否	String	类目tab，传key值，默认为精选 (all)
timeSlotId	否	Integer	淘货场景时间轴id
pageNo	是	Integer	当前页
pageSize	是	Integer	分页大小，不传默认20

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
itemList	List	商品列表
iid	String	商品ID
title	String	名称
sellPoint	String	卖点介绍
mainImg	String	商品主图
images	List	商品图片集合
originPrice	Integer	原价
advicePrice	Integer	零售价
promotionPrice	Integer	贝仓大促价
price	Integer	拿货价 (单位:分)
itemStatus	Integer	商品状态 [1:有效其他无效]
gmtBegin	Long	开始时间
gmtEnd	Long	结束时间
brandId	String	品牌ID
brandName	String	品牌名称
brandLogo	String	品牌Logo
categoryTab	List	类目tab，页码为1时返回
key	String	类目key
name	String	类目名称
timeSlotTab	List	时间轴tab
timeSlotId	String	时间轴id
title	String	时间轴标题
hasMore	Boolean	是否有下一页
pageNo	Integer	当前页
pageSize	Integer	每页大小
currentTab	String	当前tab
currentTimeSlot	Integer	当前时间轴

查询商品类目

URL：

https://gw.beicang.com/openapi?method=beicang.outer.category.list
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
cateGoryId	否	Long	查询类目的id
pageNo	是	Integer	页码
pageSize	是	Integer	页数

响应结果：

参数	类型	说明
success	Boolean	成功失败标志[true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
categorys	List	类目列表
id	Long	类目ID
name	String	类目名
level	Integer	类目的层级(1,2,3)
hasMore	Boolean	是否有下一页
page	Integer	当前页
pageSize	Integer	页数
total	Integer	总数

查询商品详情

URL：

https://gw.beicang.com/openapi?method=beicang.outer.item.detail.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
itemId	是	String	商品ID

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
iid	String	商品ID
title	String	名称
originPrice	Integer	原价
advicePrice	Integer	零售价，仅做参考
promotionPrice	Integer	贝仓大促价
price	Integer	拿货价(单位分)
itemStatus	Integer	商品状态 [1:有效]
gmtBegin	Long	开始时间
stockStatus	Integer	库存状态 [0:下架 1:有效]
itemSize	String	商品大小字符串 [36/37/38/39/40]
intros	String	商品介绍
brandId	String	品牌ID
brandName	String	品牌名称
brandLogo	String	品牌Logo
shortNumber	String	短码
productCode	String	商品款号
images	List<String>	商品图片集合
cids	List<Long>	所属分类ID集合，比如:2,19,77分别代表:一、二、三级类目id，有几条数据就代表有几级类目
categoryNames	List<String>	所属分类名称集合，比如:童鞋,靴子,皮靴，分别代表一、二、三级类目名，与上面的cids匹配
skuArea	List<Object>	商品SKU集合
outerSkuId	String	商品外部编码，直接作为唯一标识，不依赖iid
price	Integer	拿货价
advicePrice	Integer	建议零售价，可自主加价
stock	Integer	库存
originPrice	Integer	原价
promotionPrice	Integer	贝仓大促价
validDate	Integer	效期。时间戳形式。大于0时可使用
skuProperty	Map<String,String>	sku属性
nonDeliveryAddress	List<Object>	不发货地区
province	String	省
city	String	市
area	String	区
shippingFrom	String	发货地
pid	String	值相同的常态和专场商品为同款
nonFreeShippingAreas	List<String>	不包邮地区

批量查询商品库存

URL：

https://gw.beicang.com/openapi?method=beicang.outer.item.stock.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
iids	否	String	逗号分隔商品IID，一批最多99个
eventId	否	String	专场ID，与iids二选一
pageNo	否	String	通过eventId查询时需要传，从1开始

响应结果：

参数	类型	说明
success	Boolean	成功失败标志 [true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
itemList	List	商品库存列表
outerSkuId	String	商品外部编码
stock	Integer	库存
hasMore	Boolean	是否有下一页，通过eventId获取时需要关注
pageNo	Integer	当前页

批量查询专场状态

URL：

https://gw.beicang.com/openapi?method=beicang.outer.brand.status.list.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

GET

请求参数：

参数	必须	类型	说明
eventIds	是	String	逗号分隔商品eventIds（最多99个）

响应结果：

参数	类型	说明
success	Boolean	成功失败标志[true:成功 false:失败]
message	String	成功失败提示
errorCode	Integer	错误码
data	Object
brandStatusList	List	专场列表
eventId	String	专场ID
gmtBegin	Long	最新的专场开始时间
gmtEnd	Long	最新的专场结束时间
isOver	Boolean	专场是否结束

交易

联调时请用测试商品下单，访问:常见问题

以下接口涉及到价格的，单位统一为分。错误码：

code	含义
2010	无效的商品
2020	无效的地址
2030	无效的购买数量
2040	无效的库存
2050	创建订单失败
2060	支付订单失败
2070	余额不足
2110	取消订单失败
3010	无订单物流信息
3020	更新订单地址失败

订单状态表：

code	含义
1	已创建，等待支付
2	已付款，等待发货
3	已发货，等待收货
4	已确认收货
-1	已取消

创建并支付订单

下单前请保证账户内余额充足，否则会下单失败

URL：

https://gw.beicang.com/openapi?method=beicang.outer.trade.create.pay
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
itemList	是	List<Object>	商品列表
outerSkuId	是	String	商品外部编码
num	是	Integer	购买数量
outerTid	是	String	商户的订单ID
province	是	String	省
city	是	String	市
area	是	String	区
addressDetail	是	String	除了省市区外的地址
fullName	是	String	收货人姓名
mobile	是	String	收货人手机号
outerGmtPayed	是	Long	外部平台支付时间戳（秒）
remark	否	String	备注，200字符以内

响应结果：

参数	类型	说明
success	Boolean	创建订单是否成功 [true:成功;false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	交易信息
tid	String	订单ID
payment	Long	支付总金额
shippingFee	Long	物流费用
orderList	List<Object>	订单信息
oid	String	订单号
payment	Long	订单支付金额
itemList	List<Object>	订单内的商品
outerSkuId	String	商品外部编码
num	Integer	购买数量
singleSkuPayment	Long	支付商品的单个sku金额
invalidItemList	List<Object>	无效的商品，错误码为2010或2040时返回
outerSkuId	String	商品外部编码

创建订单

创建订单后超过30分钟未支付，系统会自动关单

URL：

https://gw.beicang.com/openapi?method=beicang.outer.trade.create
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
itemList	是	List<Object>	商品列表
outerSkuId	是	String	商品外部编码
num	是	Integer	购买数量
outerTid	是	String	商户的订单ID
province	是	String	省
city	是	String	市
area	是	String	区
addressDetail	是	String	除了省市区外的地址
fullName	是	String	收货人姓名
mobile	是	String	收货人手机号
remark	否	String	备注，200字符以内

响应结果：

参数	类型	说明
success	Boolean	创建订单是否成功 [true:成功;false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	交易信息
tid	String	交易ID
payment	Long	支付总金额
shippingFee	Long	物流费用
orderList	List<Object>	订单信息
oid	String	订单号
payment	Long	订单支付金额
itemList	List<Object>	订单内的商品
outerSkuId	String	商品外部编码
num	Integer	购买数量
singleSkuPayment	Long	支付商品的单个sku金额
invalidItemList	List<Object>	无效的商品，错误码为2010或2040时返回
outerSkuId	String	商品外部编码

支付订单

URL：

https://gw.beicang.com/openapi?method=beicang.outer.trade.pay
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
tid	是	String	交易号
outerGmtPayed	是	Long	外部平台支付时间戳（秒）

响应结果：

参数	类型	说明
success	Boolean	操作是否成功
message	String	提示信息
errorCode	Integer	错误码
data	Object	交易信息
tid	String	交易tid

取消订单

仅待发货状态的订单可申请取消。支付后30分钟内可直接取消，30分钟后需商家同意才能取消。商家会在6小时内确认，超时系统自动同意。不支持部分取消。

URL：

https://gw.beicang.com/openapi?method=beicang.outer.order.cancel
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	String	订单号
reason	是	Integer	原因 1.买错了 2.不想买了 3.信息填写错误，重新下单 4.重复购买 5.其他原因

响应结果：

参数	类型	说明
success	Boolean	操作是否成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object
cancelStatus	Integer	取消状态 [1:取消成功 2:等待商家同意]

查询订单取消状态

URL：

https://gw.beicang.com/openapi?method=beicang.outer.order.cancel.status.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	String	订单号

响应结果：

参数	类型	说明
success	Boolean	操作是否成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	数据信息
cancelStatus	Integer	取消状态 [1.取消成功 2.等待商家同意 3.卖家拒绝（直接发货）]
applyReturnLeftTime	Integer	等待商家确认超时自动取消订单剩余时间

修改地址

支付后30分钟内可以修改地址

URL：

https://gw.beicang.com/openapi?method=beicang.outer.order.address.update
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	String	订单号
province	是	String	省
city	是	String	市
area	是	String	区
addressDetail	是	String	除了省市区外的地址
fullName	是	String	收货人姓名
mobile	是	String	收货人手机号

响应结果：

参数	类型	说明
success	Boolean	操作是否成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码

确认收货

URL：

https://gw.beicang.com/openapi?method=beicang.outer.order.confirm
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	String	订单号

响应结果：

参数	类型	说明
success	Boolean	操作是否成功
message	String	错误信息
errorCode	Integer	错误码
data	Object
oid	String	交易oid

查询物流

URL：

https://gw.beicang.com/openapi?method=beicang.outer.order.shipment.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	String	订单号

响应结果：

参数	类型	说明
success	Boolean	请求是否成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	数据信息
fullShipment	List	所有的物流信息
company	String	物流公司
outsid	String	运单号

售后

目前只支持两种售后类型：退款、退货退款；补发错发换货暂不支持，建议一律以退货退款方式处理。
接口对申请售后的时间没有限制，但确认收货超过7天的售后可能被拒绝。
发货前的订单不支持售后，请调用取消订单接口。
支持部分商品（sku维度）售后，同一个商品不能多次发起售后。

以下接口涉及到价格的，单位统一为分。错误码：

code	含义
4010	无效的订单
4020	无效的售后单
4030	无效的售后状态
4040	申请售后失败
4050	获取售后详情失败
4060	更新售后物流信息失败

售后状态表：

状态码	状态	售后状态
1	等待平台审核	处理中
2	等待寄回商品	处理中
3	等待商家收货	处理中
4	售后完成	售后完成
5	等待系统打款	售后完成
6	等待商家处理	处理中
9	待二次举证	处理中
11	物流拦截中	处理中
12	已签收待确认收货	处理中
-1	售后取消	售后取消
-2	待仲裁	处理中
-3	售后关闭	售后关闭
-4	退货待仲裁	处理中
-6	审核未通过	处理中

售后状态流转图：

申请售后

已发货才能申请，待发货请调用取消订单接口

URL：

https://gw.beicang.com/openapi?method=beicang.outer.refund.apply
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	String	订单号
outerRefundId	是	String	外部售后单号
outerSkuId	是	String	商品外部编码
refundType	是	String	申请售后的类型<2：仅退款，3：退货退款>
productStatus	是	Integer	商品状态：售后类型=2时，可选：1：未收到货，2：已收到货。售后类型=3时，只能是2：已收到货>
reason	是	Interger	售后原因当商品状态=1时，售后原因有：60商品漏发，61：未收到货；当商品状态=2时，售后原因：90 商品与描述不符，91：商品漏发，92：商家发错货了，93：拍错/多拍，94：面料/材质/质量问题，95：大小尺寸不符，96：不喜欢/穿着效果不好>
number	是	Integer	售后商品数量，不能超过商品购买数量
refundAmt	是	Integer	售后金额，不能超过商品购买金额(单位分)
imgs	否	String	售后图片凭证，多张图片以分号分隔，最多5张图
desc	是	String	售后理由，1~500个字

响应结果：

参数	类型	说明
success	Boolean	是否创建售后单成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	售后单信息
refundId	String	售后ID
returnAddress	String	售后退货地址（聚合地址）
returnProvince	String	省
returnCity	String	市
returnArea	String	区
returnProvinceCode	Long	省id
returnCityCode	Long	市id
returnAreaCode	Long	区id
returnAddressDetail	String	除了省市区外的地址
returnContacts	String	售后退货联系人
returnTel	String	售后退货电话号码

查询售后详情

URL：

https://gw.beicang.com/openapi?method=beicang.outer.refund.detail.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
refundId	是	String	售后ID

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	售后单信息
refundId	String	售后ID
oid	String	订单号
outerSkuId	String	商品外部编码
refundType	Integer	申请售后的类型：<2：仅退款，3：退货退款>
refundStatus	Integer	售后状态码，参见上面的售后状态表
canSupplementReason	Boolean	是否支持补充售后理由
num	Integer	售后数量
refundAmt	Integer	售后金额（单位分）
returnAddress	String	售后退货地址（聚合地址）
returnProvince	String	省
returnCity	String	市
returnArea	String	区
returnProvinceCode	Long	省id
returnCityCode	Long	市id
returnAreaCode	Long	区id
returnAddressDetail	String	除了省市区外的地址
returnContacts	String	售后退货联系人
returnTel	String	售后退货电话号码

更新售后物流

URL：

https://gw.beicang.com/openapi?method=beicang.outer.refund.shipment.update
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
refundId	是	String	售后ID
outSid	是	String	物流单号
company	是	String	物流公司，包括有：邮政国内，申通，圆通，中通，韵达，EMS，百世快递，天天，顺丰，宅急送，京东物流，快捷快递，国通快递，八达通，德邦物流，优速物流，佳吉快运，佳成快递，易达通

响应结果：

参数	类型	说明
success	Boolean	是否更新物流信息成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	售后单信息
refundId	String	售后ID

补充售后理由

URL：

https://gw.beicang.com/openapi?method=beicang.outer.refund.supplement
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
refundId	是	String	售后ID
imgs	是	String	售后图片凭证，多张图片以分号分隔，最多5张图
desc	是	String	售后理由，1~500个字

响应结果：

参数	类型	说明
success	Boolean	是否补充信息成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	售后单信息
refundId	String	售后ID

取消售后

URL：

https://gw.beicang.com/openapi?method=beicang.outer.refund.cancel
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
refundId	是	String	售后ID

响应结果：

参数	类型	说明
success	Boolean	是否取消售后成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	取消售后信息
refundId	String	售后ID
refundStatus	Integer	售后状态
refundOperateTime	Long	售后取消时间

消息推送

如果客户希望感知开放平台内部数据（订单、商品、售后）的变化，需要订阅贝仓的推送服务，贝仓会将需要的数据推送给客户。

客户需要提供一个消息监听的地址，推荐采用http协议，端口使用80。
客户应该做好消息内容的签名校验，由贝仓分配公钥，开放平台会提供校验签名的jar包。
客户应该及时返回echostr，如果超过3秒未返回，会被认为是服务器响应超时，触发贝仓开放平台的消息的重推机制。
客户接口应该做好幂等，避免重复消费消息。
系统级公共参数为以URL参数方式传递，消息内容使用POST方式传递，格式Content-type=application/json。

请求参数：

参数	必须	类型	说明
msgType	是	String	消息类型，参见下文
timestamp	是	Long	秒级时间戳，5分钟内的请求有效
bsign	是	String	签名，用于商户验证消息的正确性
version	否	String	接口版本，默认为1
echostr	是	String	商家应该返回的字符串

代码示例：

接口定义

@Path("http/consumer/demo")
@Consumes({ ContentType.APPLICATION_JSON_UTF_8, ContentType.TEXT_XML_UTF_8 })
@Produces({ ContentType.APPLICATION_JSON_UTF_8, ContentType.TEXT_XML_UTF_8 })
public interface HttpDemoService {

    @POST
    @Path("consumer")
    String postDemo(@QueryParam("version") Integer version, @QueryParam("timestamp") Long timestamp,
                    @QueryParam("echostr") String echostr, @QueryParam("msgType") String msgType,
                    @QueryParam("bsign") String bsign);

    @POST
    @Path("testMq")
    String consumerMq(TestMqMessageTO to);
}

接口实现

@Service(protocol = {"dubbo", "rest"}, timeout = 3000)
public class HttpDemoServiceImpl implements HttpDemoService {

    private static final String PUBLIC_KEY = "XXX";

    @Resource
    private RocketNotifyMerchantMqHandler rocketNotifyMerchantMqHandler;

    @Override
    public String postDemo(Integer version, Long timestamp, String echostr, String msgType,
                           String bsign) {
        // 获取post内容
        Map<String, Object> bodyParams;
        try {
            bodyParams = getPostBody();
        } catch (Exception e) {
            return e.getMessage();
        }

        Map<String, String> urlParams = new HashMap<>(4);
        urlParams.put("timestamp", String.valueOf(timestamp));
        urlParams.put("echostr", echostr);
        urlParams.put("version", String.valueOf(version));
        urlParams.put("msgType", msgType);

        // 执行签名校验,如果校验为false，说明非合法的贝仓消息通知，如果校验通过，则继续执行下面的业务逻辑
        try {
            boolean checkResult = RsaSignUtils.checkSign(urlParams, bodyParams, PUBLIC_KEY, bsign);
            System.out.println("签名校验结果:" + checkResult);
        } catch (Exception e) {
            return e.getMessage();
        }

        System.out.println("正常执行下面的业务逻辑");

        // 返回入参的echostr
        return echostr;
    }

    private Map<String, Object> getPostBody() throws IOException {
        HttpServletRequest request = (HttpServletRequest) RpcContext.getContext().getRequest();
        BufferedReader br = new BufferedReader(
                        new InputStreamReader(request.getInputStream(), Charset.defaultCharset()));
        StringBuffer bodySb = new StringBuffer();
        String temp;
        while ((temp = br.readLine()) != null) {
            bodySb.append(temp);
        }
        System.out.println("body:" + bodySb.toString());

        JSONObject jsonObject = JSONObject.parseObject(bodySb.toString());

        Map<String, Object> fianlBodyParams = new HashMap<>(4);
        jsonObject.keySet().stream().forEach(key ->
                fianlBodyParams.put(key, jsonObject.get(key)));
        return fianlBodyParams;
    }

    @Override
    public String consumerMq(TestMqMessageTO to) {
        MessageExt messageExt = new MessageExt();
        org.springframework.beans.BeanUtils.copyProperties(to, messageExt);
        messageExt.setBody(to.getBody().getBytes(Charset.defaultCharset()));
        RocketMqMessage<RocketMqNotifyMerchantBody> message = rocketNotifyMerchantMqHandler.buildMessage(messageExt);
        try {
            rocketNotifyMerchantMqHandler.handlerMessage(message);
        } catch (Exception e) {
            return e.getMessage();
        }
        return HttpConstants.DEFAULT_ECHOSTR;
    }
}

如需订阅相关消息，请访问:消息订阅

专场状态变更消息 `item_situation_info`

专场排期或状态更改时推送

参数	类型	说明
eventId	String	专场id
gmtBegin	Long	专场开始时间戳
gmtEnd	Long	专场结束时间戳
eventStatus	Integer	专场状态 1:正常 -1:下架

商品状态变更消息 `item_status_change`

商品上下架状态更改时推送

参数	类型	说明
iid	String	商品iid
itemStatus	Integer	1:上架 -1:下架

商品库存变更消息 `item_stock`

商品库存低于阈值时推送

参数	类型	说明
outerSkuId	String	商品外部编码
stock	Integer	商品库存

常态商品上新消息 `normal_item_on_shelf`

参数	类型	说明
iid	String	商品的itemId

常态商品价格变更消息 `sku_price_change`

参数	类型	说明
outerSkuId	String	商品外部编码
price	Integer	商品变更后的价格

订单物流消息 `order_shipment`

订单发货时推送，一个订单可能有多个物流

参数	类型	说明
outerTid	String	外部交易号
tid	String	交易号
oid	Long	订单号
orderStatus	Integer	订单状态
fullShipment	ArrayList	全部物流信息
company	String	物流公司
outSid	String	物流单号

订单取消结果消息 `cancel_status`

订单取消后的结果通知。注意：30分钟内的订单，调用接口会直接取消成功，不会通知

参数	类型	说明
outerTid	String	外部交易号
tid	String	交易号
oid	Long	订单号
cancelStatus	Integer	订单取消的状态 1：取消成功， 3：卖家拒绝（已发货）

物流修改消息 `order_reshipment`

商家修改物流信息时推送

参数	类型	说明
outerTid	String	外部交易号
tid	String	交易号
oid	Long	订单号
orderStatus	Integer	订单状态
fullShipment	ArrayList	全部物流信息
company	String	物流公司
outSid	String	物流单号

售后创建消息 `system_create_refunding`

客服主动帮用户创建售后时推送

参数	类型	说明
outerTid	String	外部交易号
outerRefundId	String	外部售后单号
refundId	String	售后单号
refundAmt	Integer	退款金额
refundUpdateTime	Long	售后状态更新时间，unix时间戳
refundStatus	Integer	售后状态 0:创建售后
outerSkuId	String	商品外部编码
oid	Long	订单号
refundType	Integer	申请售后的类型 2：仅退款，3：退货退款
productStatus	Integer	商品状态：售后类型=2时，可选：1：未收到货，2：已收到货。售后类型=3时，只能是2：已收到货
reasonDesc	String	售后原因描述
number	Integer	售后商品数量，不能超过商品购买数量

售后完成消息 `refund_agree_return_money`

售后完成时推送

参数	类型	说明
outerTid	String	外部交易号
outerRefundId	String	外部售后单号
refundId	String	售后单号
refundAmt	Integer	退款金额
refundUpdateTime	Long	售后状态更新时间，unix时间戳
refundStatus	Integer	售后状态

售后拒绝消息 `refund_refuse_return_money`

售后被拒绝时推送

参数	类型	说明
outerTid	String	外部交易号
outerRefundId	String	外部售后单号
refundId	String	售后单号
reason	String	拒绝原因
imgs	String	图片可能有多张，以分号分隔
refundUpdateTime	Long	售后状态更新时间，unix时间戳
refundStatus	Integer	售后状态

自助联调

自助发货

URL：

https://gw.beicang.com/openapi?method=beicang.outer.tool.ship.deliever
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
oid	是	Long	订单号

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	账户信息
oid	Long	订单号

自助发起退款仲裁

相当于商家发起仲裁

URL：

https://gw.beicang.com/openapi?method=beicang.outer.tool.refund.refuse
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
refundId	是	String	售后单号

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	String	售后单号

自助发起同意仲裁

售后拒绝，推送refund_refuse_return_money消息

URL：

https://gw.beicang.com/openapi?method=beicang.outer.tool.platform.reject
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
refundId	是	String	售后单号

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	String	售后单号

其他

查询账户余额

URL：

https://gw.beicang.com/openapi?method=beicang.outer.account.info.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

无

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	账户信息
tel	String	手机号码
balance	Long	贝仓账户余额

查询账单明细

URL：

https://gw.beicang.com/openapi?method=beicang.outer.account.water.list
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
page	是	Integer	当前页
opType	是	List<String>	操作类型 recharge:充值 pay:支出 income:收入 cancel:取消。示例:["cancel"](目前只支持一个参数操作)
ascGmt	否	Boolean	查询的明细按时间正序，默认是倒序
searchGmtBegin	否	Long	大于该流水时间
searchGmtEnd	否	Long	小于于该流水时间

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	List	余额明细
orderInfo	List<Object>	订单明细
payMent	Long	支付金额
oid	Long	订单id
bizId	String	流水业务凭证id
tid	String	交易id
balanceMoney	Long	这笔明细之后的剩余金额
amt	Long	单笔操作金额
opType	String	操作类型:recharge
addAmt	Boolean	是否是增加金额
opTypeInfo	String	操作描述
gmtCreate	Long	操作创建时间
hasMore	Boolean	是否有下一页
pageSize	Integer	该页总条数
pageNo	Integer	当前页码
totalSize	Integer	总数

查询地址库

URL：

https://gw.beicang.com/openapi?method=beicang.outer.regions.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
level	是	Integer	区域级别:(0～3) 0:获取全部省市区 1:全部省 2:指定parentId的下一级 3:根据传入的id获取省市区信息
parentId	否	Integer	父级id:level大于1的时候必填，父级id，例如（浙江省：330000）
id	否	Integer	区域id: 例如浙江省：330000

响应结果：

参数	类型	说明
success	Boolean	是否操作成功 [true:成功 false:失败]
message	String	错误信息
errorCode	Integer	错误码
data	Object	售后单信息
regions	List
id	Integer	区域id:如120000
name	String	地址名称:天津市
parentId	Integer	父级id:1

计算运费

各个商品单独计算，一批不超过20个

URL：

https://gw.beicang.com/openapi?method=beicang.outer.shipping.fee.get
&appId=xx&appKey=xx&timestamp=xx&bsign=xx&version=1

请求方式：

POST

请求参数：

参数	必须	类型	说明
itemList	是	List<Object>	商品列表
outerSkuId	是	String	商品外部编码
num	是	Integer	购买数量
province	是	String	省
city	是	String	市
area	是	String	区

响应结果：

参数	类型	说明
success	Boolean	操作是否成功
message	String	错误信息
errorCode	Integer	错误码
data	Object	数据信息
shippingFeeList	List<Object>	运费信息
outerSkuId	String	商品外部编码
shippingFee	Integer	运费金额

注册

生成公私钥

签名

算法

签名过程

请求地址

公共参数

返回结果

查询专场列表

查询专场素材

查询专场商品列表

查询常态品牌列表

查询常态商品列表

查询场景商品列表

查询商品类目

查询商品详情

批量查询商品库存

批量查询专场状态

创建并支付订单

创建订单

支付订单

取消订单

查询订单取消状态

修改地址

确认收货

查询物流

申请售后

查询售后详情

更新售后物流

补充售后理由

取消售后

专场状态变更消息 item_situation_info

商品状态变更消息 item_status_change

商品库存变更消息 item_stock

常态商品上新消息 normal_item_on_shelf

常态商品价格变更消息 sku_price_change

订单物流消息 order_shipment

订单取消结果消息 cancel_status

物流修改消息 order_reshipment

售后创建消息 system_create_refunding

售后完成消息 refund_agree_return_money

售后拒绝消息 refund_refuse_return_money

自助发货

自助发起退款仲裁

自助发起同意仲裁

查询账户余额

查询账单明细

查询地址库

计算运费

专场状态变更消息 `item_situation_info`

商品状态变更消息 `item_status_change`

商品库存变更消息 `item_stock`

常态商品上新消息 `normal_item_on_shelf`

常态商品价格变更消息 `sku_price_change`

订单物流消息 `order_shipment`

订单取消结果消息 `cancel_status`

物流修改消息 `order_reshipment`

售后创建消息 `system_create_refunding`

售后完成消息 `refund_agree_return_money`

售后拒绝消息 `refund_refuse_return_money`