文档中心 > 商家经营工具-开发指引

一、背景

 

平台通过获取商家在订单全链路履约数据,通过数字化视图处理后在商家、消费者侧进行物流时效的表达,提升消费者物流体验、并降低商家经营成本。

服务商需将商家订单履约数据上翻至平台,数据内容包含:订单在ERP、OMS、WMS等系统里处理信息。

 

image

 

二、订单全链路使用场景

 

1. 大促场景订单流转全链路监控:保障大促期间订单正常流转,当订单在ISV系统产生异常堆积,平台能快速感知并协同服务商进行解决处理,更多详情请查看:订单全链路监控产品介绍

2. 子订单多包裹:子单拆分成多个包裹后,通过ISV回传包裹发货信息及包裹对应成分信息,展示在手淘前台,提升消费者物流体验。

3. 更多全链路协同场景:订单全链路将陆续应用在改地址等场景中,提升商家、消费者的经营和购物体验。

 

三、名词解释

 

组合品和成分品:组合品是一个单独售卖的SKU,由多个成分品构成,如:一个组合品为“桌椅套装”,包含成分品1:1张桌子,成分品2:4把椅子。

注意:成分品和组合品目前仅支持商家通过千牛后台进行发布维护,无法通过TOP接口发布组合品和成分品信息,但交易接口可获取子订单成分品信息。

组合品详细介绍:https://open.taobao.com/doc.htm?docId=121196&docType=1

 

标准品:即未填写成分品信息的正常商品,如上文“桌椅套装,1张桌子,4把椅子”未维护成分品信息,也算标准品。

 

四、链路概览

image

 

涉及API

使用方

接口变更说明

订单详情

taobao.trade.fullinfo.get

ERP

增加子订单成分品信息

增加子订单部分发货场景,对应的运单号列表及成分品信息

退款API

taobao.refund.get

ERP

退款详情中,增加组合商品下的成分品清单

发货

alibaba.ascp.logistics.offline.send (老接口升级)

alibaba.ascp.logistics.consign.modify(新接口)

ERP

发货接口支持场景:部分发、全部发、补发、“部分发货”的订单 无包裹订正为 "全部发货"

新增接口修改运单号

新增接口:商品成分品查询

alibaba.item.edit.schema.get(老接口改造)

ERP

增加成分品相关信息字段

taobao.qimen.event.produce

ERP

订单状态回传(原订单全链路接口请查看文档:订单全链路监控产品接入,本次会针对拆合单结果回传新增字段)

若历史上未接入订单全链路监控,请先按文档进行接入。

 

五、API详情

1. 奇门API

 

taobao.qimen.event.producetaobao.qimen.events.produce(批量接口) 原接口升级。

 

原始字段

 

image

 

新增字段

 

字段名

说明

备注

erpOrderId

erp单号

主单号对应的erp单号,转单、审单、通知配货、出库 需要填。拆单、合单场景下不用填。

taobaoSubOrderIds

淘宝子订单号集合

转单、审单、通知配货、出库 需要填,按照实际场景,传对应的子单即可。

拆单、合单场景下不用填。

eventTime

产生事件时间

触发事件的时间。

 

字段修改

 

字段名

说明

status

枚举值:

转单:QIMEN_ERP_TRANSFER、X_TO_SYSTEM

审单:QIMEN_ERP_CHECK、X_SERVICE_AUDITED、X_SEND_PRINTED

通知配货:QIMEN_CP_NOTIFY、X_ALLOCATION_NOTIFIED、X_WAIT_ALLOCATION

仓库通知ERP出库:QIMEN_CP_OUT、X_OUT_WAREHOUSE

拆单:QIMEN_ERP_SPLIT (新增)

合单:QIMEN_ERP_MERGE (新增)

 

备注:拆单、合单节点只需在ERP内部作业的最后一个环节(即erp发货单创建)调用即可。若无拆单、合单操作,这忽略这两个节点即可。

tid

淘宝主订单id,合单场景填任意值即可,实际逻辑不会消费此字段。

 

接口扩展支持拆合单

 

ext字段回流数据结构

"ext": {
  // 拆单信息

  "splitInfo": {
    "erpId": "发货单的erpId",  // 发货单的erpId
    "taobaoSubOrderId": "淘宝子订单id",
    "orders": [
      {
        "taobaoSubOrderId": "淘宝子订单", 
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      },
      {
        "taobaoSubOrderId": "淘宝子订单", 
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
  

  // 合单结构
  "mergeInfo": {
    "erpId": "发货单的erpId", // 对淘宝子订单id1 和 淘宝子订单id2 做了合单操作,对应的发货单id
    "orders": [
      {
        "taobaoSubOrderId": "淘宝子订单id", // 淘宝交易子订单,如果为主单合单,taobaoSubOrderId = taobaoMainId
        "taobaoMainId": "淘宝主订单id",
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      },
      {
                "taobaoSubOrderId": "淘宝子订单id", // 淘宝交易子订单,如果为主单合单,taobaoSubOrderId = taobaoMainId
        "taobaoMainId": "淘宝主订单id",
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
  
}

 

以几个场景为例,举例说明拆合单传参细节:

前置条件:主订单A有三个子订单:{a, b, c}

 

场景一:由erp系统操作后,变成{a}, {b, c}两个包裹发货 这种场景下,认为主订单A被拆单发货了。

调用两次拆单接口 或 一次批量接口即可。ext传参如下:

// 第一次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // a的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "a"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第二次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // b的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "b"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      },
      {
        "taobaoSubOrderId": "b"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

 

场景二:由erp系统操作后,变成{a} {b} {c}三个包裹发货,这种场景下,认为主订单A被拆单发货了,调用三次拆单接口 或 一次批量接口即可。ext传参如下:

// 第一次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId", // a的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "a"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第二次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // b的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "b"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第三次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // c的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "c"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

 

场景三:由erp系统操作后,变成{a} {b} {c1} {c2}四个包裹发货,这种场景下,认为主订单A被拆单发货了,调用四次拆单接口 或 一次批量接口即可。ext传参如下:

// 第一次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // a的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "a"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第二次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // b的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "b"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第三次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId", // c1的发货单erpId
    "taobaoSubOrderId": "c", // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": null, // 这种场景非必要填
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第四次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // c2的发货单erpId
    "taobaoSubOrderId": "c", // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": null, 
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

 

场景四:如果还有个一主一子订单B {d} , 最后变成 {a,d} {b} {c1, c2} 三个包裹发货, {a,d} 属于合单操作。 {b}、{c1,c2} 属于拆单操作 。 这种情况下调用一次合单接口,两次拆单接口 即可。ext传参如下:

// 第一次合单传参:
{
    "mergeInfo": {
    "erpId": "发货单的erpId", // a、d对应发货单的erpId
    "orders": [
      {
        "taobaoSubOrderId": "a", // 淘宝交易子订单,如果为主单合单,taobaoSubOrderId = taobaoMainId
        "taobaoMainId": "A",
        "skuId": "淘宝skuId",
      
        "itemId": "淘宝itemId",
        "count": "商品数量"
      },
      {
                "taobaoSubOrderId": "d", // 淘宝交易子订单,如果为主单合单,taobaoSubOrderId = taobaoMainId
        "taobaoMainId": "B",
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第二次拆单传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // b的发货单erpId
    "taobaoSubOrderId": null, // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": "b"
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      }
    ]
  }
}

// 第三次传参:
{
    "splitInfo": {
    "erpId": "发货单的erpId",  // c1-c2对应发货单的erpId
    "taobaoSubOrderId": "c", // 不是根据子订单拆单,不需要填
    "orders": [
      {
        "taobaoSubOrderId": null, 
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      },
      {
        "taobaoSubOrderId": null, 
        "skuId": "淘宝skuId",
        "itemId": "淘宝itemId",
        "count": "商品数量"
      },
    ]
  }
}

 

2. 交易API

 

API

taobao.trade.fullinfo.get

 

出参

1)若存在成分品信息,子订单详情中,增加组合商品下的成分品清单;

2)主订单信息中,增加赠品包裹物流详情及子订单对应多包裹物流详情。

 

名称

类型

示例值

描述

orders

Order[]

 

订单列表

-combine_item_info

combineItemInfo[]

 

组合品(成分品)子商品列表

注意:获取此部分信息需要在入参的fields填orders.combine_item_info才会有返回

-- item_id

Number

2342344

商品id

-- item_name

String

测试商品

商品标题

-- quantity

Number

 

数量

-- sku_id

String

5937146

商品的最小库存单位Sku的id

-- outer_iid

String

152e442aefe88dd41cb0879232c0dcb0

商家外部编码(可与商家外部系统对接)

-- sku_title

String

16g

SKU标题

-- origin_fee

Number

123

成分品原价

-- combine_sub_item_fee

Number

123

成分品套餐原价

-- outer_id

String

123

外部ID

combine_logistics_details(与orders同级)

combine_logistics_detail[]

 

子订单对应多包裹物流详情

-- invoice_no

String

 

运单号

-- logistics_company

String

 

物流公司

-- sub_order_id

Number

 

子订单id

-- send_goods_detail

send_goods_detail[]

 

包裹详情

--- type

Number

 

0普通1组合商品2组套商品3后置赠品4状态推进

--- consign_status

Number

 

0全部发货1部分发货

--- amount

Number

 

数量

--- goods_detail

goods_details[]

 

成分品发货物品详情,非成分品不支持

---- sku_id

String

 

sku_Id

---- amount

Number

 

数量

---- item_id

Number

2342344

商品id

-- 其余物流相关字段不再列出,参见 https://open.taobao.com/api.htm?docId=54&docType=2

     

 

3. 退款API

 

API

taobao.refund.get

 

出参

退款详情中,增加组合商品下的成分品清单。

 

名称

类型

示例值

描述

refund

Refund[]

 

订单列表

-combine_item_info

combineItemInfo[]

 

组合品(成分品)子商品列表

-- item_name

String

测试商品

商品名称

-- quantity

Number

 

数量

-- num_iid

Number

2342344

商品数字编号

-- sku_id

String

5937146

商品的最小库存单位Sku的id

-- outer_iid

String

152e442aefe88dd41cb0879232c0dcb0

商家外部编码(可与商家外部系统对接)。外部商家自己定义的商品Item的id,可以通过taobao.items.custom.get获取商品的Item的信息

-- 其余相关字段不再列出,参见 https://open.taobao.com/api.htm?&source=search&docId=53&docType=2

     

 

4. 物流API

4.1 发货接口

 

alibaba.ascp.logistics.offline.send (老接口升级)

 

支持场景:

1)部分发;

2)全部发;

3)补发;

4)“部分发货”的订单 无包裹订正为 "全部发货"。

 

名称

类型

必须

示例值

描述

tid

String

true

123

淘宝交易ID(发货对象模型)

feature

String

false

 

主交易单扩展字段

sender_id

Number

false

123456

发货寄件场景下,卖家联系人地址库ID,可以通过taobao.logistics.address.search接口查询到地址库ID。如果为空,取的卖家的默认寄件地址

cancel_id

Number

false

123456

退回寄件场景下,卖家联系人地址库ID,可以通过taobao.logistics.address.search接口查询到地址库ID。 如果为空,取的卖家的默认退货地址

sub_tids

String

false

1,2,3

子订单id列表(consign_type = 1、2、3 时不再使用次字段,使用新字段goods代替子订单信息

consign_type

Number

true

1

发货类型 0:普通发货(原链路)

1:普通发货(新链路,覆盖老链路功能,并支持子单多批次发货、成分品和ERP线下赠品发货

2:无包裹推进发货状态

3:补发; 默认0

consign_pkgs

TopConsignPkgRequest[]

true

 

包裹信息模型

--out_sid

String

true

123455

运单号.具体一个物流公司的真实运单号码。淘宝官方物流会校验,请谨慎传入

--company_code

String

true

POST

物流公司代码.如"POST"就代表中国邮政,"ZJS"就代表宅急送.调用 taobao.logistics.companies.get 获取

--goods

TopConsignGoods

   

包裹商品信息模型

----sub_tid

String

true

100001

子交易单单号

----item_type

Number

false

0

商品类型 0:普通品、平台赠品,1:线下erp赠品,2:成分品 默认0

----comp_item_id

Long

false

22222

成分品itemid,在成分品场景下必填

----comp_sku_id

Long

false

33333

成分品skuid,在成分品场景下必填

----num

Number

false

2

商品发货数量,不传默认为下单时的商品数量,

支持不传,但不能传0

consign_status

TopConsignStatusRequest[]

   

子订单发货状态

--sub_tid

String

true

100001

子订单id(组合品不需要传,系统会自动判断状态)

--is_part_consign

Boolean

false

true

是否部分发;true:“部分发”,fasle:”全部发货“,默认false

 

入参举例

 

case1 子订单发货

 

4.1.1.1 子订单“部分发货”
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                  "subTid": "123456789",
                  "num" : 1
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignStatus": [
        {
            "isPartConsign": true,
            "subTid": "123456789"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

tips:

① consignType = 1 ;

② consignStatus 传需要部分发的子订单,且isPartConsign = true(true:部分发货 false:全部发货,默认不填为false)。

 

4.1.1.2 子订单“全部发货”
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

 

4.1.1.3 主订单“全部发货”
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

tips:

① 不传goods信息,只通过主订单id推进发货;

 

case2 成分品发货

 

成分品信息:

123456789(子单)
-- 成分品A: itemId: 100001 skuId:100002 1件
-- 成分品B: itemId: 200001 skuId:200002 1件

 

4.1.2.1 组合品"部分发货"
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "compItemId": "100001",
                    "compSkuId": "100002",
                    "num": 1,
                    "itemType":2,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

tips:

① itemType=2 (成分品);

② compItemId、compSkuId 成分品的itemid和skuid,成分品场景下必传。

 

4.1.2.2 成分品“全部发货”
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "compItemId": "100001",
                    "compSkuId": "100002",
                    "subTid": "123456789",
                    "itemType":2
                },
                {
                    "compItemId": "200001",
                    "compSkuId": "200002",
                    "subTid": "123456789",
                    "itemType":2
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

 

case3 ERP赠品

 

4.1.3.1 主品+赠品 “全部发货”
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "subTid": "123456789"
                },
                {
                    "itemType": 1,
                    "num": 1,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

tips:

① itemType = 1 表示赠品

 

4.1.3.2 赠品“部分发货”
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "itemType": 1,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignStatus": [
        {
            "isPartConsign": true,
            "subTid": "123456789"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

tips:

① itemType = 1 表示赠品;

② 如果数量不传默认为1;

③ 若子订单A主品未发货,只单独发了赠品,则需要指定子订单A发货状态为“部分发货"(isPartConsign= true)。

 

case4 已发货后的“补发”

 

4.1.4.1 补发普通品
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 3,
    "tid": "123456789"
}

tips:

① 子单必须全部发货之后才可以补发;

② consignType = 3(补发类型)。

 

4.1.4.2 补发成分品
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "compItemId": "100001",
                    "compSkuId": "100002",
                    "itemType": 2,
                    "num": 1,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 3,
    "tid": "123456789"
}

tips:

① 成分品必须全部发货之后才可以补发;

② itemType=2 (成分品);

③ compItemId、compSkuId 成分品信息必传;

④ consignType = 3(补发)。

 

4.1.4.3 补发赠品
{
    "consignPkgs": [
        {
            "cpCode": "STO",
            "goods": [
                {
                    "itemType": 1,
                    "num": 1,
                    "subTid": "123456789"
                }
            ],
            "mailNo": "1234"
        }
    ],
    "consignType": 3,
    "tid": "123456789"
}

tips

① 子订单必须全部发货之后,才能调用consignType = 3 补发赠品;

② itemType=1 (赠品);

③ consignType = 3(补发)。

 

case5 子订单从“部分发货”修改为"全部发货"

{
    "consignStatus": [
        {
            "isPartConsign": false,
            "subTid": "123456789"
        }
    ],
    "consignType": 2,
    "tid": "123456789"
}

tips:

① 子订单当前为“部分发货”,但发现已经子单实际上已经发完了,可订正子订单发货状态为“全部发货”;

② 只有普通品可以订正,成分品不可订正状态

③ consignType = 2(无包裹订正“部分发”为“全部发货”);

④ 不传consignPkgs 包裹信息。

 

FAQ:

  1. consign_type=1 (新的发货链路):支持成分品发货、非成分品部分发货和ERP赠品发货,后续将完全取代consign_type=0。
  2. num(发货数量)只作为物流详情展示所用,不作为是否子订单多批次发货的逻辑判断依据 ,是否多批次发货请使用字段 is_part_consign。原因是:因为考虑到erp组套品的场景,数量可能超发,所以不采用数量计算发货状态,比如买了一个床,发货的时候发了一个床垫,一个床主体,又发了一对床头柜,这时候的数量实际上是超过1了,用数量是不准确的,所以采用了 is_part_consign 来明确告知是“部分发货”还是最后一次“全部发货”。
  3. 关于数量计算的举例
    1. 普通品买了5件
      1. 全部发3件,会在物流详情展示:包裹A已发3件
      2. 全部发6件,会在物流详情展示:包裹A已发6件
      3. 部分发货3件,会在物流详情展示:包裹A已发3件,剩余2件
      4. 部分发5件,会在物流详情展示:包裹A已发5件,剩余1件
      5. 部分发6件,会在物流详情展示:包裹A已发6件,剩余1件
      6. 数量不传部分发,会在物流详情展示:包裹A已发5件,剩余1件
      7. 数量不传全部发,会在物流详情展示:包裹A已发5件
      8. 第一次部分发货3件,第二次全部发数量不传,会在物流详情展示:一个包裹3件,一个包裹2件
    1. 组合品(成分品A 2件,成分品B 3件)* 2 (成分品不支持再By数量多次发货)
      1. 成分品A发货(数量不传),物流详情展示:包裹A已发成分品A 4件,剩余6件(成分品B 6件)
      2. 成分品A发货(3件),物流详情展示:包裹A已发成分品A 3 件,剩余6件(成分品B 6件)
      3. 成分品A发货(5件),物流详情展示:包裹A已发成分品A 5 件,剩余6件(成分品B 6件)
  1. consign_type=2 (无包裹将子订单发货状态从“部分发货”推进为“全部发货”) 使用前提:

答:本质上是一次发货状态的订正,比如子订单A第一次用包裹A “部分发货”,子订单A第二次用包裹B “部分发货”,这时发现A已经全部发完了,因为引入了"部分发货",需要将A的状态由“部分发货”修正为“全部发货”,这个时候用consign_type=2 ,consign_status(sub_tid + is_part_consign=false)。

  1. consign_status(子订单发货状态): 只需要传标品的子订单状态,因为组合品是否“全部发货”由系统自动判定不需要告知。建议:只有标品部分发货的时候传consign_status(sub_tid + is_part_consign=true),其他情况缺省空着就行。
  2. consign_type=3 补发调用 前提:
    1. 标品: 必须是子订单当前状态已经是全部发货
    2. 组合品: 只要组合品下的某个成分品已经发货,那么该成分品就可以执行补发。

 

4.2 修改运单号

 

alibaba.ascp.logistics.consign.modify(新接口)

 

名称

类型

必须

示例值

描述

tid

String

true

123

淘宝交易ID(发货对象模型)

old_company_code

String

true

POST

原物流公司代码.如"POST"就代表中国邮政,"ZJS"就代表宅急送.调用 taobao.logistics.companies.get 获取

old_out_sid

String

true

123455

原运单号.具体一个物流公司的真实运单号码。淘宝官方物流会校验,请谨慎传入

new_company_code

String

true

SF

新物流公司代码.如"POST"就代表中国邮政,"ZJS"就代表宅急送.调用 taobao.logistics.companies.get 获取

new_out_sid

String

true

123455

新运单号.具体一个物流公司的真实运单号码。淘宝官方物流会校验,请谨慎传入

goods

ConsignGoodsReq

false

 

包裹商品信息模型

--sub_tid

String

true

100001

子交易单单号

--item_type

Number

false

0

商品类型 0:普通品,1:赠品,2:成分品 默认0

--comp_item_id

String

false

 

成分品itemid,在成分品场景下必填

--comp_sku_id

String

false

 

成分品skuid,在成分品场景下skuid存在则必填

 

tips:

① 同一主订单多次发货的场景时,如果两次发货的快递公司+运单号相同,在修改运单时无法判断需要修改哪一次发货行为的运单号,所以需要传包裹中的商品信息goods来唯一确定。

② 若每次发货的包裹信息不同,则无需传goods信息。

 

case1 修改运单号(不传商品信息)

{
    "oldCompanyCode": "STO",
    "oldOutSid": "1234",
    "newCompanyCode": "SF",
    "newOutSid": "123456",
    "tid": "123456789"
}

tips:

① 每次发货的物流信息都不相同时,使用此方式。

 

case2 同运单分两次发成分品A 和 成分品B

 

4.2.2.1 第一次用包裹1(STO-1234)发了成分品A
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "compItemId": "100001",
                    "compSkuId": "100002",
                    "num": 1,
                    "itemType":2,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

 

4.2.2.1 第二次用相同的包裹1(STO-1234)发了成分品B
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "compItemId": "200001",
                    "compSkuId": "200002",
                    "num": 1,
                    "itemType":2,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

 

4.2.2.3 此时想把装有成分品A的包裹1 (STO-1234)修改为 包裹2 (SF-123456)
{
    "oldCompanyCode": "STO",
    "oldOutSid": "1234",
    "newCompanyCode": "SF",
    "newOutSid": "123456",
    "tid": "123456789",
    "goods": [
                {
                    "compItemId": "200001",
                    "compSkuId": "200002",
                    "num": 1,
                    "itemType":2,
                    "subTid": "123456789"
                }
            ]
}

 

case3 同运单分两次发子订单A的主商品 和 子订单A的赠品

 

4.2.3.1 第一次用包裹1(STO-1234)“部分发”商品A
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignStatus": [
        {
            "isPartConsign": true,
            "subTid": "123456789"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

 

4.2.3.1 第二次用相同的包裹1(STO-1234)发了商品A的赠品
{
    "consignPkgs": [
        {
            "companyCode": "STO",
            "goods": [
                {
                    "num": 1,
                    "itemType":2,
                    "subTid": "123456789"
                }
            ],
            "outSid": "1234"
        }
    ],
    "consignType": 1,
    "tid": "123456789"
}

 

4.2.3.3 此时想把装有赠品的包裹1 (STO-1234)修改为 包裹2 (SF-123456)
{
    "oldCompanyCode": "STO",
    "oldOutSid": "1234",
    "newCompanyCode": "SF",
    "newOutSid": "123456",
    "tid": "123456789",
    "goods": [
                {
                    "num": 1,
                    "itemType":2,
                    "subTid": "123456789"
                }
            ]
}

 

5. 商品API

 

API

alibaba.item.edit.schema.get(该API已上线,使用线上版本即可)

 

出参

商品编辑get接口中,增加组合商品下的成分品字段。

 

字段

含义

备注

combinePackage

组合商品

combinePackage下一个complex-values为一个sku的售卖包

--packageUnitList

组合内商品

最多12个子品

----unitItemId

子品商品id

 

----unitSkuId

子品skuid

 

----unitMultiple

子品组合数

 

--packageStockShare

组合商品和子商品共享库存

次售卖包的库存模式

--skuId

组合商品的skuid

商品上的skuid

 

<field id="combinePackage" name="组合商品" type="multiComplex">
  <rules>
    <rule name="tipRule" value="若关联了组合内商品,商品的实际库存将以具体规格中组合库存模式为准,请关注下方设置。"/>
  </rules>
  <complex-values>
    <field id="packageUnitList" name="组合内商品" type="multiComplex">
      <complex-values>
        <field id="unitItemId" name="商品id" type="input">
          <value>700060143250</value>
        </field>
        <field id="unitSkuId" name="SKU id" type="input">
          <value>5118340851806</value>
        </field>
        <field id="unitMultiple" name="组合数" type="input">
          <value>2</value>
        </field>
      </complex-values>
      <complex-values>
        <field id="unitItemId" name="商品id" type="input">
          <value>700229959409</value>
        </field>
        <field id="unitSkuId" name="SKU id" type="input">
          <value>5114510878090</value>
        </field>
        <field id="unitMultiple" name="组合数" type="input">
          <value>3</value>
        </field>
      </complex-values>
      <complex-values>
        <field id="unitItemId" name="商品id" type="input">
          <value>700457939953</value>
        </field>
        <field id="unitSkuId" name="SKU id" type="input">
          <value>5044093122517</value>
        </field>
        <field id="unitMultiple" name="组合数" type="input">
          <value>3</value>
        </field>
      </complex-values>
    </field>
    <field id="packageStockShare" name="组合商品和子商品共享库存" type="singleCheck">
      <value>true</value>
    </field>
    <field id="skuId" name="skuId" type="input">
      <value>5118497803936</value>
    </field>
  </complex-values>
  <complex-values>
    <field id="packageUnitList" name="组合内商品" type="multiComplex">
      <complex-values>
        <field id="unitItemId" name="商品id" type="input">
          <value>699379583391</value>
        </field>
        <field id="unitSkuId" name="SKU id" type="input"/>
        <field id="unitMultiple" name="组合数" type="input">
          <value>5</value>
        </field>
      </complex-values>
      <complex-values>
        <field id="unitItemId" name="商品id" type="input">
          <value>699395960010</value>
        </field>
        <field id="unitSkuId" name="SKU id" type="input"/>
        <field id="unitMultiple" name="组合数" type="input">
          <value>4</value>
        </field>
      </complex-values>
      <complex-values>
        <field id="unitItemId" name="商品id" type="input">
          <value>699403524525</value>
        </field>
        <field id="unitSkuId" name="SKU id" type="input"/>
        <field id="unitMultiple" name="组合数" type="input">
          <value>6</value>
        </field>
      </complex-values>
    </field>
    <field id="packageStockShare" name="组合商品和子商品共享库存" type="singleCheck">
      <value>true</value>
    </field>
    <field id="skuId" name="skuId" type="input">
      <value>5118497803937</value>
    </field>
  </complex-values>
  <fields>
    <field id="skuId" name="skuId" type="input">
      <rules>
        <rule name="tipRule" value="组合商品 sku id"/>
        <rule name="valueTypeRule" value="long"/>
      </rules>
    </field>
    <field id="packageStockShare" name="组合商品和子商品共享库存" type="singleCheck">
      <rules>
        <rule name="tipRule" value="如果选择共享库存,则组合商品的库存会根据组合内的商品自动计算,不可单独维护;若不共享库存,则组合商品的库存可以独立维护。"/>
      </rules>
      <options>
        <option displayName="是" value="true"/>
        <option displayName="否" value="false"/>
      </options>
    </field>
    <field id="packageUnitList" name="组合内商品" type="multiComplex">
      <fields>
        <field id="unitItemId" name="商品id" type="input">
          <rules>
            <rule name="tipRule" value="子商品 id"/>
            <rule name="valueTypeRule" value="long"/>
          </rules>
        </field>
        <field id="unitSkuId" name="SKU id" type="input">
          <rules>
            <rule name="tipRule" value="子商品 sku id"/>
            <rule name="valueTypeRule" value="long"/>
          </rules>
        </field>
        <field id="unitMultiple" name="组合数" type="input">
          <rules>
            <rule name="tipRule" value="子商品的倍数"/>
            <rule name="requiredRule" value="true"/>
            <rule name="minValueRule" value="1" exProperty="include"/>
            <rule name="valueTypeRule" value="integer"/>
          </rules>
        </field>
      </fields>
    </field>
  </fields>

 

六、测试用例

 

image

 

七、服务商测试说明

1. 测试普通品子订单拆单方法

 

1)测试环境

 

SDK:使用您的Appkey在开发者控制台生成即可。

开放平台地址:开放平台生产环境域名:gw.api.taobao.com (不再提供预发域名)。

测试店铺:任意店铺。

测试买家:任意买家。

测试商品:任意商品。

 

2)测试流程

 

① 您可以使用您任意测试店铺任意商品做测试;

② 使用发货接口测试拆单发货,用fullinfo获取交易订单明细测试。

 

2. 测试成分品

 

1)测试环境

 

SDK:使用您的Appkey在开发者控制台生成即可。

开放平台地址:开放平台生产环境域名:gw.api.taobao.com (不再提供预发域名)。

商家账号:商家测试帐号1 (注意,不再支持服务商自有测试店铺,无需再做任何白名单逻辑)。

 

2)测试流程

 

① 请提供应用的Appkey,联系开放小二@新萍 生成并提供对应的sessionKey用于测试;

② 请登录开发者控制台,并提供开发者账号给小二 @新萍

点击开发——测试账号——申请借用如下账号:

c测试账号寒守

c公共测试账号01

 

image

 

手淘扫码登录

 

image

 

使用下述商品:

单品01 https://detail.tmall.com/item.htm?id=696819041658&skuId=4720453156797

单品02 https://detail.tmall.com/item.htm?id=697332691100&skuId=4720453156797

单品03 https://detail.tmall.com/item.htm?id=696516208640&skuId=4720453156797

单品04 https://detail.tmall.com/item.htm?id=697332671463&skuId=4720453156797

单品05 https://detail.tmall.com/item.htm?id=696518840048

拆单图书测试组合品01 https://detail.tmall.com/item.htm?id=696519860562

湛青商家测试1 https://detail.tmall.com/item.htm?id=702624770158

 

扫描后手淘下单

 

image

 

如果有免密支付,直接免密支付即可,如果没有免密支付,则需要使用『找朋友帮忙付』功能,下单完成后使用对应的单号测试。

 

imageimage

 

③ 使用步骤1的sessionKey 和步骤2的tid用于测试发货和订单接口。

 

八、FAQ

 

改造答疑钉钉群:25125023835

 

Q:系统中存在多次拆合单行为,该如何回传拆合单结果?

A:回传发货单创建前的最后一次拆合单结果,(针对ERP/WMS一体:在仓作业前进行回传)

 

Q:子订单如果仅拆为一个包裹发货,是否需要回传平台该笔子订单已发货完成?

A:需要。

 

Q:现在已有修改运单号接口 alibaba.ascp.logistics.consign.resend,方案中修改运单号接口alibaba.ascp.logistics.consign.modify的使用场景?

A:成分品修改运单号只能用新的接口alibaba.ascp.logistics.consign.modify,无法使用老接口alibaba.ascp.logistics.consign.resend进行修改。比如:第一次用包裹A发了成分品a1,第二次又用相同的包裹A发了成分品a2,此时想要修改装了成分品a1的包裹运单号,只能通过alibaba.ascp.logistics.consign.modify进行修改。alibaba.ascp.logistics.consign.resend暂时不下线。

 

Q:发货接口alibaba.ascp.logistics.offline.send的字段consign_type中的赠品是指什么赠品?

A:平台赠品作为一个独立的子订单存在原来就是支持的,这里的赠品是指ERP线下赠品,是这次新开发的功能。

 

Q:发货接口alibaba.ascp.logistics.offline.send的字段consign_type中的0123发货类型是指什么?

A:0是老链路的发货,1、2、3是这次子订单拆单项目衍生出的新链路,其中2.无包裹推进发货状态是发货状态的订正,因为引入了部分发货,比如商品A第一次用包裹1“部分发货”,商品A第二次用包裹2“部分发货”,这时发现A已经全部发完了,需要将A的状态由“部分发货”->“全部发货”,此时选用2。

另外1覆盖了2,如果使用了部分发、补发还有成分品发货能力的话,1就没办法使用了,建议一起切掉。

 

Q:发货接口alibaba.ascp.logistics.offline.send的字段gift_item_id、gift_sku_id是传ERP里面的id么?

A:是的。

 

Q:目前部分发货的场景?

A:标准品by数量的部分发货、组合商品by成分品部分发货。

 

Q:发货接口alibaba.ascp.logistics.offline.send补发的前提是不是当前订单状态需要全部发货完成?

A:非成分品是该子订单全部发货,组合品是组合品下的成分品发货了,那么该成分品就可以执行补发了。

 

Q:组合品发货状态需要回传么?

A:组合品发货状态会根据数量进行计算,不需要回告平台组合品发货状态。即sub_tid、is_part_consign不用回传。(只有标准品发货平台会取服务商回传的完全发货和部分发货状态,成分品平台会自己判断是否完全发货)

 

Q:标准品发货状态是否可以通过数量来告诉平台已经发货完成,而不用is_part_consign?

A:不可以,数量存在超发的情况(比如:买了一个床,发货的时候发了一个床垫,一个床主体,又发了一对床头柜,这时候的数量实际上是超过1了),发货状态需要通过发货接口is_part_consign来回告平台是否完全发货。

因此,在发货接口alibaba.ascp.logistics.offline.send的字段num只做物流详情展示用,不会作为是否全部发货的依据。

 

Q:是否支持成分品退款?

A:暂不支持,仍只能通过子订单维度退款。

 

Q:成分品占比支付金额是否在交易单中体现?

A:目前成分品金额不体现。

 

标准品、成分品关于数量计算的举例如下。

 

image

 

Q: 淘宝sdk 调用的taobao.qimen.event.produce,sdk更新了吗?

A: 预发联调域名联调——http://pre-gw.api.taobao.com/router/resttaobao.qimen.event.produce / taobao.qimen.events.produce接口对应的request如下所示:
QimenEventProduceRequest 、QimenEventsProduceRequest

taobao-sdk.zip

 

Q: 子订单已多包裹部分发货的状态下,是还可以无限追加包裹进行部分发货吗?

A: 是的,但是最多10次。

 

Q:构建拆单和合单情况下的ext参数?

A: 对接订单全链路的event.produce接口时,需要构建拆单和合单情况下的ext参数,我们提供了一个工具类来构建,提高大家的联调效率。
使用方式参考里面的main方法即可。

long_text_2023-03-06-16-15-25.txt

 

Q:发赠品现在不用传赠品的gift_item_id了么?

A: 是的,不用传gift的itemid了,目前没有消费场景,减少理解成本。

 

Q:为什么fullinfo接口不返回combine_item_info?

A:fileds需要填orders.combine_item_info

 

Q:系统有多次拆合单,需要怎么回传?

A:1)erp/wms一体化:在仓作业节点前回传;

2)erp-wms通过奇门对接:发货单创建时回传。

 

Q:如果订单在其他平台发货,交易接口无法获取已发货的订单信息?

A:二期会增加在其他平台已发货的交易信息。

 

Q:组合品不支持taobao.logistics.trace.search的物流详情信息查询?

A:可使用taobao.logistics.trace.get查询主单下全部包裹物详情。

 

更多FAQ请见汇总文档

 

FAQ

关于此文档暂时还没有FAQ
返回
顶部