渠道对接严选OpenAPI接口文档说明-V2.0.5

接入指南

测试环境

http://openapi-test.you.163.com (配置host:223.252.216.178 openapi-test.you.163.com)

线上环境

http://openapi.you.163.com
https://openapi.you.163.com

接口地址

/channel/api.json

请求方式:

POST

输入参数说明

参数默认采用x-www-form-urlencoded的形式编码。如果参数值是一个对象,则默认做json编码转成String。

示例如下:

key=value&key1=value1....

输出参数说明

采用json的编码格式

频率限制

单个接口一分钟的时间段内(开始时间任意)请求不能超过70次

其他说明

  1. 渠道方需提供测试服务器ip,生产上线前提供生产服务器IP
  2. 渠道方从严选获取测试环境appKey和appSecret,生产上线前获取生产环境的appKey和appSecret
  3. 所有api接口均幂等

商品信息查询

1.yanxuan.item.id.batch.get(商品ID查询接口)

功能描述

获取渠道能售卖的所有商品(SPU)ID,相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为 yanxuan.item.id.batch.get
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String
结果 result List<Long> SPU ID

输出示例

{
  "code": 200,
  "msg": "",
  "result": "[0,0]"
}

2.yanxuan.item.batch.get(商品信息查询接口)

功能描述

获取渠道能售卖商品的详细信息,相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为yanxuan.item.batch.get
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
请求商品(SPU)ID列表 itemIds String 用英文逗号分隔,例如:1000884,1000885;一次最多请求30个商品

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String
结果 result List<Item>

输出示例

{
  "code": 200,
  "msg": "",
  "result": [
    {
      "listPicUrl": "",
      "skuList": [
        {
          "yanxuanPrice": 0,
          "picUrl": "",
          "channelPrice": 0,
          "displayString": "",
          "itemSkuSpecValueList": [
            {
              "skuSpec": {
                "name": ""
              },
              "skuSpecValue": {
                "picUrl": "",
                "value": ""
              }
            }
          ],
          "id": 0
        }
      ],
      "categoryPathList": [
        [
          {
            "name": ""
          }
        ]
      ],
      "simpleDesc": "",
      "primaryPicUrl": "",
      "name": "",
      "itemDetail": {
        "detailHtml": "",
        "picUrl3": "",
        "picUrl4": "",
        "picUrl1": "",
        "picUrl2": ""
      },
      "id": 0,
      "attrList": [
        {
          "attrValue": "",
          "attrName": ""
        }
      ],
      "primarySkuId": 0
    }
  ]
}

3.yanxuan.inventory.count.get(商品SKU库存查询接口)

功能描述

获取渠道能售卖的商品SKU的库存信息,相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为yanxuan.inventory.count.get
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
要查询的skuId列表 skuIds String Json序列化的skuId列表。示例:[10019005,123123],一次最多请求100个

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String
结果 result List<ChannelSkuInventoryOut>的json串

输出示例

注意:result的Value为String

{
  "code": 200,
  "msg": "",
  "result": "[
    {
      "inventory": 0,
      "skuId": 0
    }
  ]"
}

商品交易

1.yanxuan.order.paid.create(渠道下单接口)

功能描述

用户付款后,渠道把订单信息推给严选,严选再发货给用户。相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为yanxuan.order.paid.create
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
订单 order Json串

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String
结果 result ChannelOrderOut的json串

输出示例

注意:result的Value为String

{
  "code": 200,
  "msg": "",
  "result": "{
    "expFee": 0,
    "payTime": "",
    "orderId": "",
    "receiverName": "",
    "receiverMobile": "",
    "orderStatus": "",
    "invoiceAmount": 0,
    "orderPackages": [
      {
        "expCreateTime": "",
        "expressNo": "",
        "expressCompany": "",
        "packageId": "",
        "confirmTime": "",
        "orderSkus": [
          {
            "activityTotalAmount": 0,
            "saleCount": 0,
            "originPrice": 0,
            "couponTotalAmount": 0,
            "subtotalAmount": 0,
            "skuId": "",
            "productName": ""
          }
        ],
        "packageStatus": ""
      }
    ],
    "receiverAddressDetail": "",
    "submitTime": "",
    "receiverPhone": "",
    "buyerAccount": "",
    "receiverCityName": "",
    "payMethod": "",
    "receiverDistrictName": "",
    "invoiceTitle": "",
    "receiverProvinceName": "",
    "realPrice": 0
  }"
}

2.yanxuan.order.paid.cancel(渠道取消订单接口)

功能描述

用户(发货前)取消订单后,渠道把取消操作推给严选。相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为yanxuan.order.paid.cancel
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
订单号 orderId String

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String
结果 result OrderCancelResult的json串

输出示例

注意:result的Value为String

{
  "code": 200,
  "msg": "",
  "result": "{
    "rejectReason": "",
    "cancelStatus": 0
  }"
}

3.yanxuan.order.received.confirm(渠道订单确认收货接口)

功能描述

用户确认收货后,渠道把确认收货信息推给严选。相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为 yanxuan.order.received.confirm
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
订单号 orderId String
订单包裹号 packageId String
签收时间 confirmTime String 2016-05-23 16:32:48

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String

输出示例

{
  "code": 200,
  "msg": "",
  "result": null
}

订单信息查询

1.yanxuan.order.paid.get(渠道订单信息查询接口)

功能描述

获取严选系统中订单相关信息,相关接入说明参见here

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为yanxuan.order.paid.get
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
订单号 orderId String

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String
结果 result ChannelOrderOut

输出示例

注意:result的Value为String

{
  "code": 200,
  "msg": "",
  "result": "{
    "expFee": 0,
    "payTime": "",
    "orderId": "",
    "receiverName": "",
    "receiverMobile": "",
    "orderStatus": "",
    "invoiceAmount": 0,
    "orderPackages": [
      {
        "expCreateTime": "",
        "expressNo": "",
        "expressCompany": "",
        "packageId": "",
        "expressDetailInfos": [
          {
            "skus": [
              {
                "activityTotalAmount": 0,
                "saleCount": 0,
                "originPrice": 0,
                "couponTotalAmount": 0,
                "subtotalAmount": 0,
                "skuId": "",
                "productName": ""
              }
            ],
            "expressNo": "",
            "expressCompany": ""
          }
        ],
        "confirmTime": "",
        "orderSkus": [
          {
            "activityTotalAmount": 0,
            "saleCount": 0,
            "originPrice": 0,
            "couponTotalAmount": 0,
            "subtotalAmount": 0,
            "skuId": "",
            "productName": ""
          }
        ],
        "packageStatus": ""
      }
    ],
    "receiverAddressDetail": "",
    "submitTime": "",
    "receiverPhone": "",
    "buyerAccount": "",
    "receiverCityName": "",
    "payMethod": "",
    "receiverDistrictName": "",
    "invoiceTitle": "",
    "receiverProvinceName": "",
    "realPrice": 0
  }"
}

渠道提供回调接口

回调地址

所有回调都用一个统一的回调url

请求方式

POST

输入参数说明

参数默认采用x-www-form-urlencoded的形式编码。如果参数值是一个对象,则默认做json编码转成String。

示例如下:

key=value&key1=value1....

输出参数说明

采用json的编码格式

其他说明

  1. 所有回调会做必要的有限次数的重试,然并不保证回调100%成功
  2. 回调接口都要保证幂等
  3. 请求和返回内容都为json

1.订单取消回调

业务说明

渠道方通过调用严选API(订单取消申请),将订单的取消申请告知严选。严选接收到取消请求后,会根据订单中的商品进行取消判断,有的商品可以直接返回取消结果,有的商品需要等待人工审核。对于人工审核的订单取消申请,严选工作人员审核完成后,通过调用渠道方提供的回调接口告知取消结果。

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为 yanxuan.callback.order.cancel
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
取消结果 orderCancelResult Json串

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String

输出示例

{
  "code": 200,
  "msg": ""
}

2.订单包裹物流绑单回调

业务说明

订单包裹出库成功,严选通过调用渠道方提供的回调接口告知订单包裹的物流绑单信息(如物流公司、物流单号等),一次回调为可能为部分物流绑单信息。

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为 yanxuan.notification.order.delivered
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
订单包裹信息 orderPackage Json串

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String

输出示例

{
  "code": 200,
  "msg": ""
}

3.订单异常回调

业务说明

因为sku的库存信息或其他因素,导致订单会被严选主动取消。严选会把这个主动取消操作推送给渠道。

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为 yanxuan.notification.order.exceptional
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
异常信息描述 exceptionInfo Json串

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String

输出示例

{
  "code": 200,
  "msg": ""
}

4.渠道SKU库存划拨回调

业务说明

渠道方需要关心网仓划拨、回拨的通知。

输入

参数说明 参数名 类型 是否必须 描述
方法名 method String 值为yanxuan.notification.inventory.count.changed
渠道的AppKey appKey String
签名 sign String
请求时间戳 timestamp String
划拨记录 skuTransfer Json串

输出

参数说明 参数名 类型 描述
状态码 code int
失败原因 msg String

输出示例

{
  "code": 200,
  "msg": ""
}

数据说明

输入

appKey

严选提供的渠道方标识

appSecret

严选提供的渠道方标识

timestamp

时间戳,采用yyyy-MM-dd HH:mm:ss的形式

sign

签名,签名的生成规则如下:

  1. 输入参数值(除sign外)参照字母排序拼接,拼接成key=value的字符串形式
  2. 首尾加上appSecret值
  3. 最后对上述值取32位大写MD5值

OrderSku

订单中SKU数据

参数说明 参数名 类型 是否必须 描述 长度
SKU ID skuId String 1020003 32
商品名称 productName String 网易严选 轻透隐形包芯丝连裤袜 512
商品数量 saleCount int 1 10
商品单价 originPrice BigDecimal 9.90 整数8小数2
金额小计 subtotalAmount BigDecimal 1.90, 单价*数量-两个优惠等于小计 整数8小数2
优惠卷金额 couponTotalAmount BigDecimal 0.00 整数8小数2
活动优惠金额 activityTotalAmount BigDecimal 8.00 整数8小数2

Order

订单

参数说明 参数名 类型 是否必须 描述 长度
订单号 orderId String 最长128位
下单时间 submitTime String 2016-05-23 09:00:00
支付时间 payTime String 2016-05-23 13:59:59
买家用户名 buyerAccount String XXX@126.com 最长255位
收件人姓名 receiverName String XXX 最大255位
收件人手机 receiverMobile String 13612345678 最大32位
收件人电话 receiverPhone String 13612345678 最大32位
收件人省名称 receiverProvinceName String 浙江省 最大32位
收件人市名称 receiverCityName String 杭州市 最大32位
收件人区名称 receiverDistrictName String 滨江区 最大32位
收件人详细地址 receiverAddressDetail String 网商路599号,网易大厦 最大512位
订单实付金额 realPrice BigDecimal 90.87 ,包含邮费,减去邮费需要大于0 最长十位 整数8位小数2位
邮费 expFee BigDecimal 10.00 最长十位 整数8位小数2位
支付方式 payMethod String 支付宝SDK 最大32位
发票抬头 invoiceTitle String XXX 最大128位
发票金额 invoiceAmount BigDecimal 90.87 最长十位 整数8位小数2位
备注 remark String XXX
订单SKU orderSkus List<OrderSku>

OrderCancelCallbackResult

取消订单结果

参数说明 参数名 类型 是否必须 描述
订单ID orderId String
取消状态 cancelStatus int 0:不允许取消,1:允许取消,2:待审核
拒绝取消原因 rejectReason String XXX

OrderPackage

订单包裹信息

参数说明 参数名 类型 是否必须 描述
订单号 orderId String 最大128位
包裹号 packageId String 20160620123
物流信息 expressInfos List<OrderPackageExpressInfo>
物流详细信息(带上sku) expressDetailInfos List<ChannelOrderExpressDetailInfo>
发货时间 expCreateTime Long unix时间戳,单位毫秒

ChannelOrderExpressDetailInfo

渠道订单回调的包裹详情信息

参数说明 参数名 类型 是否必须 描述
物流公司名称 expressCompany String 查看目前支持的物流:物流公司列表
物流单号 expressNo String
子物流单列表 subExpressNos List<String>
物流包裹包含SKU信息 skus List<OrderSku>

OrderPackageExpressInfo

订单包裹物流信息

参数说明 参数名 类型 是否必须 描述
物流公司名称 expressCompany String 查看目前支持的物流:物流公司列表
运单号 expressNos List<String>

OrderExceptionInfo

订单异常信息

参数说明 参数名 类型 是否必须 描述
订单ID orderId String
异常说明 reason String 描述订单异常原因, 见异常说明

额外补充数据 | extData | String | 否 | json串

OrderExceptionReason

订单异常reason说明

reason 说明 额外补充数据说明
CANCEL 订单被主动取消 没有extData字段

订单异常信息

参数说明 参数名 类型 是否必须 描述
订单ID orderId String
异常说明 reason String 描述订单异常原因, 见异常说明
额外补充数据 extData String json串

ChannelInventoryTransfer

SKU在对应渠道中的库存划拨记录

参数说明 参数名 类型 是否必须 描述
划拨记录唯一标识符 id String
sku划拨记录 skuTransfers List<ChannelSkuInventoryTransfer>
划拨时间 operateTime long

输出

code

状态码。200为成功,其余为失败

msg

失败原因,当code!=200时返回

ChannelOrderPackage

订单包裹

参数说明 参数名 类型 是否必须 描述
包裹号 packageId String 20160620123
物流公司名称 expressCompany String 绑单之后才有,多物流公司之间使用英文竖线|隔开,如顺丰|圆通,查看目前支持的物流:物流公司列表
运单号 expressNo String 绑单之后才有, 不同物流公司的运单号使用英文竖线|隔开,相同物流公司的运单号使用,隔开如 sf123,sf456|yt123,yt456
发货时间 expCreateTime Long 绑单之后才有,2016-05-23 13:59:59
签收时间 confirmTime String 绑单之后才有,2016-05-24 13:59:59
包裹状态 packageStatus String 绑单之后才有
订单SKU orderSkus List<OrderSku>
物流详细信息 expressDetailInfos List<ChannelOrderExpressDetailInfo> 绑单之后才有

packageStatus

包裹状态

包裹状态 描述
WAITING_DELIVERY 等待发货
START_DELIVERY 已发货(等待收货)
WAITING_COMMENT 已收货(等待评论)
COMMENTED 已评价
SYS_CANCEL 系统取消
USER_CANCEL 用户取消
KF_CANCEL 客服取消
USER_PAYED_CANCEL 用户付款后取消

ChannelOrderOut

严选系统中订单信息

参数说明 参数名 类型 是否必须 描述
订单号 orderId String 最大128位
下单时间 submitTime String 2016-05-23 09:00:00
支付时间 payTime String 2016-05-23 13:59:59
买家用户名 buyerAccount String
收件人姓名 receiverName String XXX
收件人手机 receiverMobile String 13612345678
收件人电话 receiverPhone String 13612345678
收件人省名称 receiverProvinceName String 浙江省
收件人市名称 receiverCityName String 杭州市
收件人区名称 receiverDistrictName String 滨江区
收件人详细地址 receiverAddressDetail String 网商路599号,网易大厦
订单实付金额 realPrice BigDecimal 90.87
邮费 expFee BigDecimal 10.00
支付方式 payMethod String 支付宝SDK
发票抬头 invoiceTitle String XXX
发票金额 invoiceAmount BigDecimal 90.87
订单状态 orderStatus String PAYED
订单包裹 orderPackages List<ChannelOrderPackage>

orderStatus

订单状态

订单状态 描述
WAITING_PAY 未付款
PAYED 已付款
SYS_CANCEL 系统取消
USER_CANCEL 用户取消
KF_CANCEL 客服取消
CANCELLING 取消待审核
USER_PAYED_CANCEL 用户付款后取消

OrderCancelResult

取消订单结果

参数说明 参数名 类型 是否必须 描述
取消状态 cancelStatus int 0:不允许取消,1:允许取消,2:待审核
拒绝取消原因 rejectReason String XXX

ChannelSkuInventoryOut

严选系统中SKU库存信息

参数说明 参数名 类型 是否必须 描述
SKU ID skuId String 1020003
库存数量 inventory long 实时的库存数量

ChannelSkuInventoryTransfer

具体sku的划拨数据

参数说明 参数名 类型 是否必须 描述
SKU ID skuId long
划拨数量 transferCount int 小于0表示回拨

物流公司列表

参数说明
EMS
顺丰
韵达
中通
百世汇通
圆通
申通
天天
全峰
宅急送
国通
德邦
速尔
能达
优速
快捷
新邦物流
晟邦物流

Item

商品信息

参数说明 参数名 类型 描述
商品(SPU)的标识 id Long 10018002
商品名称 name String 草莓
主skuId primarySkuId Long 10019005,默认展示的SKU
商品主图的URL primaryPicUrl String
列表页图片的URL listPicUrl String
商品描述 simpleDesc String 好吃不能听,买买买!
商品下的sku列表 skuList List<Sku>
商品详情 itemDetail ItemDetail
商品属性列表 attrList List<ItemAttr>
商品类目路径列表 categoryPathList List< List<Category> > 类目路径指包含商品所在目录及其父目录的完整类目路径,第2层List拼接就是一个完整的分类

Item_Sku

商品中Sku信息

参数说明 参数名 类型 描述
Sku的标识 id Long 10019005
严选基准售价 yanxuanPrice BigDecimal 50.00
渠道售价 channelPrice BigDecimal 50.00
sku规格图片的URL picUrl String
sku规格文字信息 displayString String 大箱草莓
sku规格信息 itemSkuSpecValueList List<SkuSpecInfo>

ItemDetail

ItemDetail信息

参数说明 参数名 类型 描述
详情页html detailHtml String
商品大图1的URL picUrl1 String
商品大图2的URL picUrl2 String
商品大图3的URL picUrl3 String
商品大图4的URL picUrl4 String

ItemAttr

商品属性信息

参数说明 参数名 类型 描述
属性名 attrName String
属性值 attrValue String

Category

Categroy信息

参数说明 参数名 类型 描述
类目名称 name String

SkuSpecInfo

Sku规格信息

参数说明 参数名 类型 描述
规格名 skuSpec SkuSpec
规格值 skuSpecValue SkuSpecValue

SkuSpec

Sku规格名

参数说明 参数名 类型 描述
规格名 name String 规格名字

SkuSpecValue

Sku规格值

参数说明 参数名 类型 描述
规格值 value String 规格值描述
规格图片 picUrl String 规格图片URL