[Action Required - Shopee Open API] Sandbox Testing for Category Tree Adjustment

Hi Developer,

To ensure that you can be fully prepared and have enough time to adjust your category mapping logic, we have provided the new global category tree data in the Sandbox environment for your testing. This will be available from 6 Dec 2021 onwards for both OpenAPI v1 and v2 APIs.

The scheduled rollout to the Live environment will be 19 January 2022 for the Brazil site.

What to expect:

• The new category and attribute data can be extracted by GetCategories and GetAttribute APIs in the sandbox environment.
• All APIs that take category_id as request param need to request with leaf node category_id.
• More mandatory attributes will be added.

a. For new listing creation, all mandatory attributes are required.

b. For existing listing updates, there will be a transition period allowing for listings to be updated without filling in all the missing mandatory attributes. (Exception: if you update category_id for an existing listing, all mandatory attributes of the new category_id should be included.)

• Parent-child structure will be introduced at the attribute level.

There are three types of parent-child attribute structure:

1. parent(mandatory*) - child(mandatory)

2. parent(mandatory) - child(optional)

3. parent(optional) - child(optional)

*Mandatory from “is_mandatory” field in GetAttributes API

For Types 1 and 2, creating new listings will require the mandatory attributes.

For Type 3, you can use only parent or parent-child for new listings.

One child can have multiple parents, and it only needs one parent in the request for creating new listings.

Currently, all parent-child relationships are set up using Type 3.

• For OpenAPI 2.0, the brand field will be extracted from regular attributes and each brand will have a unique brand_id. For existing listings with unrecognised brand by Shopee and no valid brand_id assigned to it, the unrecognised brand will be wiped out and the listings will be considered as “no brand”.
• For OpenAPI 2.0, the attribute value_id will have a valid value instead of 0.
• New APIs for OpenAPI 2.0:

a. v2.product.search_item for searching attributes-missing listing.

b. v2.product.category_recommend for global category recommendation based on listing name.

How to test the new global category tree in Sandbox:

Refer to step 5 in the user guide to learn more about the Sandbox environment.

1. Main test cases for OpenAPI 1.0 developers:

1. Retrieve the new global category tree data in Sandbox by GetCategories and GetAttribute APIs.

2. Use the retrieved category_id, attribute_id and other necessary info to call item.Add and item.Update.

3. Based on the upload and update result, call GetItemDetail to verify.

Note: There is no parent-child structure indicator field in v1. If it is Type 3 structure and you only include the child but not parent, it will fail.

Additional cases:

1. Call GetCategoryByCountry to retrieve category_id to verify categories are the same across different markets.

2. Call GetRecommendCats to retrieve category_id based on the listing name.

2. Main test cases for OpenAPI 2.0 developers:

1. Retrieve the new global category tree category_id in Sandbox by product.get_category.

2. Call product.get_brand_list to retrieve the brand_id.

3. Call product.get_dts_limit to retrieve the days-to-ship limit details.

4. Call product.get_attributes to retrieve the attribtue_id, value_id and parent-child structure details.

5. Use applicable category_id, attribute_id, value_id and brand_id to call product.add_item to create new listings.

6. Use category_id to call product.support_size_chart to check if size chart is supported for this category.

7. Call product.update_size_chart with the applicable category_id to upload size chart.

Additional cases:

1. Call product.search_item to find listings that are missing mandatory or optional attributes after the new global category tree is released.

2. Call product.category_recommend to retrieve recommended category_id based on listing names.

For more details on the v2 test case call flow, please check here.

开发者您好：

为确保您有足够的时间调整类目映射关系，我们在沙盒环境中提供了新的类目结构数据供您测试。 从2021年12月06日开始，通过Open API 1.0 和 2.0 的相关接口都可以使用此功能。

新的类目结构预计将于2022年1月19日更新至巴西线上环境。

请注意:

• 在新的类目结构上线前，线上环境与沙盒环境的类目/属性是不相同的。线上仍是旧的类目结构，沙盒则是新的类目结构。

更新说明：

• 在沙盒环境中，通过 GetCategories 与 GetAttributes 接口分别可以获取新的类目结构与商品属性。
• 对于需要入参 category_id 的接口，需要使用叶节点（leaf node）的 category_id。
• 新增更多必填属性。

a. 对于新增商品，入参时必须包括所有必填属性。

b. 对于存量商品的更新，在过渡期内，允许入参不包含必填属性进行更新商品信息。（例外，若您要更新存量商品的category_id，则入参时必须包括所有必填属性。）

• 部分商品属性引入父子结构。

属性的父子结构有以下三种类型：

1. 父（必填*）- 子（必填）

2. 父（必填）- 子（选填）

3. 父（选填）- 子（选填）

*请注意，通过 GetAttributes 接口的 is_mandatory 字段可以获取属性是否为必填

对于属性为类型1和 2，新增商品时需要入参必填属性。

对于属性为类型3，新增商品时可以入参父属性，或同时入参父子属性，但不能只入参子属性。

一个子属性可能拥有多个父属性，新增商品时，只需入参任一父属性即可。

目前，所有父子结构皆为类型3。

• 对于Open API 2.0，品牌字段（brand）将会从常规属性中移除，每一个品牌都有独立的 brand_id。若存量商品的品牌未通过Shopee审核且没有有效的 brand_id，品牌信息将会被清理并显示“No Brand”
• 属性值（attribute value）会有独立的 value id，Open API 2.0会返回有效的 value_id，且返回的 value_id 不会为 0。
• OpenAPI 2.0 新增的接口：

a. v2.product.search_item：用以搜索缺失商品属性的商品

b. v2.product.category_recommend：可以根据商品标题为商品推荐合适的新类目（category_id）

如何在沙盒中测试新的类目结构：

请先参考 Developer Guide 中的 Step 5: Test API in Sandbox 查看更多关于沙盒环境的信息。

1）OpenAPI 1.0 开发者的主要测试案例

1. 通过 GetCategories 和 GetAttributes 接口获取沙盒环境中的新类目结构下的类目（category_id）以及属性信息（attribute_id）。

2. 利用案例 1 获取的 category_id，attribute_id 以及其他必要信息，分别通过item.Add 和 item.Update 接口来新增和更新商品。

3. 通过 GetItemDetail 接口验证商品的信息与案例 2 新增和更新商品所使用的信息是否一致。

注意：OpenAPI 1.0不会返回属性的父子结构关系。若属性的父子结构为类型3，仅使用子属性且不包含其父属性去新增或更新商品时，将会失败。

其他案例：

1. 调用 GetCategoryByCountry 接口以获取 category_id，验证各个市场所使用的类目结构是否相同。

2. 利用商品标题调用 GetRecommendCats 接口为商品推荐合适的类目（category_id）。

2）OpenAPI 2.0 开发者的主要测试案例：

1. 调用 product.get_category 接口来获取沙盒中新类目结构下 的 category_id 。

2. 调用 product.get_brand_list 接口来获取 brand_id 。

3. 调用 product.get_dts_limit 接口来获取类目的 days-to-ship 信息。

4. 调用 product.get_attributes 接口来获取 attribtue_id，value_id 和属性父子结构信息。

5. 利用适用的 category_id，attribute_id，value_id 和 brand_id 调用 product.add_item 接口来新建商品。

6. 利用 category_id 调用 product.support_size_chart 接口来检查该类目是否支持上传尺寸表。

7. 利用案例 6 获取的 category_id 调用 product.update_size_chart 上传尺寸表。

其他案例：

1. 调用 product.search_item 接口来查询缺失必填和选填属性的商品。

2. 调用 product.category_recommend 根据商品标题为商品推荐合适的类目（category_id）。

关于OpenAPI 2.0的调用细节，请参考API请求流程图。