鉴权 上次更新时间: 2020-06-24

注册

生成公私钥

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

签名

算法

采用RSA2 SHA256WithRSA算法进行签名。

签名过程

  1. 签名字段名为bsign,该字段不参与签名。
  2. 将URL中的参数按照参数名字典顺序排序,并拼接为string1 = key1value1key2value2的格式。
  3. 将请求体(json)中的参数,按照参数名进行字典顺序排序,并拼接为string2 = key3value3key4value4的格式,注意签名只针对json中第一层valueStringNumberBoolean三种类型进行,嵌套json忽略,并拼接为string1 = key1value1key2value2的格式。
  4. string1string2进行拼接成string3 = string1string2,客户使用私钥进行签名。
  5. 签名字段bsign放在URL中进行接口请求。
  6. 完整示例代码请见 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

请求参数:

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

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 brandListList专场列表
  eventIdString专场ID
  unitString品牌商品个数单位
  brandNameString品牌名称
  brandIdString品牌ID
  countInteger品牌商品个数
  brandIconString品牌图片
  categoryString分类名称
  categoryIdInteger分类Id
  isNormalBoolean是否实体店专场 [true:是 false:否],实体店专场一般为一个月以上
  nonDeliveryAreaString不发货区域字段,目前默认都是同一个
  gmtBeginLong专场开始时间戳
  gmtEndLong专场结束时间戳
  brandDescString品牌描述
  brandImageString专场海报图
  brandTagListList品牌标签,文案
   contentString内容
   textColorString文本颜色
   backgroundColorString背景色
hasMoreBoolean是否有下一页
pageNoInteger当前页
pageSizeInteger每页大小

查询专场素材

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
eventIdString专场ID

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 materialListList素材列表
  materialIdString素材ID
  eventIdString专场ID
  fileTypeInteger类型:[1:文件 2:视频]
  imgsList图片集合
  videoUrlString视频链接
  videoFirstFrameString视频封面链接
  contentString文案
  nickString昵称
  avatarString头像
  iconString昵称icon

查询专场商品列表

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
eventIdString专场ID
iidString货号
keywordsString模糊查询,如标题
pageNoInteger当前页
pageSizeInteger分页大小,不传默认20

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 itemListList商品列表
  iidString商品ID
  titleString名称
  originPriceInteger原价
  advicePriceInteger零售价
  priceInteger拿货价 (单位:分)
  itemStatusInteger商品状态 [1:有效]
  gmtBeginLong开始时间
  stockStatusInteger库存状态 [0:下架 1:有效]
  itemSizeString商品大小字符串 [36/37/38/39/40]
  eventIdString专场ID
  introsString商品介绍
  imagesList商品图片集合
  shortNumberString短码
hasMoreBoolean是否有下一页
pageNoInteger当前页
pageSizeInteger每页大小

查询常态品牌列表

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
pageNoInteger当前页
pageSizeInteger分页大小,不传默认20

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 brandListList品牌列表
  brandIdString品牌ID
  brandNameString品牌名称
  brandIconString品牌图片
  brandDescString品牌描述
hasMoreBoolean是否有下一页
pageNoInteger当前页
pageSizeInteger每页大小

查询常态商品列表

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
categoryIdLong分类ID
brandIdString品牌ID
titleString标题,支持模糊查询
pageNoInteger当前页
pageSizeInteger分页大小,不传默认20

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 itemListList商品列表
  iidString商品ID
  titleString名称
  originPriceInteger原价
  advicePriceInteger建议零售价
  priceInteger拿货价 (单位:分)
  itemStatusInteger商品状态 [1:有效]
  gmtBeginLong开始时间
  stockStatusInteger库存状态 [0:下架 1:有效]
  itemSizeString商品大小字符串 [36/37/38/39/40]
  introsString商品介绍
  imagesList商详图片集合,第一张为主图
  brandIdString品牌ID
  brandNameString品牌名称
  brandLogoString品牌Logo
  cidsList所属分类ID集合,比如:2,19,77,分别代表一、二、三级类目ID,有几条数据就代表有几级类目
  categoryNamesList所属分类名称集合,比如:童鞋,靴子,皮靴,分别代表一、二、三级类目名,与上面的cids匹配
  shortNumberString短码
hasMoreBoolean是否有下一页
pageNoInteger当前页
pageSizeInteger每页大小

查询场景商品列表

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
sceneIdInteger场景ID [1:大牌制造 精选第一个为今日爆款;2:淘货]
categoryTabString类目tab,传key值,默认为精选 (all)
timeSlotIdInteger淘货场景时间轴id
pageNoInteger当前页
pageSizeInteger分页大小,不传默认20

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 itemListList商品列表
  iidString商品ID
  titleString名称
  sellPointString卖点介绍
  mainImgString商品主图
  imagesList商品图片集合
  originPriceInteger原价
  advicePriceInteger零售价
  priceInteger拿货价 (单位:分)
  itemStatusInteger商品状态 [1:有效 其他无效]
  gmtBeginLong开始时间
  gmtEndLong结束时间
  brandIdString品牌ID
  brandNameString品牌名称
  brandLogoString品牌Logo
 categoryTabList类目tab,页码为1时返回
  keyString类目key
  nameString类目名称
timeSlotTabList时间轴tab
  timeSlotIdString时间轴id
  titleString时间轴标题
hasMoreBoolean是否有下一页
pageNoInteger当前页
pageSizeInteger每页大小
currentTabString当前tab
currentTimeSlotInteger当前时间轴

查询商品类目

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
cateGoryIdLong查询类目的id
pageNoInteger页码
pageSizeInteger页数

响应结果:

参数 类型 说明
successBoolean成功失败标志[true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 categorysList类目列表
  idLong类目ID
  nameString类目名
  levelInteger类目的层级(1,2,3)
hasMoreBoolean是否有下一页
pageInteger当前页
pageSizeInteger页数
totalInteger总数

查询商品详情

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
itemIdString商品ID

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
  iidString商品ID
  titleString名称
  originPriceInteger原价
  advicePriceInteger零售价,仅做参考
  priceInteger拿货价(单位分)
  itemStatusInteger商品状态 [1:有效]
  gmtBeginLong开始时间
  stockStatusInteger库存状态 [0:下架 1:有效]
  itemSizeString商品大小字符串 [36/37/38/39/40]
  introsString商品介绍
  brandIdString品牌ID
  brandNameString品牌名称
  brandLogoString品牌Logo
  productCodeString商品款号
  imagesList<String>商品图片集合
  cidsList<Long>所属分类ID集合,比如:2,19,77分别代表:一、二、三级类目id,有几条数据就代表有几级类目
  categoryNamesList<String>所属分类名称集合,比如:童鞋,靴子,皮靴,分别代表一、二、三级类目名,与上面的cids匹配
  skuAreaList<Object>商品SKU集合
    outerSkuIdString商品外部编码,直接作为唯一标识,不依赖iid
    priceInteger拿货价
    advicePriceInteger建议零售价,可自主加价
    stockInteger库存
    originPriceInteger原价
    validDateInteger效期。时间戳形式。大于0时可使用
   skuPropertyMap<String,String>sku属性
nonDeliveryAddressList<Object>不发货地区
    provinceString
    cityString
    areaString
shippingFromString发货地
  pidString值相同的常态和专场商品为同款
  nonFreeShippingAreasList<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

请求参数:

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

响应结果:

参数 类型 说明
successBoolean成功失败标志 [true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 itemListList商品库存列表
  outerSkuIdString商品外部编码
  stockInteger库存
hasMoreBoolean是否有下一页,通过eventId获取时需要关注
pageNoInteger当前页

批量查询专场状态

URL:

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

请求方式:

GET

请求参数:

参数 必须 类型 说明
eventIdsString逗号分隔商品eventIds(最多99个)

响应结果:

参数 类型 说明
successBoolean成功失败标志[true:成功 false:失败]
messageString成功失败提示
errorCodeInteger错误码
dataObject
 brandStatusListList专场列表
  eventIdString专场ID
  gmtBeginLong最新的专场开始时间
  gmtEndLong最新的专场结束时间
  isOverBoolean专场是否结束

交易

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

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

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

请求参数:

参数 必须 类型 说明
itemListList<Object>商品列表
  outerSkuIdString商品外部编码
  numInteger购买数量
outerTidString商户的订单ID
provinceString
cityString
areaString
addressDetailString除了省市区外的地址
fullNameString收货人姓名
mobileString收货人手机号
outerGmtPayedLong外部平台支付时间戳(秒)
remarkString备注,200字符以内

响应结果:

参数 类型 说明
successBoolean创建订单是否成功 [true:成功;false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject交易信息
tidString订单ID
 paymentLong支付总金额
 shippingFeeLong物流费用
 orderListList<Object>订单信息
  oidString订单号
  paymentLong订单支付金额
  itemListList<Object>订单内的商品
   outerSkuIdString商品外部编码
   numInteger购买数量
   singleSkuPaymentLong支付商品的单个sku金额
  invalidItemListList<Object>无效的商品,错误码为2010或2040时返回
   outerSkuIdString商品外部编码

创建订单

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
itemListList<Object>商品列表
  outerSkuIdString商品外部编码
  numInteger购买数量
outerTidString商户的订单ID
provinceString
cityString
areaString
addressDetailString除了省市区外的地址
fullNameString收货人姓名
mobileString收货人手机号
remarkString备注,200字符以内

响应结果:

参数 类型 说明
successBoolean创建订单是否成功 [true:成功;false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject交易信息
tidString交易ID
 paymentLong支付总金额
 shippingFeeLong物流费用
 orderListList<Object>订单信息
  oidString订单号
  paymentLong订单支付金额
  itemListList<Object>订单内的商品
   outerSkuIdString商品外部编码
   numInteger购买数量
   singleSkuPaymentLong支付商品的单个sku金额
  invalidItemListList<Object>无效的商品,错误码为2010或2040时返回
   outerSkuIdString商品外部编码

支付订单

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
tidString交易号
outerGmtPayedLong外部平台支付时间戳(秒)

响应结果:

参数 类型 说明
successBoolean操作是否成功
messageString提示信息
errorCodeInteger错误码
dataObject交易信息
 tidString交易tid

取消订单

URL:

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

请求方式:

POST

请求参数:

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

响应结果:

参数 类型 说明
successBoolean操作是否成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject
 cancelStatusInteger取消状态 [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

请求参数:

参数 必须 类型 说明
oidString订单号

响应结果:

参数 类型 说明
successBoolean操作是否成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject数据信息
 cancelStatusInteger取消状态 [1.取消成功 2.等待商家同意 3.卖家拒绝(直接发货)]
 applyReturnLeftTimeInteger等待商家确认超时自动取消订单剩余时间

修改地址

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
oidString订单号
provinceString
cityString
areaString
addressDetailString除了省市区外的地址
fullNameString收货人姓名
mobileString收货人手机号

响应结果:

参数 类型 说明
successBoolean操作是否成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码

确认收货

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
oidString订单号

响应结果:

参数 类型 说明
successBoolean操作是否成功
messageString错误信息
errorCodeInteger错误码
dataObject
 oidString交易oid

查询物流

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
oidString订单号

响应结果:

参数 类型 说明
successBoolean请求是否成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject数据信息
 fullShipmentList所有的物流信息
  companyString物流公司
  outsidString运单号

售后

目前只支持两种售后类型:退款、退货退款;补发错发换货暂不支持,建议一律以退货退款方式处理。
接口对申请售后的时间没有限制,但确认收货超过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

请求参数:

参数 必须 类型 说明
oidString订单号
outerRefundIdString外部售后单号
outerSkuIdString商品外部编码
refundTypeString申请售后的类型<2:仅退款,3:退货退款>
productStatusInteger商品状态: 售后类型=2时,可选:1:未收到货,2:已收到货。售后类型=3时,只能是2:已收到货>
reasonInterger售后原因 当商品状态=1时,售后原因有:60商品漏发,61:未收到货;当商品状态=2时,售后原因:90 商品与描述不符,91:商品漏发,92:商家发错货了,93:拍错/多拍,94:面料/材质/质量问题,95:大小尺寸不符,96:不喜欢/穿着效果不好>
numberInteger售后商品数量,不能超过商品购买数量
refundAmtInteger售后金额,不能超过商品购买金额(单位分)
imgsString售后图片凭证,多张图片以分号分隔,最多5张图
descString售后理由,1~500个字

响应结果:

参数 类型 说明
successBoolean是否创建售后单成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject售后单信息
 refundIdString售后ID
 returnAddressString售后退货地址(聚合地址)
 returnProvinceString
 returnCityString
 returnAreaString
 returnProvinceCodeLong省id
 returnCityCodeLong市id
 returnAreaCodeLong区id
 returnAddressDetailString除了省市区外的地址
 returnContactsString售后退货联系人
 returnTelString售后退货电话号码

查询售后详情

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
refundIdString售后ID

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject售后单信息
 refundIdString售后ID
 oidString订单号
 outerSkuIdString商品外部编码
 refundTypeInteger申请售后的类型:<2:仅退款,3:退货退款>
 refundStatusInteger售后状态码,参见上面的售后状态表
 canSupplementReasonBoolean是否支持补充售后理由
 numInteger售后数量
 refundAmtInteger售后金额(单位分)
 returnAddressString售后退货地址(聚合地址)
 returnProvinceString
 returnCityString
 returnAreaString
 returnProvinceCodeLong省id
 returnCityCodeLong市id
 returnAreaCodeLong区id
 returnAddressDetailString除了省市区外的地址
 returnContactsString售后退货联系人
 returnTelString售后退货电话号码

更新售后物流

URL:

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

请求方式:

POST

请求参数:

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

响应结果:

参数 类型 说明
successBoolean是否更新物流信息成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject售后单信息
 refundIdString售后ID

补充售后理由

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
refundIdString售后ID
imgsString售后图片凭证,多张图片以分号分隔,最多5张图
descString售后理由,1~500个字

响应结果:

参数 类型 说明
successBoolean是否补充信息成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject售后单信息
 refundIdString售后ID

取消售后

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
refundIdString售后ID

响应结果:

参数 类型 说明
successBoolean是否取消售后成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject取消售后信息
 refundIdString售后ID
 refundStatusInteger售后状态
 refundOperateTimeLong售后取消时间

消息推送

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

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

请求参数:

参数 必须 类型 说明
msgTypeString消息类型,参见下文
timestampLong秒级时间戳,5分钟内的请求有效
bsignString签名,用于商户验证消息的正确性
versionString接口版本,默认为1
echostrString商家应该返回的字符串

代码示例:

接口定义

@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

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

参数 类型 说明
eventIdString专场id
gmtBeginLong专场开始时间戳
gmtEndLong专场结束时间戳
eventStatusInteger专场状态 1:正常 -1:下架

商品状态变更消息 item_status_change

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

参数 类型 说明
iidString商品iid
itemStatusInteger1:上架 -1:下架

商品库存变更消息 item_stock

商品库存低于阈值时推送

参数 类型 说明
outerSkuIdString商品外部编码
stockInteger商品库存

常态商品上新消息 normal_item_on_shelf

参数 类型 说明
iidString商品的itemId

常态商品价格变更消息 sku_price_change

参数 类型 说明
outerSkuIdString商品外部编码
priceInteger商品变更后的价格

订单物流消息 order_shipment

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

参数 类型 说明
outerTidString外部交易号
tidString交易号
oidLong订单号
orderStatusInteger订单状态
fullShipmentArrayList全部物流信息
 companyString物流公司
 outSidString物流单号

订单取消结果消息 cancel_status

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

参数 类型 说明
outerTidString外部交易号
tidString交易号
oidLong订单号
cancelStatusInteger订单取消的状态 1:取消成功, 3:卖家拒绝(已发货)

物流修改消息 order_reshipment

商家修改物流信息时推送

参数 类型 说明
outerTidString外部交易号
tidString交易号
oidLong订单号
orderStatusInteger订单状态
fullShipmentArrayList全部物流信息
 companyString物流公司
 outSidString物流单号

售后创建消息 system_create_refunding

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

参数 类型 说明
outerTidString外部交易号
outerRefundIdString外部售后单号
refundIdString售后单号
refundAmtInteger退款金额
refundUpdateTimeLong售后状态更新时间,unix时间戳
refundStatusInteger售后状态 0:创建售后
outerSkuIdString商品外部编码
oidLong订单号
refundTypeInteger申请售后的类型 2:仅退款,3:退货退款
productStatusInteger商品状态:售后类型=2时,可选:1:未收到货,2:已收到货。售后类型=3时,只能是2:已收到货
reasonDescString售后原因描述
numberInteger售后商品数量,不能超过商品购买数量

售后完成消息 refund_agree_return_money

售后完成时推送

参数 类型 说明
outerTidString外部交易号
outerRefundIdString外部售后单号
refundIdString售后单号
refundAmtInteger退款金额
refundUpdateTimeLong售后状态更新时间,unix时间戳
refundStatusInteger售后状态

售后拒绝消息 refund_refuse_return_money

售后被拒绝时推送

参数 类型 说明
outerTidString外部交易号
outerRefundIdString外部售后单号
refundIdString售后单号
reasonString拒绝原因
imgsString图片可能有多张,以分号分隔
refundUpdateTimeLong售后状态更新时间,unix时间戳
refundStatusInteger售后状态

自助联调

自助发货

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
oidLong订单号

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject账户信息
 oidLong订单号

自助发起退款仲裁

相当于商家发起仲裁

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
refundIdString售后单号

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataString售后单号

自助发起同意仲裁

售后拒绝,推送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

请求参数:

参数 必须 类型 说明
refundIdString售后单号

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataString售后单号

其他

查询账户余额

URL:

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

请求方式:

POST

请求参数:

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject账户信息
 telString手机号码
 balanceLong贝仓账户余额

查询账单明细

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
pageInteger当前页
opTypeList<String>操作类型 recharge:充值 pay:支出 income:收入 cancel:取消。
示例:["cancel"](目前只支持一个参数操作)
ascGmtBoolean查询的明细按时间正序,默认是倒序
searchGmtBeginLong大于该流水时间
searchGmtEndLong小于于该流水时间

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataList余额明细
  orderInfoList<Object>订单明细
    payMentLong支付金额
    oidLong订单id
  bizIdString流水业务凭证id
  tidString交易id
  balanceMoneyLong这笔明细之后的剩余金额
  amtLong单笔操作金额
  opTypeString操作类型:recharge
  addAmtBoolean是否是增加金额
  opTypeInfoString操作描述
  gmtCreateLong操作创建时间
 hasMoreBoolean是否有下一页
 pageSizeInteger该页总条数
 pageNoInteger当前页码
 totalSizeInteger总数

查询地址库

URL:

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

请求方式:

POST

请求参数:

参数 必须 类型 说明
levelInteger区域级别:(0~3) 0:获取全部省市区 1:全部省 2:指定parentId的下一级 3:根据传入的id获取省市区信息
parentIdInteger父级id:level大于1的时候必填,父级id,例如(浙江省:330000)
idInteger区域id: 例如浙江省:330000

响应结果:

参数 类型 说明
successBoolean是否操作成功 [true:成功 false:失败]
messageString错误信息
errorCodeInteger错误码
dataObject售后单信息
 regionsList
  idInteger区域id:如120000
  nameString地址名称:天津市
  parentIdInteger父级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

请求参数:

参数 必须 类型 说明
itemListList<Object>商品列表
  outerSkuIdString商品外部编码
  numInteger购买数量
provinceString
cityString
areaString

响应结果:

参数 类型 说明
successBoolean操作是否成功
messageString错误信息
errorCodeInteger错误码
dataObject数据信息
  shippingFeeListList<Object>运费信息
   outerSkuIdString商品外部编码
   shippingFeeInteger运费金额