文档

API参考

更新时间:

当前版本: v1.6.15

版本号

变更内容

变更背景

重要公告

是否兼容存量接口

SDK是否更新

发布日期

v1.6.15

2.7查询商品列表(无本地缓存)

  • CanNotBeSoldCode更新为isCanNotBeSoldCode

  • CanNotBeSoldMessage更新为isCanNotBeSoldMessage

2023-10-23

v1.6.14

3.16分销采购订单物流查询

返回包裹对应的商品skuId

2023-10-23

v1.6.13

接口内容优化:

3.4分销采购订单创建结果通知 优化“通知中的交易失败原因 和 分销订单extInfo中的关单原因”描述 优化前结果通知:“采购失败、采购关单” 优化后结果通知:“商品异常,下单失败、大促活动商品,下单失败、区域库存不足,下单失败、账户状态异常,下单失败、账户短时间内下单过多,下单失败、订单超时关闭,商户余额可能不足”

“通知中的交易失败原因 和 分销订单extInfo中的关单原因”优化错误码返回,方便客户理解接口返回的错误码。

2023-08-01

v1.6.12

3.6分销采购订单退款申请初始化

为了减少接入方匹配售后原因的麻烦,我们过滤了大部分售后原因,只返回优先级最高的一条

2023-08-01

v1.6.11

3.2分销创单接口,商品信息参数新增商品价格字段

采购库商品价格变更,分销商仍使用变更前的价格下单,引起分销商资损

您采购时,为了防止价格信息的突发性变动,造成您的资损。itemInfo中的price字段,表示分销商向渠道商天猫企业购下单时刻的价格,后台在创建分销订单时会校验该下单商品价格和分销库中商品实时供货价格是否一致,如果不一致则判定商品不可售。

为避免您的资损,强烈建议传入该字段

2023-06-21

v1.6.10

分销逆向申请退款接口错误码优化

优化错误码返回,方便客户理解接口返回的错误码

2023-04-26

v1.6.9

分销交易、订单接口返回值code更正

更正交易、订单主动调用接口成功时的code描述

2023-04-26

v1.6.8

所有价格相关字段描述更新

降低客户对于各类价格的理解门槛,方便客户理解价格体系

2023-02-27

v1.6.7

  • 3.1增加分销渲染接口中关于分销商真实买家ID的参数备注

  • 3.2增加分销创单接口中关于分销商真实买家ID的参数备注

确定buyerId的规则,避免客户使用固定统一的buyerId而引发一系列并发问题

buyerId(分销真实买家ID)字段请务必传入分销商城侧的每个C端用户对应的唯一身份ID。

风险:若不填写与真实用户相对应的身份ID,将有可能触发主站下单风控和下单接口并发度降低等业务和技术风险。请您务必检查一下3.1和3.2接口处buyerId传入信息是否符合该规范。

2023-02-10

v1.6.6

2.7新增B端管控查询商品列表(无本地缓存)

商品渠道价格或图文信息变更后,客户可以及时查询到变更后的信息并自动更新商品详情

是。若不使用2.7接口,则不需要更新。

2023-01-13

v1.6.5

  • 2.1商品列表接口,新增平台商品属性商品维度lmItemAttributeMap字段,SKU维度lmSkuAttributeMap字段

  • 2.2商品详情接口,修改平台商品属性商品维度lmItemAttributeMap描述,SKU维度lmSkuAttributeMap描述

  • 2.4商品详情接口(支持区域库存),修改平台商品属性商品维度lmItemAttributeMap描述,SKU维度lmSkuAttributeMap描述

支持商家设置税率税码

2023-01-03

v1.6.4

3.12查询分销采购订单退款申请接口,废弃returnGoodCount字段。

客户实际业务中并不使用该字段,故在文档中相应废除。

2022-12-16

v1.6.3

  • 2.2商品详情接口,废弃invoiceType字段。

  • 2.4商品详情接口(支持区域库存),废弃invoiceType字段。

  • 2.6商品建议零售价格接口,增加最低建议零售价格字段。

...

2022-12-09

v1.6.2

  • 3.2接口中,增加外部交易单传入distributionOutTradeId

  • 3.4通知接口,返回外部交易单ID

...

distributionOutTradeId(分销外部交易号)字段请留意,分销外部交易号为您商城C端用户下单的订单号。为避免您的资损,强烈建议传入该字段

2022-12-06

v1.6.1

  • 调整3.7和3.9注意事项表述

  • 优化格式,校对业务流程等

...

2022-12-02

v1.6.0

2.3信息变更通知中增加两种通知类型

...

2022-11-24

...

...

...

...

v1.0.0

全量内容发布,业务流程描述

...

2022-07-22

0 公共参数

入参公共参数

属性名

变量名

是否必须

数据类型

备注

分销商城租户ID

tenantId

Y

String(128)

和分销商ID一致

1. 分销商管理

1.1 分销商城查询

1. 接口说明

分销商查询自己拥有的商城信息

2. 接口约定

  • 接口名称:queryDistributionMall

  • 使用场景:B端管控

  • URL:SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:10

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String(128)

分销商城ID

租户ID

tenantId

Y

String(128)

租户ID

4. 返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

分销商城信息

data

Y

DistributionMall

分销商城信息

DistributionMall

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商城ID

distributionMallId

Y

String(64)

分销商城ID

分销商城名称

distributionMallName

Y

String(128)

商城名称

渠道供应商ID

channelSupplierId

N

String(64)

渠道供应商ID

商城模式

distributionMallType

N

String(64)

商城模式

开始时间

startDate

N

String(32)

开始时间

yyyy-MM-dd HH:mm:ss

结束时间

endDate

N

String(32)

结束时间

yyyy-MM-dd HH:mm:ss

分销商城状态

status

Y

String(32)

分销商城状态

  • INIT:初始创建

  • TO_BE_APPROVED: 待审核

  • APPROVED:审核通过

  • CONFIG_INIT:初始化中

  • WORKING:生效

  • INVALID:失效

1.2 分销商城列表查询

1. 接口说明

查询自己已经开通的商城列表

2. 接口约定

  • 接口名称:listDistributionMall

  • 使用场景:B端管控

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:10

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

租户ID

tenantId

Y

String(64)

租户ID

分销商ID

distributorId

Y

String(64)

分销商ID

商城名称

distributionMallName

N

String(128)

商城名称

渠道供应商ID

channelSupplierId

N

String(64)

渠道供应商ID

开始时间

startDate

N

String(32)

开始时间

yyyy-MM-dd HH:mm:ss

结束时间

endDate

N

String(32)

结束时间

yyyy-MM-dd HH:mm:ss

页码

pageNumber

Y

Integer

请求页码,默认为1

每页数量

pageSize

Y

Integer

每页数量范围(1-20)默认20

4. 返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

当前页码

pageNumber

Y

Integer

当前页码

每页数量

pageSize

Y

Integer

每页数量

数量

totalCount

Y

Integer

总数

分销商城信息

distributionMallList

Y

List<DistributionMall>

分销商城信息

DistributionMall

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String(64)

分销商城ID

分销商城名称

distributionMallName

Y

String(128)

商城名称

渠道供应商ID

channelSupplierId

Y

String(64)

渠道供应商ID

商城模式

distributionMallType

N

String(64)

商城模式

开始时间

startDate

N

String(32)

开始时间

yyyy-MM-dd HH:mm:ss

结束时间

endDate

N

String(32)

结束时间

yyyy-MM-dd HH:mm:ss

分销商城状态

status

Y

String(32)

分销商城状态

1.3 分销商城回调通知

1. 接口说明

分销商城入驻完成后,有状态变更时向客户系统发起通知

2. 接口约定

  • 接口名称:distributorChangeNotify

  • 使用场景:B端管控

  • URL:客户提供HTTPS地址

  • 发起方:LinkedMall

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

请求标识

requestId

Y

String(64)

请求标识

分销商

distributorId

Y

String(64)

客户业务 ID

分销商城ID

distributorMallId

Y

String

分销商城ID

通知类型

noticeType

Y

String

  • DISTRIBUTOR_APPROVED:分销商审核通过通知

  • DISTRIBUTION_MALL_APPROVED:分销商城审核通过通知

通知时间

noticeTime

Y

String

扩展信息

extInfo

N

String

json格式

签名

signature

Y

String(128)

集团内部metaQ可不签名

签名方法

signatureMethod

Y

String(128)

默认: SHA256WithRSA

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String

SUCCESS 表示成功

错误信息

message

N

String

失败时,返回具体原因

请求ID

requestId

Y

String

1.4 账单明细查询

1. 接口说明

账单明细查询,返回明细数据下载链接。

2. 接口约定

  • 接口名称:queryDistributionBillDetail

  • 使用场景:B端管控

  • URL:SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:10

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商城ID

distributionMallId

N

String(128)

分销商城ID

账单ID

billId

N

String(64)

账单ID

账单期数

billPeriod

N

String(32)

示例1:2022

示例2:2022-08(年月期次需用这种格式的入参)

分销商城名称

distributionMallName

N

String(128)

分销商城名称

账单状态

billStatus

N

String(32)

  • billGenerated : 账单生成

  • billGenerating : 正在生成

页码

pageNumber

Y

Integer

请求页码,默认为1

每页数量

pageSize

Y

Integer

每页数量范围(1-20)默认20

4. 返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求ID

requestId

Y

String

请求ID

账单明细

model

Y

BillDetail

账单明细

BillDetail

属性名

变量名

是否必须

数据类型

备注

当前页码

pageNumber

Y

Integer

当前页码

每页数量

pageSize

Y

Integer

每页数量

数量

total

Y

Integer

总数

分销账单明细下载链接

data

Y

List<String>

分销账单明细下载链接

2. 分销商品管理

2.1 查询商品列表

1. 接口说明

查询分销商商品库内的商品列表,分销商品信息排序规则为商品的添加时间。

建议使用2.7.查询商品列表(无本地缓存)

2. 接口约定

  • 接口名称:listDistributionItem

  • 使用场景:B端管控

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:10

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商商城ID

distributionMallId

Y

String(64)

分销商商城ID

LM商品ID

lmItemId

N

String

LM商品ID

商品状态

itemStatus

N

Integer

商品状态

1:可售

2:不可售

不传:则查所有状态

页码

pageNumber

Y

Integer

请求页码,默认为1

每页数量

pageSize

Y

Integer

每页数量范围(1-20)默认20

4. 返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

操作日志号

logsId

N

String

每次请求操作对应的操作日志号,由系统自动生成,可用于排查问题,双方日志中统一透出此标识

错误子代码

subCode

N

String

用于显示业务类的错误代码,一般建议关注此类错误

错误子代码信息

subMessage

N

String

业务处理相关的错误信息,一般建议关注此类错误

当前页码

pageNumber

Y

Integer

当前页码

每页数量

pageSize

Y

Integer

每页数量

数量

totalCount

Y

Integer

总数

商品

model

Y

List<DistributionItemModel>

分销商品信息

DistributionItemModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

LM商品ID

lmItemId

Y

String

LM商品ID

淘宝商品ID

itemId

Y

Long

Long类型淘宝商品ID

淘宝商品ID

itemIdStr

Y

String

String类型淘宝商品ID

叶子类目ID

categoryId

Y

Long

叶子类目ID(叶子类目,即最末类目。由于主站不同商品的类目长度不同,不确定该叶子类目处于正向第几级类目)

类目链

categoryChain

Y

List<CategoryModel>

类目链,父类目在前,子类目在后,叶子类目最后。(该字段直接返回主站的类目信息,不同商品的类目长度不同。分销客户通常存储到三/四级类目,该类目信息可以不与分销商城前台类目一一绑定)

例如:

[{

"categoryId": 50008907,

"name": "手机号码/套餐/增值业务",

"parentId": 0,

"level": 0,

"leaf": false

}]

平台商品分类

category

Y

String

商品在LinkedMall平台上的分类:实物商品(entity),猫超卡券(aliComBenifit),电影票(movieTicket)

商品状态

status

Y

Integer

商品状态

1:商品可售卖2:商品不可售卖3:商品价格异常4:商品被删除

商品剩余库存

quantity

N

Integer

商品剩余库存:MIN{采买数量-已售卖数量,IC库存}

模糊化库存值

simpleQuantity

Y

String

模糊化库存值

例如:

有货、无货、库存紧张

是否有库存

hasQuantity

Y

Boolean

是否有库存

总售卖数量

totalSoldQuantity

N

Integer

商品总售卖数量

模糊化商品累计售卖数量

simpleTotalSoldQuantity

Y

String

模糊化商品累计售卖数量

例如:100+、200+、1000+、2000+、1万+、10万+

创建时间

gmtCreate

Y

String

创建时间

最后修改/生效时间

gmtModified

Y

String

最后修改/生效时间

图片地址

picUrl

Y

String

图片URL

商品描述信息

itemDesc

N

String

商品描述信息

注:列表接口不透传该字段,如需图文信息请使用详情接口获取

SKU

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

SKU划线价范围

reservedPriceScope

Y

String

一个商品下,所有SKU的划线价范围。(分)

供货价范围

priceCentScope

Y

String

一个商品下,所有SKU供货价(渠道给分销供货价,即分销商进价)的范围。(分)

是否可售

isCanSell

Y

boolean

是否可销售,目前主要判断了商品的状态是否正常,同时库存要求大于0

不可售的原因

tips

N

String

对商品不可售的原因描述

商品名称

itemTitle

Y

String

商品名称

商品主图

mainPicUrl

Y

String

商品主图

图片详情

descOption

N

String

商品详情介绍-图片介绍信息

注:列表接口不透传该字段,如需图文信息请使用详情接口获取

配置信息

propertiesJson

N

String

配置信息

例如:

{&quot;品牌&quot;:[&quot;中国移动&quot;],&quot;套餐&quot;:[&quot;开普通移动本地套餐&quot;,&quot;测试套餐0408&quot;],&quot;套餐特征&quot;:[&quot;本地基础套餐&quot;]}

轮播图片列表

itemImages

N

List<String>

商品图片URL列表,最多10张,一般是Detail上轮播

商品规格列表

skuList

Y

List<DistributionItemSkuModel>

商品规格列表

LM客户侧扩展属性

lmAttributeModels

N

List<LmAttributeModel>

商品维度扩展属性列表(客户业务商品库扩展属性)

详见6.商品扩展属性

平台商品属性

lmItemAttributeMap

N

Map<String, String>

商品维度扩展属性PV(商家扩展属性或系统扩展属性)

详见6.商品扩展属性

DistributionItemSkuModel说明

属性名

变量名

是否必须

数据类型

备注

LM商品ID

lmItemId

Y

String

LM商品ID

淘宝商品ID

itemId

Y

Long

淘宝商品ID

商品规格ID

skuId

Y

Long

商品规格ID

商品剩余库存

quantity

N

Long

商品剩余库存:MIN{采买数量-已售卖数量,IC库存}

精简化库存

simpleQuantity

Y

String

精简化库存值

例如:有货、无货、库存紧张

是否有库存

hasQuantity

Y

Boolean

是否有库存

商品状态

status

Y

Integer

商品状态

1:商品可售卖2:商品不可售卖3:商品价格异常4:商品被删除

SKU供货价

priceCent

Y

Long

分销渠道商给分销商的供货价格。 每次交易单个商品会从分销商支付宝账户扣的金额。(分)

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

规格描述

skuDesc

N

String

规格描述

规格展示图片

skuPicUrl

N

String

规格展示图片

规格标题

skuTitle

N

String

规格标题

最后修改/生效时间

gmtModified

Y

String

最后修改/生效时间

LM客户侧扩展属性

lmAttributeModels

N

List<LmAttributeModel>

规格维度扩展属性列表(客户业务商品库扩展属性)

详见:6.商品扩展属性

客户自定义属性

customizedAttributeMap

N

Map<String, String>

规格维度扩展属性PV(客户业务商品库扩展属性)

详见:6.商品扩展属性

平台SKU属性

lmSkuAttributeMap

N

Map<String, String>

规格维度扩展属性PV(商家扩展属性或系统扩展属性)

详见:6.商品扩展属性

是否可售

canSell

Y

Boolean

是否可售

不可售原因

tips

N

String

不可售原因

SKU配置

skuPropertiesJson

N

String

SKU配置

注:列表接口不透传该字段,如需图文信息请使用详情接口获取

基础库/系统扩展属性

skuProperties

N

Map<String, String>

设置基础库/系统扩展属性

注:列表接口不透传该字段,如需图文信息请使用详情接口获取

其它信息

extInfo

N

String

其它信息

LmAttributeModel说明

属性名

变量名

是否必须

数据类型

备注

LM属性ID

attrId

Y

Long

LM属性ID

属性值

value

Y

String

属性值

属性名

name

Y

String

属性名

描述

description

N

String

描述

数据类型

dataType

N

String

数据类型,默认String

2.2 查询商品详情接口

1.接口说明

查询单个商品的详细信息。

建议使用2.4. 查询商品详情接口(支持区域库存)

2.接口约定

  • 接口名称:queryItemDetail

  • 使用场景:C端查询商品详情

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3.入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商商城ID

distributionMallId

Y

String(64)

分销商商城ID

LM商品ID

lmItemId

Y

String

LM商品ID

购买商品数量

itemBuyAmount

N

Integer

购买商品数量。

  • 不传或者小于等于0的情况将不会计算商品库存是否充足。

  • 传值并且大于0的情况下将会计算商品库存是否充足。

4.返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

操作日志号

logsId

N

String

每次请求操作对应的操作日志号,由系统自动生成,可用于排查问题,双方日志中统一透出此标识

错误子代码

subCode

N

String

用于显示业务类的错误代码,一般建议关注此类错误

错误子代码信息

subMessage

N

String

业务处理相关的错误信息,一般建议关注此类错误

商品信息

model

Y

DistributionItemDetailModel

分销商品信息

DistributionItemDetailModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

商品规格列表

skuModels

Y

List<DistributionItemSkuDetailModel>

商品规格列表

商品规格PV属性列表

skuPropertys

N

List<SkuPropertyModel>

商品规格属性PV对列表,用于渲染页面下单时,选择下单参数(当商品是无规格产品的时候,对应的PV属性列表为空)

LM商品ID

lmItemId

Y

String

LM商品ID

商品ID

itemId

Y

Long

商品ID

商品名称

itemTitle

Y

String

商品名称

主图地址

mainPicUrl

Y

String

主图

首图地址

firstPicUrl

Y

String

轮播图第一张图

轮播图

itemImages

Y

List<String>

商品图片URL,最多10张,一般是Detail上轮播

商品详情介绍地址

descPath

N

String

商品详情介绍-图片介绍,URL

商品图文详情

descOption

N

String

商品详情介绍-图片介绍信息

商品最低SKU价格

minPrice

Y

Long

商品所有SKU中,最低的SKU的价格。如果商品下只有一个SKU,则直接为该SKU的供货价;如果商品下有多个SKU,则显示的是所有SKU里的最低价。(分)

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

商品库存

quantity

N

Integer

商品库存,如果只有一个SKU,则直接是SKU上的库存。如果商品有配送区域库存,且查询接口里指定了配送区域,则返回的是对应区域库存

模糊化库存

simpleQuantity

Y

String

模糊化库存

例如:有货、无货、库存紧张(库存数量<=10)

是否有库存

hasQuantity

Y

Boolean

是否有库存,返回的是库存状态,有或者没有

叶子类目ID

categoryId

Y

Long

叶子类目ID(叶子类目,即最末类目。由于主站不同商品的类目长度不同,不确定该叶子类目处于正向第几级类目)

类目链ID

categoryIds

N

List<Long>

类目链ID,父类目在前,子类目在后,叶子类目最后

商品所在省份

prov

N

String

商品所在省份:如浙江

商品所在城市

city

N

String

商品所在城市:如杭州

产品参数

properties

N

Map<String, Set<String>>

产品属性或产品参数,供Detail页面显示使用

例如:

{颜色分类: ["桔色", "军绿色"]}

产品特征

features

N

Map<String, String>

商家配置产品特征

tax_invoice:税率

tax_rate_code:税码,全国统一

extraPeriod:保质期,用于食品

food_pro_date:生产日期

关键属性

iforestProps

N

List<Map<String, String>>

关键属性,供Detail页面显示使用

例如:

[{value: "军绿色", key: "颜色分类"}, {value: "桔色", key: "颜色分类"}]

是否包邮

SellerPayPostfee

N

boolean

是否包邮

是否可售

isCanSell

Y

boolean

是否可销售,目前主要判断了商品的状态是否正常,同时库存要求大于0;

平台商品的类型

lmItemCategory

Y

String

商品在LinkedMall平台的类型

entity:实物商品

aliComBenifit:虚拟商品

客户自定义属性

customizedAttributeMap

N

Map<String, String>

商品维度的扩展属性PV

(客户自定义属性)

详见6.商品扩展属性

平台商品属性

lmItemAttributeMap

N

Map<String, String>

商品维度的扩展属性PV

(商家扩展属性或系统扩展属性)

详见6.商品扩展属性

当前时间

current

Y

Date

当前时间

虚拟商品类型

virtualItemType

N

String

虚拟商品类型,该字段为枚举类型,值为cardRoll(卡券)、rechageableCard(充值卡)、fuelCard(油卡)

外部商品ID

thirdPartyItemId

N

String

外部商品ID (来自第三方的商品)

商品来源

thirdPartyName

N

String

商品来源 (标记第三方商品的来源)

视频地址

vIDeoUrl

N

String

视频地址

视频封面地址

vIDeoPicUrl

N

String

视频封面地址

不可售编码

canNotBeSoldCode

N

String

不可售编码,可售时为空

不可售消息

canNotBeSoldMessage

N

String

不可售消息,可售时为空

总量库存值

itemTotalValue

N

Integer

总量库存值

总量库存模糊值

itemTotalSimpleValue

Y

String

总量库存模糊值

例如:

有货、无货、库存紧张

DistributionItemSkuDetailModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

预留扩展字段

extJson

N

String

预留扩展字段,JSON-Map结构

LM商品ID

lmItemId

Y

String

LM商品ID

IC商品ID

itemId

Y

Long

IC商品ID

规格ID

skuId

Y

Long

规格ID

属性PV值组合

skuPvs

N

String

SKU对应的属性PV值组合(当商品是无规格产品的时候,对应的PV属性为空)

规格图片地址

skuPicUrl

N

String

SKU图片

规格标题

skuTitle

N

String

SKU对应的属性显示Title。多个属性组合值之间用斜线分隔。

SKU库存

quantity

N

Integer

SKU库存。如果商品有配送区域库存,且查询接口里指定了配送区域,则返回的是对应区域库存

SKU模糊化库存

simpleQuantity

Y

String

SKU模糊化库存

例如:有货、无货、库存紧张

是否有库存

hasQuantity

Y

Boolean

是否有库存,返回的是库存状态,有或者没有

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。 商品SKU在主站侧的划线价。(分)

SKU供货价

priceCent

Y

Long

分销渠道商给分销商的SKU供货价格。 每次交易单个商品SKU会从分销商支付宝账户扣的金额。(分)

规格状态

status

Y

Integer

商品规格售卖状态

1:商品可售卖2:商品不可售卖3:商品价格异常4:商品被删除

客户自定义属性

customizedAttributeMap

N

Map<String, String>

规格维度的扩展属性PV

(客户自定义属性)

详见6.商品扩展属性

平台SKU属性

lmSkuAttributeMap

N

Map<String, String>

规格维度的扩展属性PV

(商家扩展属性或系统扩展属性)

详见6.商品扩展属性

不可售编码

canNotBeSoldCode

N

String

不可售编码,可售时为空

不可售原因

canNotBeSoldMessage

N

String

不可售消息,可售时为空

SkuPropertyModel说明

属性名

变量名

是否必须

数据类型

备注

规格属性ID

ID

Y

Long

规格属性ID

属性键P

text

Y

String

属性键P

属性值列表

values

Y

List<SkuPropertyValueModel>

属性值列表

SkuPropertyValueModel说明

属性名

变量名

是否必须

数据类型

备注

属性值ID

ID

Y

Long

属性值ID

属性值V

text

Y

String

属性值V

5.错误码

canNotBeSoldCode(不可售错误编码)

canNotBeSoldMessage(不可售错误原因)

CAN_NOT_BE_SOLD

商品不可售,原因可能为以下:

超过限购数量,暂时无法购买

兑换次数达到上限

IC_PRICE_EXCEPTION

主站商品价格异常

IC_AUCTION_STATUS_CAN_NOT_BE_SOLD

主站商品状态不可售

IC_NO_QUANTITY

主站没有库存

IC_SKU_NO_QUANTITY

主站该SKU没有库存

IC_SKU_LIST_NOT_EXIST

主站不存在任何SKU

IC_SKU_NOT_EXIST

主站不存在该SKU

IC_SKU_STATUS_EXCEPTION

主站该SKU状态异常

BASIC_PRICE_EXCEPTION

基础商品库侧商品价格异常

BASIC_SKU_NOT_EXIST

基础商品库侧SKU不存在

BASIC_STATUS_CAN_NOT_BE_SOLD

基础商品库侧SKU状态为不可售

BIZ_PRICE_EXCEPTION

业务商品库侧商品价格异常

BIZ_SKU_NOT_EXIST

业务商品库侧SKU不存在

BIZ_STATUS_CAN_NOT_BE_SOLD

业务商品库侧SKU状态为不可售

ACTIVITY_PRICE_EXCEPTION

活动商品库侧商品价格异常

ACTIVITY_EXIST_SESSION_NOT_EXIST

存在活动库不存在任何有效的场次库

LM_SKU_LIST_NOT_EXIST

基础库中不存在任何SKU

LM_DIVISION_SALES_RESTRICTION

此商品在当前配送区域限售

ITEM_TAGS_LIMIT_CAN_NOT_BE_SOLD

商品标签限制不可售

6.商品扩展属性

属性名

数据类型

描述

taxInvoice

String(64)

税率(单位:分)

taxRateCode

String(64)

税码

2.3 分销商品库信息变更通知

1.接口说明

商品库单个商品关键信息发生变化时,通知到客户系统

2.接口约定

  • 接口名称:distributionItemChangeNotify

  • 使用场景:B端管控

  • URL:被通知方提供地址,分销域按固定格式通知

  • 发起方:LinkedMall

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3.入参约定

属性名

变量名

是否必须

数据类型

备注

请求标识

requestId

Y

String(64)

请求标识

lm商品标识

lmItemId

Y

String

lm商品ID

商品标识

itemId

N

Long

商品ID

分销商城ID

distributorMallId

Y

String

分销商城ID

通知类型

noticeType

Y

String

  • ITEM_UP_SHELF:商品上架(SKU维度)

  • ITEM_DOWN_SHELF:商品下架(SKU维度)

  • ADD_ITEM:添加商品(SKU维度)

  • REMOVE_ITEM:移除商品(SKU维度)

  • MODIFY_PRICE:渠道价格变更(SKU维度)

  • EDIT_ITEM:商品图文详情变更(商品维度)

  • CHANGE_SKU_TITLE:商品SKU名称(SKU维度)

  • CHANGE_SKU_IMAGE:商品SKU图片 (SKU维度)

通知时间

noticeTime

Y

String

通知时间

扩展信息

extInfo

Y

String

详细信息如下表所示。

签名

signature

Y

String(128)

签名字段值

签名方法

signatureMethod

Y

String(128)

默认: SHA256WithRSA

通知类型对应扩展信息结构

通知类型

扩展信息字段示例

ITEM_UP_SHELF

{

"skuId":72673284

}

ITEM_DOWN_SHELF

{

"skuId":72673284

}

ADD_ITEM

{

"skuId":72673284

}

REMOVE_ITEM

{

"skuId":72673284

}

MODIFY_PRICE

{

skuId:72673284,

oldPriceCent:1000,

newPriceCent:200

}

EDIT_ITEM

{

title:"商品标题",

mainPicUrl:"http://xxxx.cdn/1.jpg",

images:[

"http://xxxx.cdn/1.jpg","http://...."

],

descOption:"商品图文信息"

}

CHANGE_SKU_TITLE

[

{

skuId:72673284,

skuTitle:"天蓝色"

},

{

skuId:72673285,

skuTitle:"咖啡色"

}

]

CHANGE_SKU_IMAGE

[

{

skuId:72673284,

skuPicUrl:"http://img.alicdn.com/imgextra/1.png"

},

{

skuId:72673285,

skuPicUrl:"http://img.alicdn.com/imgextra/2.png"

}

]

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String

SUCCESS表示成功

错误信息

message

N

String

失败时,返回具体原因

请求ID

requestId

Y

String

2.4. 查询商品详情接口(支持区域库存)

1.接口说明

查询商品详细信息,支持区域库存查询

2.接口约定

  • 接口名称:queryItemDetailWithDivision

  • 使用场景:C端查询商品详情,支持区域库存

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3.入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商城ID

distributionMallId

Y

String(64)

分销商城 ID

LM商品ID

lmItemId

Y

String(64)

LM商品ID

区域码

divisionCode

N

String(64)

如果为空,默认查询全部区域库存

4.返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

操作日志号

logsId

N

String

每次请求操作对应的操作日志号,由系统自动生成,可用于排查问题,双方日志中统一透出此标识

错误子代码

subCode

N

String

用于显示业务类的错误代码,一般建议关注此类错误

错误子代码信息

subMessage

N

String

业务处理相关的错误信息,一般建议关注此类错误

商品信息

model

Y

DistributionItemDetailModel

分销商品信息

DistributionItemDetailModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

商品规格列表

skuModels

Y

List<DistributionItemSkuDetailModel>

商品规格列表

商品规格PV属性列表

skuPropertys

Y

List<SkuPropertyModel>

商品规格属性PV对列表,用于渲染页面下单时,选择下单参数

LM商品ID

lmItemId

Y

String

LM商品ID

商品ID

itemId

Y

Long

商品ID

商品名称

itemTitle

Y

String

商品名称

主图地址

mainPicUrl

Y

String

主图

首图地址

firstPicUrl

Y

String

轮播图第一张图

轮播图

itemImages

Y

List<String>

商品图片URL,最多10张,一般是Detail上轮播

商品详情介绍地址

descPath

N

String

商品详情介绍-图片介绍,URL

商品图文详情

descOption

N

String

商品详情介绍-图片介绍信息

商品最低SKU价格

minPrice

Y

Long

商品所有SKU中,最低的SKU的价格。如果商品下只有一个SKU,则直接为该SKU的供货价;如果商品下有多个SKU,则显示的是所有SKU里的最低价。(分)

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

商品库存

quantity

N

Integer

商品库存,如果只有一个SKU,则直接是SKU上的库存。如果商品有配送区域库存,且查询接口里指定了配送区域,则返回的是对应区域库存

模糊化库存

simpleQuantity

Y

String

模糊化库存

例如:有货、无货、库存紧张

是否有库存

hasQuantity

Y

Boolean

是否有库存,返回的是库存状态,有或者没有

叶子类目ID

categoryId

Y

Long

叶子类目ID(叶子类目,即最末类目。由于主站不同商品的类目长度不同,不确定该叶子类目处于正向第几级类目)

类目链ID

categoryIds

N

List<Long>

类目ID,父类目在前,子类目在后,叶子类目在最后

商品所在省份

prov

N

String

商品所在省份:如浙江

商品所在城市

city

N

String

商品所在城市:如杭州

产品参数

properties

N

Map<String, Set<String>>

产品属性或产品参数,供Detail页面显示使用

例如:

{颜色分类: ["桔色", "军绿色"]}

产品特征

features

N

Map<String, String>

商家配置产品特征

tax_invoice:税率

tax_rate_code:税码,全国统一

extraPeriod:保质期,用于食品

food_pro_date:生产日期

关键属性

iforestProps

N

List<Map<String, String>>

关键属性,供Detail页面显示使用

例如:

[{value: "军绿色", key: "颜色分类"}, {value: "桔色", key: "颜色分类"}]

是否包邮

SellerPayPostfee

N

boolean

是否包邮

是否可售

isCanSell

Y

boolean

是否可销售,目前主要判断了商品的状态是否正常,同时库存要求大于0

平台商品的类型

lmItemCategory

Y

String

商品在LinkedMall平台的类型

  • entity:实物商品

  • aliComBenifit:虚拟商品

客户自定义属性

customizedAttributeMap

N

Map<String, String>

商品维度的扩展属性PV

(客户自定义属性)

详见6.商品扩展属性

平台商品属性

lmItemAttributeMap

N

Map<String, String>

商品维度的扩展属性PV

(商家扩展属性或系统扩展属性)

详见6.商品扩展属性

当前时间

current

Y

Date

当前时间

虚拟商品类型

virtualItemType

N

String

虚拟商品类型,该字段为枚举类型,值为cardRoll(卡券)、rechageableCard(充值卡)、fuelCard(油卡)

外部商品ID

thirdPartyItemId

N

String

外部商品ID (来自第三方的商品)

商品来源

thirdPartyName

N

String

商品来源 (标记第三方商品的来源)

视频地址

vIDeoUrl

N

String

视频地址

视频封面地址

vIDeoPicUrl

N

String

视频封面地址

不可售编码

canNotBeSoldCode

N

String

不可售编码,可售时为空

不可售消息

canNotBeSoldMessage

N

String

不可售消息,可售时为空

总量库存值

itemTotalValue

N

Integer

总量库存值

总量库存模糊值

itemTotalSimpleValue

Y

String

总量库存模糊值

例如:有货、无货、库存紧张

DistributionItemSkuDetailModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

预留扩展字段

extJson

N

String

预留扩展字段,JSON-Map结构

LM商品ID

lmItemId

Y

String

LM商品ID

IC商品ID

itemId

Y

Long

IC商品ID

规格ID

skuId

Y

Long

规格ID

属性PV值组合

skuPvs

N

String

Sku对应的属性PV值组合

规格图片地址

skuPicUrl

N

String

Sku图片

规格标题

skuTitle

N

String

SKU对应的属性显示Title。多个属性组合值之间用斜线分隔。

SKU库存

quantity

N

Integer

SKU库存。如果商品有配送区域库存,且查询接口里指定了配送区域,则返回的是对应区域库存

SKU模糊化库存

simpleQuantity

Y

String

SKU模糊化库存

例如:有货、无货、库存紧张

是否有库存

hasQuantity

Y

Boolean

是否有库存,返回的是库存状态,有或者没有

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

SKU供货价

priceCent

Y

Long

分销渠道商给分销商的SKU供货价格。 每次交易单个商品SKU会从分销商支付宝账户扣的金额。(分)

规格状态

status

Y

Integer

商品规格售卖状态

1:商品可售卖2:商品不可售卖3:商品价格异常4:商品被删除

客户自定义属性

customizedAttributeMap

N

Map<String, String>

规格维度的扩展属性PV

(客户自定义属性)

详见6.商品扩展属性

平台SKU属性

lmSkuAttributeMap

N

Map<String, String>

规格维度的扩展属性PV

(商家扩展属性或系统扩展属性)

详见6.商品扩展属性

不可售编码

canNotBeSoldCode

N

String

不可售编码,可售时为空

不可售原因

canNotBeSoldMessage

N

String

不可售消息,可售时为空

SkuPropertyModel说明

属性名

变量名

是否必须

数据类型

备注

规格属性ID

ID

Y

Long

规格属性ID

属性键P

text

Y

String

属性键P

属性值列表

values

Y

List<SkuPropertyValueModel>

属性值列表

SkuPropertyValueModel说明

属性名

变量名

是否必须

数据类型

备注

属性值ID

ID

Y

Long

属性值ID

属性值V

text

Y

String

属性值V

2.5. 查询商品类目信息

1.接口说明

查询商品类目信息

2.接口约定

  • 接口名称:queryMallCategoryList

  • 使用场景:B端查询商品类目信息

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:10

3.入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商城ID

distributionMallId

Y

String(64)

分销商城ID

类目ID

categoryId

Y

Long

类目ID;0 表示查询一级类目,传入指定类目ID时只会返回当前类目的下级类目列表(传入N级类目,返回N+1级类目列表)

说明

该字段与叶子类目ID不同,请注意区分。

4.返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

操作日志号

logsId

N

String

每次请求操作对应的操作日志号,由系统自动生成,可用于排查问题,双方日志中统一透出此标识

错误子代码

subCode

N

String

用于显示业务类的错误代码,一般建议关注此类错误

错误子代码信息

subMessage

N

String

业务处理相关的错误信息,一般建议关注此类错误

类目列表

model

Y

List<Category>

List<Category>

Category

属性名

变量名

是否必须

数据类型

备注

类目ID

categoryId

Y

Long

类目ID

类目名称

name

Y

String

类目名称

父级类目ID

parentId

Y

Long

父级类目ID

是否是叶子类目

leaf

Y

Boolean

是否是叶子类目

2.6. 查询商品建议零售价格

1.接口说明

查询商品的建议零售价格。

说明

接口数据现已为实时数据,考虑到短时间多次大量请求,接口引入缓存(缓存失失效时间为10分钟)第一次查询后,后续请求查询缓存内数据(若在缓存失效时间内对商品价格进行修改,实时查询接口并不能查询到修改后的价格,需等待缓存失效后再查询便能得到修改后的价格)。

2.接口约定

  • 接口名称:queryItemGuIDeRetailPrice

  • 使用场景:B端查询商品建议零售价格

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:10

3.入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商商城ID

distributionMallId

Y

String(64)

分销商商城ID

LM商品ID

lmItemIds

Y

List<String>

LM商品ID列表,最多单次允许查询20条商品记录

4.返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

操作日志号

logsId

N

String

每次请求操作对应的操作日志号,由系统自动生成,可用于排查问题,双方日志中统一透出此标识

错误子代码

subCode

N

String

用于显示业务类的错误代码,一般建议关注此类错误

错误子代码信息

subMessage

N

String

业务处理相关的错误信息,一般建议关注此类错误

商品信息

model

Y

List<DistributionItemPriceDetailModel>

分销商品信息

DistributionItemPriceDetailModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

LM商品ID

lmItemId

Y

String

LM商品ID

商品ID

itemId

Y

Long

商品ID

商品名称

itemTitle

Y

String

商品名称

SKU划线价

reservedPrice

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

SKU划线价格范围

reservedPriceScope

Y

String

一个商品下,所有SKU的划线价范围。(分)

零售价格范围

guIDeRetailPriceScope

Y

String

一个商品下,所有SKU的建议零售价格范围。(分)

最低零售价格范围

lowGuIDeRetailPriceScope

N

String

由于需求的变动-查询T+1的数据改为查询实时数据,在此情况下获取不到该商品的价格信息;在不影响现有客户获取该字段值的情况下,目前lowGuideRetailPriceScope值处理为guideRetailPriceScope(一个商品下,所有SKU的建议零售价格范围)的值(分)

商品规格列表

skuModels

Y

List<DistributionItemSkuPriceDetailModel>

商品规格列表

DistributionItemSkuPriceDetailModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

LM商品ID

lmItemId

Y

String

LM商品ID

IC商品ID

itemId

Y

Long

IC商品ID

规格ID

skuId

Y

Long

规格ID

规格标题

skuTitle

N

String

SKU对应的属性显示Title。多个属性组合值之间用斜线分隔。

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

SKU零售价格

guIDeRetailPrice

Y

Long

商品SKU建议零售价。(分)

SKU最低零售价格

lowGuIDeRetailPrice

N

Long

由于需求的变动-查询T+1的数据改为查询实时数据,在此情况下获取不到商品的该价格信息;在不影响现有客户获取该字段值的情况下,目前lowGuideRetailPrice值处理为guideRetailPrice(商品SKU建议零售价)的值(分)

SKU供货价

priceCent

Y

Long

销渠道商给分销商的SKU供货价格。 每次交易单个商品SKU会从分销商支付宝账户扣的金额。(分)

规格状态

status

Y

Integer

商品规格售卖状态

  • 1:商品可售卖

  • 2:商品不可售卖

  • 3:商品价格异常

  • 4:商品被删除

2.7.查询商品列表(无本地缓存)

1.接口说明

查询商品列表,无本地缓存,只适用于B端管控。

2.接口约定

  • 接口名称:listDistributionItemWithoutCache

  • 使用场景:B端管控

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

  • QPS限制:5

3.入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String(64)

分销商ID

分销商商城ID

distributionMallId

Y

String(64)

分销商商城ID

LM商品ID

lmItemId

N

String

LM商品ID

商品状态

itemStatus

N

Integer

商品状态

  • 1:可售

  • 2:不可售

  • 不传:则查所有状态

页码

pageNumber

N

Integer

请求页码,默认为1

每页数量

pageSize

N

Integer

每页数量范围(1-20),默认20

4.返回值约定

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

SUCCESS 表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方,在日志中打印

操作日志号

logsId

N

String

每次请求操作对应的操作日志号,由系统自动生成,可用于排查问题,双方日志中统一透出此标识

错误子代码

subCode

N

String

用于显示业务类的错误代码,一般建议关注此类错误

错误子代码信息

subMessage

N

String

业务处理相关的错误信息,一般建议关注此类错误

当前页

pageNumber

Y

Long

当前页

每页显示条数

pageSize

Y

Long

每页显示条数

总数量

totalCount

Y

Long

总数量

商品信息

model

Y

List<DistributionItemWithoutCacheModel

分销商品信息

DistributionItemWithoutCacheModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

商品规格列表

skuModels

Y

List<DistributionItemSkuWithoutCacheModel

商品规格列表

商品规格PV属性列表

skuPropertys

N

List<SkuPropertyModel>

商品规格属性PV对列表,用于渲染页面下单时,选择下单参数(当商品是无规格产品的时候,对应的PV属性列表为空)

LM商品ID

lmItemId

Y

String

LM商品ID

商品ID

itemId

Y

Long

商品ID

商品名称

itemTitle

Y

String

商品名称

主图地址

mainPicUrl

Y

String

主图

首图地址

firstPicUrl

Y

String

轮播图第一张图

轮播图

itemImages

Y

List<String>

商品图片URL,最多10张,一般是Detail上轮播

商品详情介绍地址

descPath

N

String

商品详情介绍-图片介绍,URL

商品图文详情

descOption

N

String

商品详情介绍-图片介绍信息

商品最低SKU价格

minPrice

Y

Long

商品所有SKU中,最低的SKU的价格。如果商品下只有一个SKU,则直接为该SKU的供货价;如果商品下有多个SKU,则显示的是所有SKU里的最低价。(分)

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

商品库存

quantity

N

Integer

商品库存,如果只有一个SKU,则直接是SKU上的库存。

模糊化库存

simpleQuantity

Y

String

模糊化库存

例如:有货、无货、库存紧张(库存数量<=10)

是否有库存

hasQuantity

Y

Boolean

是否有库存,返回的是库存状态,有或者没有

叶子类目ID

categoryId

Y

Long

叶子类目ID(叶子类目,即最末类目。由于主站不同商品的类目长度不同,不确定该叶子类目处于正向第几级类目)

类目链ID

categoryIds

N

List<Long>

类目ID,父类目在前,子类目在后,叶子类目在最后

商品所在省份

prov

N

String

商品所在省份:如浙江

商品所在城市

city

N

String

商品所在城市:如杭州

产品参数

properties

N

Map<String, Set<String>>

产品属性或产品参数,供Detail页面显示使用

例如:

{颜色分类: ["桔色", "军绿色"]}

产品特征

features

N

Map<String, String>

商家配置产品特征

  • tax_invoice:税率

  • tax_rate_code:税码,全国统一

  • extraPeriod:保质期,用于食品

  • food_pro_date:生产日期

关键属性

iforestProps

N

List<Map<String, String>>

关键属性,供Detail页面显示使用

例如:

[{value: "军绿色", key: "颜色分类"}, {value: "桔色", key: "颜色分类"}]

是否包邮

SellerPayPostfee

N

boolean

是否包邮

是否可售

isCanSell

Y

boolean

是否可销售,目前主要判断了商品的状态是否正常,同时库存要求大于0;

平台商品的类型

lmItemCategory

Y

String

商品在linkedmall平台的类型

  • entity:实物商品

  • aliComBenifit:虚拟商品

客户自定义属性

customizedAttributeMap

N

Map<String, String>

客户自定义属性

平台商品属性

lmItemAttributeMap

N

Map<String, String>

Linkedmall 平台商品属性

当前时间

current

Y

Date

当前时间

虚拟商品类型

virtualItemType

N

String

虚拟商品类型,该字段为枚举类型,值为cardRoll(卡券)、rechageableCard(充值卡)、fuelCard(油卡)

外部商品id

thirdPartyItemId

N

String

外部商品id (来自第三方的商品)

商品来源

thirdPartyName

N

String

商品来源 (标记第三方商品的来源)

视频地址

videoUrl

N

String

视频地址

视频封面地址

videoPicUrl

N

String

视频封面地址

不可售编码

isCanNotBeSoldCode

N

String

不可售编码,可售时为空

不可售消息

isCanNotBeSoldMessage

N

String

不可售消息,可售时为空

总量库存值

itemTotalValue

N

Integer

总量库存值

总量库存模糊值

itemTotalSimpleValue

Y

String

总量库存模糊值

例如:有货、无货、库存紧张

DistributionItemSkuWithoutCacheModel说明

属性名

变量名

是否必须

数据类型

备注

分销商城ID

distributionMallId

Y

String

分销商城ID

预留扩展字段

extJson

N

String

预留扩展字段,JSON-Map结构

LM商品ID

lmItemId

Y

String

LM商品ID

IC商品ID

itemId

Y

Long

IC商品ID

规格ID

skuId

Y

Long

规格ID

属性PV值组合

skuPvs

N

String

SKU对应的属性PV值组合(当商品是无规格产品的时候,对应的PV属性为空)

规格图片地址

skuPicUrl

N

String

SKU图片

规格标题

skuTitle

N

String

SKU对应的属性显示Title。多个属性组合值之间用斜线分隔。

SKU库存

quantity

N

Integer

SKU库存。如果商品有配送区域库存,且查询接口里指定了配送区域,则返回的是对应区域库存

SKU模糊化库存

simpleQuantity

Y

String

SKU模糊化库存

例如:有货、无货、库存紧张

是否有库存

hasQuantity

Y

Boolean

是否有库存,返回的是库存状态,有或者没有

SKU划线价

reservedPrice

Y

Long

商品SKU原价,可用于显示划线价。商品SKU在主站侧的划线价。(分)

规格销售价格

priceCent

Y

Long

分销渠道商给分销商的SKU供货价格。 每次交易单个商品SKU会从分销商支付宝账户扣的金额。(分)

规格状态

status

Y

Integer

商品规格售卖状态

1:商品可售卖 2:商品不可售卖 3:商品价格异常 4:商品被删除

客户自定义属性

customizedAttributeMap

N

Map<String, String>

客户自定义属性

平台SKU属性

lmSkuAttributeMap

N

Map<String, String>

LinkedMall平台SKU的属性

不可售编码

canNotBeSoldCode

N

String

不可售编码,可售时为空

不可售原因

canNotBeSoldMessage

N

String

不可售消息,可售时为空

SkuPropertyModel说明

属性名

变量名

是否必须

数据类型

备注

规格属性ID

id

Y

Long

规格属性ID

属性键P

text

Y

String

属性键P

属性值列表

values

Y

List<SkuPropertyValueModel>

属性值列表

SkuPropertyValueModel说明

属性名

变量名

是否必须

数据类型

备注

属性值ID

id

Y

Long

属性值ID

属性值V

text

Y

String

属性值V

说明

canNotBeSoldMessage不可售字段透出的信息,与2.1 查询商品列表中的tips字段相同。

3. 分销交易

3.1. 分销采购订单渲染

1. 接口说明

C端用户购买某个商品前,渲染用户订单。

重要

请务必在调用3.2接口创建采购订单之前,先调用3.1接口做渲染和校验。

3.1接口负责渲染订单的同时,会对订单做拆单逻辑和自动校验(包括库存校验、可售状态校验等)。如果绕过3.1接口,可能会导致创单失败。

2. 接口约定

  • 接口名称: renderDistributionOrder

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

渠道供应商ID

distributionSupplierId

Y

String

分销渠道供应商ID

分销真实买家ID

buyerId

Y

String

该字段请务必传入分销商城侧的每个C端用户对应的唯一身份ID

(传入的身份ID可以是虚拟ID,但必须与真实用户一一对应。仅用于主站区分不同用户身份,防止触发主站风控,导致您下单失败)

商品信息

itemInfoLists

Y

List<ItemInfo>

收货地址

deliveryAddress

Y

String

收货地址,json串格式

扩展信息

extInfo

N

String

扩展信息,json串格式

ItemInfo

{
  "lmItemId" : "xxx",//LM商品ID
  "distributionMallId":"xxxx",//分销商城ID
  "skuId" : "xxx",//商品规格skuId,无规格输入-1(请区分商品id(lmItemId)和商品规格id(skuId))
  "quantity": 1  // 下单数量 (Integer类型)
}

deliveryAddress

{ 
    "divisionCode": "区/县的5级divisionCode(街道/镇的上一级地址)", //该字段通过queryChildDivisionCodeById接口获取
    "townDivisionCode":"街道/镇的5级divisionCode", //该字段通过queryChildDivisionCodeById接口获取
    "fullName": "收货人姓名", 
    "mobile": "收货人电话", 
    "addressDetail": "收货人地址" 
}

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

请求ID

requestId

Y

String

请求ID,SDK自动生成

返回码

code

Y

String

成功:“0000”,错误码见后面小节

错误信息

message

N

String

失败时,返回具体原因

返回数据

model

N

JSON

渲染结果

model数据结构

{
    "AddressInfos": [
      {
        "AddressDetail": "xxx省 xx市 xx区 xx街道",
        "ReceiverPhone": "176xx213",
        "TownDivisionCode": "441xx002",
        "Receiver": "李xx",
        "DivisionCode": "44xx02",
        "AddressId": 0
      }
    ],
    "RenderOrderInfos": [   // 可售商品列表,一个店铺一条。
      {
        "DeliveryInfos": [
          {
            "PostFee": 0,
            "ServiceType": -4, //类型列表: -4 == 快递, -7 == EMS, -1 == 平邮
            "DisplayName": "快递 包邮 (专属权益)",
            "Id": "20"
          }
        ],
        "ItemInfos": [
          {
            "ItemPicUrl": "xxxx.png",
            "Price": 100, // 价格
            "ItemName": "xxxx商品",
            "SkuName": "xxx",
            "Quantity": 1,  // 购买数量
            "Features": {
              "delivery_version": "2"
            },
            "SkuId": 3233xx212,
            "ItemId": "xxx-xxx",
            "DistributionMallId": "xxxxx",
            "CanSell": true
          }
        ],
        "CanSell": true
      }
    ],
    "UnsellableRenderOrderInfos": [  // 不可售商品列表,无不可售商品时不返回
      {
        "ItemInfos": [
          {
            "ItemPicUrl": "xxxx.jpg",
            "Message": "不可售原因",
            "Price": 10, // 价格
            "ItemName": "商品名称",
            "Quantity": 1,
            "Features": {
              "delivery_version": "6"
            },
            "SkuId": -1,
            "ItemId": "xxx-xxx",
            "DistributionMallId": "xxxxxxx",
            "CanSell": false
          }
        ],
        "CanSell": false
      }
    ],
    "CanSell": true
  }

常见返回值参考错误码

错误码

含义

CANNOT_BUY

1、该商品在您的分销业务库中为不可售状态,请联系企业购小二。

2、该商品有多个SKU,您下单的SKU当前为不可售状态。

3、商家设置了区域限购或者区域库存为0。

4、入参传递错误,如无规格商品skuId传-1(记得区分itemId和skuId哦)。

ADD_ADDRESS_ERROR

1、收货地址参数错误(参考渲染demo

2、已触发主站并发风控,请为每位C端用户填入唯一buyerId或稍后重试

1019

DeliveryAddress填写异常(如divisionCode为空)

QUERY_ITEM_ERROR_PLEASE_RETRY

对应分销业务库没有该商品

MISSING_PARAMETER

入参参数漏传(例如:分销商ID漏传、商品数量漏传)

DISTRIBUTION_REQUEST_PARAM_ERROR

入参BuyerId为空(请您务必传入与C端用户一一对应的身份ID)

DISTRIBUTION_PART_ITEM_NOT_EXIST

购买的多个商品有某个或者多个在分销业务库不存在或者SKU填写错误

PARAM_INVALID

参数填写错误无效(例如:分销商城ID、addressDetail填写错误、商品数量为0)

SYSTEM_ERROR

1、请求超时,请重试

2、系统错误,待排查

3.2. 提交分销采购订单创建请求

1. 接口说明

异步接口,只是提交创建分销订单申请,可能会存在返回交易号但是创建结果失败的场景,具体创建结果以分销订单创建结果通知或者主动调查询分销交易状态接口为准。

重要
  • buyerId(分销真实买家ID)字段请留意,该字段请务必传入分销商城侧的每个C端用户对应的唯一身份ID

    若不填写与真实用户相对应的身份ID,将有可能触发主站下单风控(例如由于同一C端用户的过多不同收货地址引发风控导致创单一直失败)和下单接口并发度降低等业务和技术风险。请您务必传入与C端用户一一对应的身份ID。请检查一下3.1和3.2接口处buyerId传入信息是否符合该规范。

  • distributionOutTradeId(分销外部交易号)字段请留意,分销外部交易号为您商城C端用户下单的订单号。为避免您的资损,强烈建议传入该字段

  • ItemInfo.price(商品价格)字段请留意,商品价格为渲染接口返回商品price或通过商品详情接口返回的SKU供货价。为避免您的资损,强烈建议传入该字段

2. 接口约定

  • 接口名称: applyCreateDistributionOrder

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

渠道供应商ID

distributionSupplierId

Y

String

分销渠道供应商ID

分销外部交易号

distributionOutTradeId

N

String

分销外部交易号为您商城C端用户下单的订单号。为避免您的资损,强烈建议传入该字段

传入外部交易号后,会以其作为创建分销采购单请求的幂等键。若不填写该字段,可能导致重复请求而重复创单发货,造成您的资损。

外部交易号也会在3.4交易结果通知中透出。

分销真实买家ID

buyerId

Y

String

该字段请务必传入分销商城侧的每个C端用户对应的唯一身份ID

(传入的身份ID可以是虚拟ID,但必须与真实用户一一对应。仅用于主站区分不同用户身份,防止触发主站风控,导致您下单失败)

商品信息

itemInfoLists

Y

List<ItemInfo>

收货地址

deliveryAddress

Y

String

收货地址,json串格式

扩展信息

extInfo

N

String

扩展信息,json串格式

ItemInfo

{
  "lmItemId" : "xxx",//LM商品ID
  "distributionMallId":"xxxx",//分销商城ID
  "skuId" : "xxx",//商品规格skuId,无规格输入-1(请区分商品id(lmItemId)和商品规格id(skuId))
  "quantity": 1,  // 下单数量 (Integer类型)
  "price": 500    // 分销商下单时支付的商品价格
}

deliveryAddress

{   
    "divisionCode": "街道/镇的5级divisionCode", //该字段通过queryChildDivisionCodeById接口获取
    "townDivisionCode":"街道/镇的5级divisionCode", //该字段通过queryChildDivisionCodeById接口获取
    "fullName": "收货人姓名", 
    "mobile": "收货人电话", 
    "addressDetail": "收货人地址" 
}

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

请求ID

requestId

Y

String

请求ID,SDK自动生成

返回码

code

Y

String

成功:“0000”,错误码见后面小节

错误信息

message

N

String

失败时,返回具体原因

响应数据

model

Y

String

分销交易号。调用失败返回空串。

常见返回值参考错误码

错误码

含义

1019

DeliveryAddress填写异常(如divisionCode为空)

ADD_ADDRESS_ERROR

1、收货地址参数错误(参考创单请求demo

2、已触发主站并发风控,请为每位C端用户填入唯一buyerId或稍后重试。

DISTRIBUTION_TRADE_ITEM_ERROR

请求入参itemInfoLists里存在商品规格(skuId)不唯一

3.3. 查询分销交易状态

1. 接口说明

只返回分销交易状态。

2. 接口约定

  • 接口名称: queryDistributionTradeStatus

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

渠道供应商ID

distributionSupplierId

Y

String

分销交易号

distributionTradeId

Y

String

分销交易号

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

请求ID

requestId

Y

String

返回码

code

Y

String

成功:“0000”,错误码见后面小节

错误信息

message

N

String

失败时,返回具体原因

分销交易状态

model

Y

String

分销交易状态枚举值:

  • 1:分销单创建中

  • 10:采购中

  • 20:采购成功,待发货

  • 21:采购成功,部分发货

  • 22:采购成功,全部发货

  • 30:部分采购成功,待发货

  • 31:部分采购成功,部分发货

  • 32:部分采购成功,全部发货

  • 80:交易失败

  • 81:采购失败

  • 99:交易成功

常见返回值参考错误码

错误码

含义

DISTRIBUTION_TRADE_NOT_FOUND

分销交易创单已失败。返回交易单号并不意味着创单成功,创单是否成功以3.4. 分销采购订单创建结果通知为准。

SYSTEM_ERROR

1、timeout连接超时,请重试

2、系统错误,待排查

3.4. 分销采购订单创建结果通知

1. 接口说明

分销订单创建结果通知,包括分销交易状态,及分销订单的信息。

2. 接口约定

  • 接口名称: syncDistributionStatus

  • 使用场景:C端交易

  • URL:被通知方提供地址,分销域按固定格式通知

  • 发起方:LinkedMall

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

请求ID

requestId

Y

String

请求ID,幂等号

分销交易号

distributionTradeId

Y

String

分销交易号,可能会包含多笔主单。

分销外部交易号

distributionOutTradeId

N

String

3.2 创建分销交易时如果传入了外部交易号,则在该通知中返回。

分销外部交易号为您商城C端用户下单的订单号。为避免您的资损,强烈建议在3.2接口传入该字段

分销商ID

distributorId

Y

String

渠道供应商ID

distributionSupplierId

Y

String

分销交易状态

distributionTradeStatus

Y

String

分销交易状态枚举值:

  • 1:分销单创建中

  • 10:采购中

  • 20:采购成功,待发货

  • 21:采购成功,部分发货

  • 22:采购成功,全部发货

  • 30:部分采购成功,待发货

  • 31:部分采购成功,部分发货

  • 32:部分采购成功,全部发货

  • 80:交易失败

  • 81:采购失败

  • 99:交易成功

失败原因

failReason

N

String

分销交易失败时,传递失败原因

子分销订单信息

subDistributionOrderInfoList

N

String

分销交易创建成功才有数据,否则为空

JSON.toString(List<distributionOrderInfo>)

{
    "createDate": "yyyy-MM-dd HH:mm:ss",
    "logisticsStatus": "主单物流状态",
    "mainDistributionOrderId": "分销主订单号",
    "orderAmount": "主单金额",
    "orderStatus": "主单状态",
    "subOrderList": [
        {
            "itemId": "分销商品ID",
            "itemPic": "商品图片地址",
            "itemPriceList": [
                {
                    "fundAmountMoney": "商品价格"
                }
            ],
            "itemTitle": "商品名称",
            "number": "商品数量",
            "orderStatus": "子单状态", // Integer类型
            "skuId": "SKUID",
            "skuName": "SKU名称",
            "subDistributionOrderId": "子订单号"
        }
    ]
}
{
    "distributionTradeId":"123123",
    "subDistributionOrderInfoList":[
        {
            "createDate":"2023-03-23 10:51:19",
            "enableStatus":"0",
            "logisticsStatus":"8",
            "mainDistributionOrderId":"123123",
            "orderAmount":"34500",
            "orderStatus":"2",
            "subOrderList":[
                {
                    "itemId":"10027770-683623254480",
                    "itemPic":"//img.alicdn.com/imgextra/i4/723491166/O1CN01GXxvZY1KU4WkQcGdI_!!723491166.jpg",
                    "itemPriceList":[
                        {
                            "fundAmountMoney":"34500"
                        }
                    ],
                    "itemTitle":"LM测试001",
                    "number":"1",
                    "orderStatus":2,
                    "skuId":"4884784372403",
                    "skuName":"桔色",
                    "subDistributionOrderId":"123123"
                }
            ]
        }
    ],
    "signature":"Pjj4I+ruAD90YO8LpOKzo+Ll8HggTMkx7NSdAQeuQ0R47C85JDpYeTM7bz45JKvTQtoQ0JvemC058bZVqwRKH98fb8vd42+rSz3y0/skRT2rvtSkvIJsRY3YfNnqKJoccjfydTFnANxmRO9syIyKnhpmhIYXGzkNBYOOWwOrrX8zEIk3rTITgu20GuAsLRcGmL1EbY6kFrKPVoToJqw3clIgbVyuNvu3zTliqAoAJKlmsAoBfGAb2A4Au0eif51DqrIeIiqDozZmRaHGau+y0MYk8/20u1pGnTVECxx88HLhjJhTDvoXDvMEeMKVYsf+uUri1hy4pooRPb+I89B50w==",
    "requestId":"123123",
    "distributorId":"XXXX",
    "signatureMethod":"SHA256WithRSA",
    "distributionSupplierId":"XXXX",
    "distributionTradeStatus":20
}

4. 返回值约定

  • 编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

请求ID

requestId

Y

String

返回码

code

Y

String

SUCCESS表示成功

错误信息

message

N

String

失败时,返回具体原因

说明

重试机制

  • 通知方案:批处理任务(数据量大的情况下可能会有积压)

  • 通知次数上限:20

  • 重试时间间隔:5s~10s

3.5. 分销采购订单确认收货

1. 接口说明

只支持主分销订单确认收货。

2. 接口约定

  • 接口名称:confirmDisburse4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

分销交易号

distributionTradeId

N

String

分销交易号,如果传递了分销交易号表示整个分销交易一起确认收货。与主分销订单号不能同时为空。

主分销订单号

mainDistributionOrderId

N

String

主分销订单号,按分销主单确认收货

与分销交易号不能同时为空。

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String

0000表示成功

错误信息

message

N

String

失败时,返回具体原因

请求标识

requestId

Y

String

建议调用方打印日志

常见返回值参考错误码:

错误码

含义

FAIL

1、交易下无可确认收货的订单(该交易号对应的分销单号均已确认收货)

2、订单的物流状态处于未发货状态

3、分销交易号或者主订单号填写有误

3.6. 分销采购订单退款申请初始化

1. 接口说明

逆向退款申请初始化,在发起退款申请之前调用,以便申请方渲染退款页面给用户。

重要

请务必在调用3.7接口创建退款申请之前,先调用3.6接口做初始化。

3.6接口出参reasonTextId(退款原因ID)须作为3.7接口的入参applyReasonTextId(退款原因ID)。若绕过3.6接口,会导致退款申请失败。

  1. 订单未发货只能申请仅退款(BizClaimType=1)

  2. 订单已发货只能申请货物状态为未收到货(goodsStatus=1)或已收到货(goodsStatus=2)

  3. 逆向申请具体情况如下:(payStatus即指订单状态orderStatus)

    • 售中(未确认收货 payStatus 2)

      • 仅退款:物流状态 logisticsStatus 1未发货;货物状态 goodstatus 4未发货

      • 仅退款:物流状态 logisticsStatus 2已发货;货物状态 goodstatus 1未收到货

      • 退货退款:货物状态 goodstatus 2已收到货

    • 售后(已确认收货 payStatus 6)

      • 仅退款:goodstatus 2已收到货

      • 退货退款:goodstatus 2已收到货

2. 接口约定

  • 接口名称: initApplyRefund4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

退款类型

bizClaimType

Y

Integer

  • 1:仅退款

  • 3:退货退款

货物状态

goodsStatus

Y

Integer

  • 1:未收到货

  • 2:已收到货

  • 3:已寄回

  • 4:未发货

  • 5:卖家确认收货

  • 6:已发货

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String

0000表示成功

错误信息

message

N

String

失败时,返回具体原因

请求标识

requestId

Y

String

建议调用方打印日志

数据

model

Y

JSON

初始化的逆向申请参数

{
  	"subDistributionOrderId":"子分销订单号",  
  	"bizClaimType": 1,   // 支持的订单退货方式,1, 标识仅退款,3,标识退货退款
    "mainOrderRefund": false, // 是否是整单退
    "maxRefundFeeData":{
       "maxRefundFee": 100, //本单最大可退款金额
       "minRefundFee": 10   // 本单最小可退款金额
    },
    "refundReasonList": [
        {
            "reasonTextId": "12323",
            "reasonTips": "拍多不想要",
            "proofRequired": true, //是否要求上传凭证
            "refundDescRequired": true //是否要求留言
        }
    ]
}

售后原因匹配说明

在订单申请退款时,不同商品可选的售后原因列表主站侧返回内容不同,为了减少接入方在匹配售后原因时的困扰,下面整理出了绝大多处场景下的售后原因优先级列表。我们将按照展示优先级顺序,与主站返回的商品的售后原因列表进行匹配,最终只返回优先级最高的一条,其他的售后原因将被过滤不透出。很偶尔的情况下,如果某商品售后原因列表未匹配上下面任何一条,则会将售后原因列表全量返回,不做过滤。

前台原因

原因展示优先级

拍错/多拍/不喜欢

1

拍错/多拍

2

拍错/多拍

3

多拍/不想要

4

拍错/多拍/取消服务

5

不想要了

6

我不想要了

7

不喜欢/不想要

8

不喜欢或效果不好

9

7天无理由退换货

10

与商家协商一致退款

11

没用/少用优惠

12

协商一致退款

13

商品信息拍错(规格/尺码/颜色等)

14

订单信息拍错(规格/尺码/颜色等)

15

地址/电话信息填写错误

16

其他

17

其他个人原因

18

未按正常流程调用接口错误码返回说明

code

message

错误码出现的业务场景

REFUND_IN_PROCESS_NOT_REPEAT

售后单处理中,请勿重复提交

存在被商家拒绝的售后单(售后状态为6)时,调用逆向初始化申请退款出现。

REFUND_DONE_NOT_REPEAT

退款已完毕,请勿重复操作

已经申请过全款退款的订单,再次申请售后退款会出现

常见返回值参考错误码:

错误码

含义

1004

1、退款申请次数已达上限(售中三次、售后两次)

2、参数不对应(物流状态、退款类型要与订单保持一致)

unknownError

分销订单创建失败

REFUND_IN_PROCESS_NOT_REPEAT

该售后单正在处理,请勿重复提交

FAIL

入参订单号输入有误

REFUND_DONE_NOT_REPEAT

退款已完毕,请勿重新操作

3.7. 分销采购订单退款申请

1. 接口说明

基于 initApplyRefund4Distribution接口获取退款申请初始化信息,发起退款或者退货退款申请,该接口不支持退换货。

  1. 正常售中允许申请退款三次,售后允许申请退款两次,如遇超过次数后不能申请退款,需自行联系商家打开线上退款入口(售中和售后的界定边缘为:确认收货)

  2. 逆向申请具体情况如下:(payStatus即指订单状态orderStatus)

    • 售中(未确认收货 payStatus 2)

      • 仅退款:物流状态 logisticsStatus 1未发货;货物状态 goodstatus 4未发货

      • 仅退款:物流状态 logisticsStatus 2已发货;货物状态 goodstatus 1未收到货

      • 退货退款:货物状态 goodstatus 2已收到货

    • 售后(已确认收货 payStatus 6)

      • 仅退款:goodstatus 2已收到货

      • 退货退款:goodstatus 2已收到货

说明

上传退款凭证须知:由于部分商家内部小二网络受阿里内部安全管控影响无法查看非阿里系OSS的图片,请务必使用阿里云的OSS服务作为您的图片存储,详细请参见企业采购客户上传退款凭证须知

2. 接口约定

  • 接口名称:applyRefund4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId​

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

退款类型

bizClaimType

Y

Integer

1:仅退款

3:退货退款

申请退款金额

applyRefundFee

Y

Long

分为单位

退货数量

applyRefundCount

N

Integer

退货数量,可不传

退款原因ID

applyReasonTextId

Y

Long

选择的reasonTextId,通过3.6initApplyRefund4Distribution接口获取

留言

leaveMessage

N

String

买家说明,某些原因要求必须留言

凭证

leavePictureLists

N

List<LeavePictureList>

凭证,某些原因要求必须有凭证。需要传图片的URL地址,实现方式为强制下载,勿使用静态资源映射

货物状态

goodsStatus

Y

Integer

当退款类型为仅退款时,货物状态为4未发货。

所有状态:

  • 1:未收到货

  • 2:已收到货

  • 3:已寄回

  • 4:未发货

  • 5:卖家确认收货

  • 6:已发货

leavePictureLists

    "leavePictureLists": [ // 用户举证的图片信息,基于initApplyRefund4Distribution接口返回的proofRequired和选择的具体原因,要求用户是否上传图片
    	{
    		"picture": "https://xxx.oss-cn-hangzhou.aliyuncs.com/xxx/x/xxxImg?Expires=1666337433&OSSAccessKeyId=TMP.3KgQ8WYr7H6mi333WxtuQrrjDSkdvdkiN1DmpEGb2psPeA4D3w2o87QYPzhj1gEeBnKEoYjKxdK9****&Signature=LRzRl0YO6%2FyFtvCn50KMryHAw%3D",
        "desc": "瑕疵的商品图片"
			}
    ]

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(8)

0000表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方打印日志

响应数据

model

Y

JSON

申请的返回数据

{
    "subDistributionOrderId": "12131234", // 当前发起逆向的子分销订单号
    "disputeStatus": 1, // 逆向的状态
    "disputeType": 0, // 任意退款类型
    "disputeId": 1232131 // 纠纷ID
}

常见返回值参考错误码

错误码

含义

1004

1、退款申请入参校验未通过(如:订单未发货状态,请求货物状态必须是未发货、未按要求上传凭证)

2、不支持当前退款操作(退款申请过了15天售后期)

unknownError

分销订单创建失败

3.8. 分销采购订单退款申请修改初始化

1. 接口说明

获取订单相关的逆向修改数据,必须在发起退款申请之后调用。

重要

请务必在调用3.9接口修改退款申请之前,先调用3.8接口做初始化。

3.8接口出参reasonTextId(退款原因ID)须作为3.9接口的入参applyReasonTextId(退款原因ID)。若绕过3.8接口,会导致退款申请修改失败。

注意:

  1. 订单未发货只能申请仅退款(BizClaimType=1)

  2. 订单已发货只能申请货物状态为未收到货(goodsStatus=1)或已收到货(goodsStatus=2)

  3. 逆向申请具体情况如下:(payStatus即指订单状态orderStatus)

    • 售中(未确认收货 payStatus 2)

      • 仅退款:物流状态 logisticsStatus 1未发货;货物状态 goodstatus 4未发货

      • 仅退款:物流状态 logisticsStatus 2已发货;货物状态 goodstatus 1未收到货

      • 退货退款:货物状态 goodstatus 2已收到货

    • 售后(已确认收货 payStatus 6)

      • 仅退款:goodstatus 2已收到货

      • 退货退款:goodstatus 2已收到货

2. 接口约定

  • 接口名称: initModifyRefund4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId​

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

退款类型

bizClaimType

Y

Integer

1 仅退款,3 退货退款

纠纷ID

disputeId

Y

Long

纠纷ID,通过查询订单逆向申请详情接口获取

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String

0000表示成功

错误信息

message

N

String

失败时,返回具体原因

请求标识

requestId

Y

String

建议调用方打印日志

数据

model

Y

JSON

初始化的逆向申请参数

{
    "subDistributionOrderId":"子分销订单号",
    "bizClaimType": 1,   // 支持的订单退货方式,1, 标识仅退款,3,标识退货退款
    "mainOrderRefund": false, // 是否是整单退
    "maxRefundFeeData":{
       "maxRefundFee": 100, //本单最大可退款金额
       "minRefundFee": 10   // 本单最小可退款金额
    },
    "refundReasonList": [
        {
            "reasonTextId": "12323",
            "reasonTips": "拍多不想要",
            "proofRequired": true, //是否要求上传凭证
            "refundDescRequired": true //是否要求留言
        }
    ]
}

售后原因优化匹配说明

不同的商品的订单申请退款时,可选的售后原因列表不同,为了减少接入方在匹配售后原因时的困扰,下面整理出了绝大部分场景下的售后原因优先级列表,按照展示优先级,与订单的售后原因列表进行匹配,返回优先级最高的一条。如果没有匹配到下面任何一条,则会将所有售后原因列表都返回。

前台原因

原因展示优先级

拍错/多拍/不喜欢

1

拍错/多拍

2

拍错/多拍

3

多拍/不想要

4

拍错/多拍/取消服务

5

不想要了

6

我不想要了

7

不喜欢/不想要

8

不喜欢或效果不好

9

7天无理由退换货

10

与商家协商一致退款

11

没用/少用优惠

12

协商一致退款

13

商品信息拍错(规格/尺码/颜色等)

14

订单信息拍错(规格/尺码/颜色等)

15

地址/电话信息填写错误

16

其他

17

其他个人原因

18

常见返回值参考错误码

错误码

含义

1004

纠纷单不存在(纠纷ID,通过查询订单逆向申请详情接口queryRefundApplicationDetail4Distribution获取)

3.9. 分销采购订单退款申请修改

1. 接口说明

基于 initModifyRefund4Distribution 接口获取退款信息,发起退款或者退货退款修改申请,该接口不支持退换货

注意:

  1. 正常售中允许申请退款三次,售后允许申请退款两次,如遇超过次数后不能申请退款,需自行联系商家打开线上退款入口(售中和售后的界定边缘为:确认收货)

  2. 逆向申请具体情况如下:(payStatus即指订单状态orderStatus)

    • 售中(未确认收货 payStatus 2)

      • 仅退款:物流状态 logisticsStatus 1未发货;货物状态 goodstatus 4未发货

      • 仅退款:物流状态 logisticsStatus 2已发货;货物状态 goodstatus 1未收到货

      • 退货退款:货物状态 goodstatus 2已收到货

    • 售后(已确认收货 payStatus 6)

      • 仅退款:goodstatus 2已收到货

      • 退货退款:goodstatus 2已收到货

说明

上传退款凭证须知:由于部分商家内部小二网络受阿里内部安全管控影响无法查看非阿里系OSS的图片,请务必使用阿里云的OSS服务作为您的图片存储,详细请参见企业采购客户上传退款凭证须知

2. 接口约定

  • 接口名称:modifyRefund4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId​

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

退款类型

bizClaimType

Y

Integer

1 仅退款, 3 退货退款

申请退款金额

applyRefundFee

Y

Long

分为单位

退货数量

applyRefundCount

N

Integer

退货数量,可不传

退款原因ID

applyReasonTextId

Y

Long

选择的reasonTextId,通过3.8initModifyRefund4Distribution接口获取

留言

leaveMessage

N

String

买家说明,某些原因要求必须留言

凭证

leavePictureLists

N

List<LeavePictureList>

凭证,某些原因要求必须有凭证。需要传图片的URL地址,实现方式为强制下载,勿使用静态资源映射

货物状态

goodsStatus

Y

Integer

当退款类型为仅退款时,货物状态为4未发货。

所有状态

  • 1:未收到货

  • 2:已收到货

  • 3:已寄回

  • 4:未发货

  • 5:卖家确认收货

  • 6:已发货

​纠纷ID

​disputeId

Y

Long

​纠纷ID,通过查询订单逆向申请详情接口获取

    "leavePictureLists": [ // 用户举证的图片信息,基于initModifyRefund4Distribution接口返回的proofRequired和选择的具体原因,要求用户是否上传图片
    	{
    		"picture": "https://xxx.oss-cn-hangzhou.aliyuncs.com/xxx/x/xxxImg?Expires=1666337433&OSSAccessKeyId=TMP.3KgQ8WYr7H6mi333WxtuQrrjDSkdvdkiN1DmpEGb2psPeA4D3w2o87QYPzhj1gEeBnKEoYjKxdK9****&Signature=LRzRl0YO6%2FyFtvCn50KMryHAw%3D",
        "desc": "瑕疵的商品图片"
			}
    ]

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(64)

0000表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方打印日志

响应数据

model

Y

JSON

申请的返回数据

{
    "subDistributionOrderId": "12131234", // 当前发起逆向的子订单号
    "disputeStatus": 1, // 逆向的状态
    "disputeType": 0, // 任意退款类型
    "disputeId": 1232131 // 纠纷ID
}

常见返回值参考错误码

错误码

含义

1004

不允许当前退款协议修改,修改协议参数有错误(例如:已收到货的货物状态无法修改成未收到货或未发货状态)

3.10. 取消分销采购订单退款申请

1. 接口说明

如果已经提交了退款申请,商家还未响应时,客户想取消退款申请,可以通过此接口取消。

说明

disputeId字段需要通过查询订单逆向申请详情(queryRefundApplicationDetail4Distribution)接口获取。

2. 接口约定

  • 接口名称:cancelRefund4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId​

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

纠纷ID

disputeId

Y

Long

纠纷ID,通过查询订单逆向申请详情接口获取

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(64)

0000表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方打印日志

响应数据

model

Y

JSON

取消申请的返回数据

{
    "subDistributionOrderId": "12131234", // 当前发起逆向的子分销订单号
    "disputeStatus": 1, // 逆向的状态
    "disputeType": 0 // 任意退款类型
}

常见返回值参考错误码

错误码

含义

1004

参数有误(例如:售后单ID入参有误)

REFUND_DONE_CANCEL_INVALID

退款已完毕,不支持取消退款

3.11. 提交分销采购订单退货物流信息

1. 接口说明

如果提交了退货申请,通过该接口提交退货的物流信息。

  1. 只有在卖家同意退款(通过queryRefundApplicationDetail4Distribution接口查询到disputeStatus为2时)且需要退回货物时,才能调此接口

  2. DisputeId字段需要通过查询订单逆向申请详情(queryRefundApplicationDetail4Distribution)接口获取

2. 接口约定

  • 接口名称:submitReturnGoodLogistics4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId​

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

纠纷ID

disputeId

Y

Long

纠纷ID

物流单号

logisticsNo

Y

String

物流单号

公司代码

cpCode

Y

String

物流公司代码

// 常见物流:
{
  "STO": "申通快递", 
	"HTKY": "百世快递",
	"DBKD": "德邦快递",
	"EYB": "EMS经济快递",
	"QFKD": "全峰快递",
	"ZJS": "宅急送",
	"SF": "顺丰速运",
	"ZTO": "中通快递",
	"TTKDEX": "天天快递",
	"YTO": "圆通快递",
	"YUNDA": "韵达快递",
	"OTHER": "其他",
	"POST": "中国邮政",
 	"EMS": "EMS",
 	"FEDEX": "联邦快递",
 	"SHQ": "华强物流",
 	"TN": "特能",
 	"TAOBAO": "淘宝物流",
 	"ZTKY": "中铁物流"
}

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(64)

0000表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方打印日志

常见返回值参考错误码

错误码

含义

1004

参数错误(例如:物流单号必须填写真实物流单号)

FAIL

无法识别的快递公司代号(具体的快递公司代号见文档、没有的快递公司代号填“OTHER”)

LOGISTIC_NO_CHECK_ERROR

物流单号有误,请检查后重新上传

3.12. 查询分销采购订单退款申请

1. 接口说明

基于子分销订单号查询逆向申请的详情

说明
  • 一般申请退款成功之后通过此接口确认逆向的状态(disputeStatus)以及纠纷ID(disputeId)等

  • 退货信息请优先参考sellerAgreeMsg字段,如果该字段为空、null、或者不包含退货地址、手机号等信息时,再参考refunderAddress、refunderName、refunderTel等字段

2. 接口约定

  • 接口名称:queryRefundApplicationDetail4Distribution

  • 使用场景:C端交易

  • URL:阿里云SDK

  • 发起方:分销商城

  • 编码方式:UTF-8

  • 请求方式:POST

  • Content-Type:application/json

3. 入参约定

属性名

变量名

是否必须

数据类型

备注

分销商ID

distributorId

Y

String

做API级别权限控制

子分销订单ID

subDistributionOrderId​

Y

String

发起退款的子分销订单号,可在查询订单详情接口中获取

4. 返回值约定

编码方式:UTF-8

属性名

变量名

是否必须

数据类型

备注

返回码

code

Y

String(64)

0000表示成功

错误信息

message

N

String(128)

失败时,返回具体原因

请求标识

requestId

Y

String(64)

建议调用方打印日志

响应数据

model

Y

JSON

初始化的逆向申请参数

{
    "distributionOrderId": "123498124", // 对应的主分销订单号
    "subDistributionOrderId": "12131234", // 当前发起逆向的子分销订单号
    "bizClaimType": 1,   // 支持的订单退货方式,1, 标识仅退款,3,标识退货退款
    "orderLogisticsStatus": 1, // 当前的订单的物流状态,1,标识未发货
    "disputeStatus": 1, // 逆向的状态
    "returnGoodLogisticsStatus": 0, //退货物流状态
    "disputeType": 0, // 逆向发生的类型
    "refundFeeData":{
       "maxRefundFee": 100, //本单最大可退款金额
       "minRefundFee": 10   // 本单最小可退款金额
    },
    "sellerRefuseReason": "商品没问题,买家举证无效",//商家拒绝原因
    "refundFee": 12121, // 退款金额(含退平台补贴的金额)
    "realRefundFee": 12121, // 实际买家收到的金额
    "disputeDesc": "mmmmmm", // 申请逆向描述
    "sellerAgreeMsg": "同意退款", // 卖家同意退货说明,真实的退货地址会在这个字段进行返回。
    "sellerRefuseAgreementMessage": "不同意退款", // 卖家拒绝的留言说明
    "applyReason": {  //买家申请的逆向原因
	     "reasonTextId": 12323,
       "reasonTips": "拍多不想要",
    },
    "applyDisputeDesc": "多拍不想要", //当前买家申请退款说明
    "disputeCreateTime": "逆向发起时间",
    "disputeEndTime": "逆向结束时间",
		"disputeId": 123123, // 纠纷ID,
    "refunderAddress": "商家退货地址", //卖家同意退货后才显示,
    "refunderName":"退货收货人", //卖家同意退货后才显示,
    "refunderTel":"退货联系方式", //卖家同意退货后才显示,
    "refunderZipCode":"退货地址邮编" //卖家同意退货后才显示
}

disputeStatus:
1: "买家已经申请退款,等待卖家同意"  # 买家提交退款申请
2: "卖家已经同意退款,等待买家退货"  # 卖家同意用户退款申请
3: "买家已经退货,等待卖家确认收货"  # 换货/退货退款场景下,买家提交退货物流信息
4: "退款关闭"                    # 买家关闭退款申请
5: "退款成功"                    # 卖家同意退款
6: "卖家拒绝退款"								  # 卖家拒绝用户退款申请
7: "等待买家确认重新邮寄的货物"     
8: "等待卖家确认退货地址"
9: "没有申请退款"
10: "有活动的退款"
11: "退款结束"
12: "卖家确认收货,等待卖家发货"    # 换货场景下,卖家收到买家退货物品
14: "换货关闭,转退货退款"         # 买家切换售后类型:换货->退货退款
13: "卖家已发货,等待卖家和买家确认收货" 
15: "邮费单已创建,待激活"

returnGoodLogisticsStatus:
0: "未退货"
1: "等待揽收"
2: "快件已揽收"
3: "物流走件中"
4: "派送中"
5: "已签收"
6: "签收失败"

disputeType:
0: "任意退款类型"
1: "售中退款"
2: "售后退款"

常见返回值参考错误码

错误码

含义

FAIL

1、该订单并没有申请退款

2、分销订单输入有误,分销订单不存在

DISTRIBUTION_REQUEST_PARAM_ERROR

查询订单号为空

SYSTEM_ERROR

1、timeout超时,请重试

2、系统错误,待排查

3.13. 分销采购订单物流通知

1. 接口说明

物流状态时同步物流信息给分销客户

说明

客户侧需对请求验签,验签逻辑以及公钥等请在服务群内通过@LinkedMall小二签名自行获取​

物流通知包含两部分内容,1)物流状态 2)物流单号

  • 情况一:部分发货时,处理发货的子单,根据分销子单的采购单号进行包裹匹配,如果匹配到包裹,则通知分销子单的物流状态和包裹的物流单号。如果没有匹配到包裹,则只通知分销子单的物流状态。

  • 情况二:全部发货时,处理所有子单,根据分销子单的采购单号进行包裹匹配,如果匹配到包裹,则通知分销子单的物流状态和包裹的物流单号。如果没有匹配到包裹,则只通知分销子单的物流状态。

以上情况中,如果存在新的包裹未匹配到子单号,则会通知主单的物流状态和所有未匹配的包裹。

2. 接口约定