首公里发货预报

Shopee 为中国大陆和韩国跨境卖家提供首公里大包绑定订单功能，用于平台订单的首公里到仓跟踪

跨境发货首公里定义：从卖家仓库发往 Shopee 境内转运仓的阶段，详情可参考：（1）订单发货预报——首公里；（2）首公里快递寄送（平台下单）

3.1 Pick Up / Drop Off / Self Delivery 模式

针对Pick up，Drop off，Self Delivery 模式，可以通过如下接口调用流程进行订单首公里预报：

开发者可通过v2.first_mile.get_channel_list接口获取首公里发货预报的渠道列表以及对应渠道所支持的发货方式，所有渠道均在此接口中返回

3.1.1 Pick up 与 Self Delivery 模式绑定

• 第一步：通过v2.first_mile.generate_first_mile_tracking_number接口生成首公里追踪号，v2.first_mile.get_tracking_number_list接口可用于查询生成的首公里追踪号列表
• 第二步：v2.first_mile.get_unbind_order_list接口查询待绑定首公里追踪号的订单列表，并通过v2.first_mile.bind_first_mile_tracking_number接口进行绑定 (Sellf Delivery 模式下 shipment_method 传 self-deliver，logistics_channel_id传空)；v2.first_mile.get_detail 可用于查询首公里追踪号详情
• 第三步：调用v2.first_mile.get_waybill接口打印大包标签

3.1.2 Drop off 模式绑定 (会逐步下线)

• 第一步：卖家线下获取渠道追踪号
• 第二步：通过v2.first_mile.get_unbind_order_list接口获取待绑定首公里追踪号的订单列表，并通过v2.first_mile.bind_first_mile_tracking_number接口进行绑定，v2.first_mile.get detail接口可用于查询首公里追踪号详情

接口清单如下：

3.2 Courier Delivery 模式

针对 Courier Delivery 模式，可以通过如下接口调用流程进行订单首公里预报：

针对快递寄送 (平台下单) 共有 2 种下单模式，开发者可通过v2.first_mile.get_courier_delivery_channel_list 获取不同模式下的快递公司及服务：

• 1010003: kuaidi100 to C - 直接预约快递上门，卖家自行与快递公司线下结算
• 1010004: kuaidi100 prepaid(MP) - 月结账号结算，使用卖家在卖家中心设置的快递公司月结账号下快递单，与快递公司进行线上结算

注意：快递公司与对应服务都是全平台统一，与店铺、商家无关

寄件地址获取:

通过v2.logistics.get_address_list获取卖家设置首公里取件地址（address_type 为 FIRST_MILE_PICKUP_ADDRESS）

注意：卖家不同店铺可以在卖家中心设置不同的地址

收件地址获取：

通过v2.first_mile.get_transit_warehouse_list获取包裹送达转运仓地址

注意：Shopee 转运仓信息都是全平台统一，与店铺、商家无关

3.2.1 Prepaid Account 月结模式

• 第一步：通过v2.merchant.get_merchant_prepaid_account_list获取卖家设置的月结账号，一个月结账号对应一个快递公司，可通过prepaid_account_courier_name 字段来与首公里快递公司匹配。注意：在一个商家维度下月结账号是一样的
• 第二步：通过v2.first_mile.generate_and_bind_first_mile_tracking_number给快递公司下单
• 第三步：下单成功，可通过 v2.first_mile.get_courier_delivery_waybill 获取可打印的快递面单

3.2.2 Payment Offline 线下结算模式

• 直接通过v2.first_mile.generate_and_bind_first_mile_tracking_number给快递公司下单，预约上门取件。注意：此模式下“prepaid_account_id”不用传值

3.2.3 绑定与解绑

• 订单增绑先通过v2.first_mile.get_courier_delivery_tracking_number_list获取binding ID；然后通过v2.first_mile.bind_courier_delivery_first_mile_tracking_number 在已下单快递单上增加订单包裹。注意：快递包裹状态为 PICKED_UP 之后无法操作
• 跨店铺绑定第一步：通过v2.first_mile.generate_and_bind_first_mile_tracking_number下单。注意：单次下单必须是同一店铺订单第二步：通过v2.first_mile.get_courier_delivery_tracking_number_list获取binding ID第三步：通过v2.first_mile.bind_courier_delivery_first_mile_tracking_number进行增绑订单。注意：若进行跨店铺绑定，只会使用新建下单的那个店铺的寄件地址与对应选择的月结账号。
• 订单解绑使用 v2.first_mile.unbind_first_mile_tracking_number_all 解除订单包裹与快递单的绑定。注意：快递包裹状态为 PICKED_UP 后无法操作

接口清单如下：

4.1 Pick up，Drop off，Self Delivery 模式

首公里跟踪号 (Binding ID) 状态：

• ORDER_RECEIVED：绑定成功
• PICKED_UP：已取件
• DELIVERED：派送成功

4.2 Courier Delivery 模式

由于快递单号的生成有延迟，需查询状态判断是否下单成功，轮询调用v2.first_mile.get_courier_delivery_detai获取状态：

注意：若状态为 CANCELED，可通过调用v2.first_mile.get_courier_delivery_tracking_number_list接口，查看“reason”字段值获取失败原因

5.1 Pick up，Drop off，Self Delivery 模式

Q：针对一个首公里追踪号，是否允许跨店铺绑定订单？

A：允许，但是要确保跨店铺的订单使用同一个转运仓。由于API有鉴权机制，在调用v2.first_mile.bind_first_mile_tracking_number接口时，一次调用只能传一个店铺的订单，所以请确保每次调用，order_sn和shop_id是匹配的。

Q：绑定成功后，订单状态是否会发生变化？

A：会的，绑定大包成功后，被扫描后，被绑定的所有订单的订单状态会从PROCESSED更新至SHIPPED。

Q：应该先将订单发货和打印面单还是应该先绑定首公里？

A：正确的顺序是先操作发货， 然后打印面单，再绑定首公里追踪号。

Q：如何查询订单的首公里追踪号？

A：可通过v2.logistics.get_tracking_number接口新增入参 response_optional_fields: first_mile_tracking_number查询订单首公里追踪号。

Q：什么首公里追踪号状态下可以绑定订单？

A：通过v2.first_mile.get_detail查询首公里追踪号状态。

若ship_method是pick up：

• 首公里追踪号刚生成时，状态为NOT_AVAILABLE，可以绑定订单；
• 首公里追踪号状态为ORDER_RECEIVED说明已经有其他订单绑定过该首公里追踪号，仍然可以继续绑定；
• 首公里追踪号状态为PICKED_UP说明首公里大包裹已经被渠道揽收，不可以再绑定订单；
• 首公里追踪号状态为DELIVERED说明首公里大包裹已经抵达转运仓，不可以再绑定订单。

若ship_method是drop off或者self deliver：则无状态限制。

Q：自送物流是否仍需要调用接口进行绑定？

A：需要，自送物流是用户的线下行为，但是仍需要调用v2.first_mile.bind_first_mile_tracking_number进行首公里发货预报。

Q：什么状态下可以将订单解绑首公里跟踪号？

A：若ship_method是pick up，则仅有首公里状态为ORDER_RECEIVED时，可以解绑；若ship_method是drop off或者self deliver，则无状态限制。

5.2 Courier Delivery 模式

Q：v2.first_mile.generate_and_bind_first_mile_tracking_number无法传跨店铺订单

A：如需跨店铺绑定，请按以下流程操作：

• 先通过 v2.first_mile.generate_and_bind_first_mile_tracking_number 为其中一个店铺的订单下单。
• 调用 v2.first_mile.get_courier_delivery_tracking_number_list 获取对应的 binding ID。
• 调用 v2.first_mile.bind_courier_delivery_first_mile_tracking_number 增绑其他店铺订单。

注意：跨店铺绑定时，寄件地址及月结账号将以首次新建下单的店铺及其所选月结账号为准。

Q：月结模式下单失败，提示月结相关错误如何处理

A：需要提示卖家前往卖家中心进行正确的月结账号配置，或与快递公司确认月结账号是否正确

Q：首公里下单失败订单是否需要解绑后再处理

A：不需要，重新进行绑定操作下单即可

Q：首公里下单成功，状态是“NOT_AVAILABLE”

A：快递单号是异步获取，需要多次调用v2.first_mile.get_courier_delivery_detai获取最终状态