[Important] 3PF PFF Shop Mode Support & 3PF Shop Upgrade

[Important] 3PF PFF Shop Mode Support & 3PF Shop Upgrade

尊敬的开发者，

您好，Shopee此前推出了本地化履约三方仓库模式 (即：3PF Shop)，本期将会进一步支持本地化履约三方仓库的一店多运模式 (即：3PF PFF Shop)，该模式支持卖家对单个店铺内的商品分别进行本地仓库库存和跨境仓库库存设置，本地仓库库存充足的情况下，将优先使用本地物流渠道进行履约，当本地仓库库存消耗完毕且该商品有跨境仓库库存时，将通过跨境小包模式进行履约，履约订单的API调用流程无变化。

具体更新如下：

1. 新字段对接

1. v2.shop.get_shop_info接口新增shop_fulfillment_flag字段，用于返回当前店铺的订单履约类型，目前包含以下类型：

2. v2.logistics.get_channel_list接口新增support_cross_border字段，用于说明当前物流渠道是本地物流渠道还是跨境物流渠道，若support_cross_border返回false，则说明当前物流渠道是本地物流渠道，若support_cross_border返回true，则说明当前物流渠道是跨境物流渠道。

3. v2.merchant.get_merchant_warehouse_location_list接口新增warehouse_name字段，用于返回卖家可用的仓库对应的仓库名称。

假如某CNSC卖家，merchant id 1包含以下店铺：

则接口返回如下：

说明：该接口返回该merchant下所有location_id和warehouse_name的对应关系，对于Normal CB Shop，更新库存时只需要更新到CNZ库存 (对CN卖家) 或 KRZ (对KR卖家)。

4. v2.product.get_item_base_info & v2.product.get_model_list接口新增if_saleable字段，用于说明当前location_id对应的库存是否可售，库存管理逻辑如下：

以上述merchant id 1为例，若创建MTSKU时，设置的Category/Attribute/Brand在MY, ID, SG, PH地区既可以作为本地商品销售也可以作为跨境商品销售时，并且设置库存为：

CNZ：500

MY001Z：400

ID001Z：300

MY002Z：200

SG001Z：100

将上述MTSKU发布至MY Shop 1, ID Shop 2, SG Shop 4, PH Shop 5后，则接口返回的库存值如下：

假设全球商品的库存合法值为0-1000，SG Shop 4设置了活动库存为200， 则更新全球商品库存时：

- CNZ+MY001Z+ID001Z+SG001Z库存总和需小于等于1000；

- CNZ+SG001Z库存需大于200。

后续，若卖家将MTSKU的Category修改为满足以下条件的Category：

- 在MY, SG, PH地区，只能作为跨境商品销售，不可作为本地商品销售；

- 在ID地区，既可以作为本地商品销售，也可以作为跨境商品销售。

MY, SG地区的本地仓库库存将会变为不可售状态，则接口返回的库存值如下：

2. 新接口对接

1. v2.merchant.get_merchant_warehouse_list

用于获取卖家可用的仓库列表以及仓库名称、地址、location_id等详细信息，接口设计参见文档 (注意：该文档仅供对接准备参考，最终版本请参见后续的上线公告与接口文档)。

注意：后续v2.merchant.get_merchant_warehouse_location_list接口将会下线，在v2.merchant.get_merchant_warehouse_list接口上线后，请尽快切换对接该接口。

2. v2.merchant.get_warehouse_eligible_shop_list

用于获取卖家仓库适用的店铺列表，接口设计参见文档 (注意：该文档仅供对接准备参考，最终版本请参见后续的上线公告与接口文档)。

3. 已有字段对接

对于3PF PFF Shop，可以通过v2.order.get_order_detail接口返回的product_location_id字段来判断订单是通过本地仓库履约或者跨境仓库履约。

以MY Shop3 为例：

该店铺产生的订单中，若product_location_id返回MY002Z，则该订单应该从本地仓库履约，若product_location_id返回CNZ，则该订单应该从跨境仓库履约。

请注意以下时间安排：

该项目中“v2.merchant.get_merchant_warehouse_location_list接口新增warehouse_name字段”部分已于2023年11月2日上线，其余接口改动将于2023年12月14日上线。由于2023年12月14日该项目整体上线后，location_id结构将会变更，不再是{shop_region}+Z格式的location_id，针对在同一地区有多个仓库的卖家，为了避免卖家无法准确识别location_id对应的仓库，从而无法管理商品库存的情况发生，请您尽快对接v2.merchant.get_merchant_warehouse_location_list接口的warehouse_name字段，并保证在2023年12月17日之前能够完成对接，感谢您的理解与配合。

字段、接口对接时间安排一览：

对接过程中遇到问题，提工单时请在标题中标注 - [3PF Developer 对接问题]，会有专属团队进行问题沟通。

Dear Developer,

Shopee previously launched 3PF Shop mode, this period will further support 3PF PFF Shop mode, which allows sellers to set up local warehouse stock and CB warehouse stock for products in a single shop. When the local warehouse stock of the product is sufficient, local logistics channels will be used first for fulfillment, and when the local warehouse stock of the product is exhausted and there is CB warehouse stock, then CB logistics channels will be used for fulfillment, the API call flow for fulfillment orders has no change.

The specific updates are:

1. New field integration

1. v2.shop.get_shop_info add shop_fulfillment_flag field to return the shop's order fulfillment type, and currently contains the following types:

2. v2.logistics.get_channel_list add support_cross_border field to indicate whether the logistics channel is local logistics channel or CB logistics channel, if support_cross_border returns false, it means the logistics channel is local logistics channel, and if support_cross_border returns true, it means the logistics channel is CB logistics channel.

3. v2.merchant.get_merchant_warehouse_location_list add warehouse_name field to return the warehouse name of the warehouse under the merchant.

If a CNSC seller, merchant id 1 contains the following shops:

Then the API response will be:

Note: This API returns the correspondence between all location_id and warehouse_name under the merchant. For Normal CB Shop, only need to update to CNZ location_id (for CN sellers) or KRZ location_id (for KR sellers) when updating stock.

4. v2.product.get_item_base_info & v2.product.get_model_list add if_saleable field to indicate whether the stock of current location_id is saleable or not, the logic is as follows:

Take the above merchant id 1 as an example, if the Category/Attribute/Brand set when creating MTSKU can be sold as both local and CB products in MY, ID, SG, and PH regions, and the stock is set:

CNZ：500

MY001Z：400

ID001Z：300

MY002Z：200

SG001Z：100

After publishing the above MTSKU to MY Shop 1, ID Shop 2, SG Shop 4, PH Shop 5, the stock will be:

Assuming that the stock limit of MTSKU is 0-1000, and SG Shop 4 has set the reserved stock to 200, when updating the stock of MTSKU:

- The sum stock of CNZ, MY001Z, ID001Z, SG001Z needs to be less than or equal to 1000;

- The sum stock of CNZ, SG001Z needs to be greater than 200.

Subsequently, if the seller modifies the Category of MTSKU to a Category that meets the following conditions:

- In MY, SG, PH regions, it can only be sold as CB products, not as local products;

- In ID region, it can be sold both as local products and CB products.

Then, the local warehouse stock in MY, SG regions will become unsaleable, and the stock will be:

2. New API integration

1. v2.merchant.get_merchant_warehouse_list

This API is used to get the seller's warehouse list and details such as warehouse name, address, location_id, etc, see this document for the API design (Note: This document is only for reference to prepare the integration, please refer to the subsequent announcement and API Reference for the final version).

Note: The v2.merchant.get_merchant_warehouse_location_list will be offline later, please switch to this new API as soon as possible after the v2.merchant.get_merchant_warehouse_list API releases.

2. v2.merchant.get_warehouse_eligible_shop_list

This API is used to get the eligible shop list of seller's warehouse, see this document for the API design (Note: This document is only for reference to prepare the integration, please refer to the subsequent announcement and API Reference for the final version).

3. Existing field integration

For 3PF PFF Shop, can determine whether the order should be fulfilled through local seller warehouse or CB seller warehouse by using the product_location_id field returned by the v2.order.get_order_detail.

Take MY Shop3 as an example:

For orders from this shop, if product_location_id returns MY002Z, then the order should be fulfilled from local seller warehouse, if product_location_id returns CNZ, then the order should be fulfilled from CB seller warehouse.

Please note the following timeline:

The "v2.merchant.get_merchant_warehouse_location_list add warehouse_name field" has been launched on November 2, 2023, and the remaining changes will be launched on December 14, 2023.

After December 14, 2023, the location_id format will be changed, it won’t be {shop_region}+Z format, for sellers with multiple warehouses in the same region, in order to prevent the seller from being unable to accurately identify the location_id corresponding warehouse, making it impossible to manage product stock, please integrate to the warehouse_name field of the v2.merchant.get_merchant_warehouse_location_list as soon as possible, and ensure that the integration can be completed before December 17, 2023. Thank you for your understanding and cooperation.

List of fields and API integration schedules:

If you encounter problems during the integration process, please add - [3PF Developer Integration Problems] in subject when raising ticket, and a dedicated team will reply.