来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 How can I upload values to the “value_id” and “original_value_name” fields when adding or updating products?
In summary:
- Attributes with "input_type": 3 (FREE_TEXT_FILED) only support user-defined values. Therefore, the uploaded "value_id" must be 0, and the "original_value_name" should be the value defined by the seller.
- For attributes with "input_type": 1 (SINGLE_DROP_DOWN) or "input_type": 4 (MULTI_DROP_DOWN), when adding/updating products, you can only upload the "value_id" from the "attribute_value_list".
- For attributes with "input_type": 2 (SINGLE_COMBO_BOX) or "input_type": 5 (MULTI_COMBO_BOX), you can upload either user-defined values or the "value_id" from the "attribute_value_list". When uploading a user-defined value, the "value_id" should be set to 0, and the "original_value_name" should be the value defined by the seller. When uploading a non-user-defined value, please select the "value_id" from the "attribute_value_list".
- Regardless of the attribute type, "value_id" must be uploaded. When uploading a user-defined value, "original_value_name" must also be provided.
- For attributes with "input_type": 5 (MULTI_COMBO_BOX) or "input_type": 4 (MULTI_DROP_DOWN), you can only upload up to 5 values for a single product.
- For attributes with "input_type": 3 (FREE_TEXT_FILED) and "input_validation_type": 4 (VALIDATOR_DATE_TYPE), when calling the "v2.product.add_item" API or the "v2.product.update_item" API, you should upload the value to the "original_value_name" field in Unix timestamp format.
- Regardless of the data type of the value, the "original_value_name" field must be uploaded as a string.
- The "value_unit" field is required only when "format_type" is 2 (FORMAT_QUANTITATIVE_WITH_UNIT) and a user-defined value is uploaded.
You can obtain the available attribute values for products through the following steps:
Step 1
Call the "v2.product.get_attribute_tree" API and upload the "category_id" of the product that you wish to add/update. The API will return a list of available attribute values for this product category.
Step 2
Based on the response, attributes with "mandatory": true are required, while attributes with "mandatory": false can be uploaded according to your needs. The "input_type" field indicates the type of the attribute, and different types of attributes correspond to different fields and values that need to be uploaded. Below, we will explain each case using the attribute values returned for “category_id”: 100578 as an example.
(1) For the attribute with "input_type": 1 (SINGLE_DROP_DOWN), you can upload only one "value_id", and this "value_id" can only be selected from the attribute list returned by the "v2.product.get_attribute_tree" API.
Partial response from the "v2.product.get_attribute_tree" API:
{
"attribute_id": 100408,
"mandatory": true,
"name": "Connection Type",
"attribute_value_list": [
{
"value_id": 2498,
"name": "Wired",
},
"attribute_info": {
"input_type": 1,
"input_validation_type": 0,
"format_type": 1,
"is_oem": false,
"support_search_value": false
}
The request that needs to be uploaded when adding/updating a product should be as follows:
"attribute_list": [
{
"attribute_id": 100408,
"attribute_value_list": [
{
"value_id": 2498
}
]
}
]
(2) For attributes with "input_type": 2 (SINGLE_COMBO_BOX), you can upload only one "value_id", and this "value_id" must be one of the values from the attribute list returned by the "v2.product.get_attribute_tree" API (please see Example 1 above) or a custom value. To upload a custom value, you must set "value_id" to 0 and provide the custom value in the "original_value_name" field.
Partial response from the "v2.product.get_attribute_tree" API:
{
"attribute_id": 100519,
"mandatory": true,
"name": "Earphone, Headphone, & Headset Type",
"attribute_value_list": [
{
"value_id": 2893,
"name": "Bone Conductor",
"multi_lang": [
{
"language": "zh-Hant",
"value": "骨傳導式"
}
]
}
],
"attribute_info": {
"input_type": 2,
"input_validation_type": 2,
"format_type": 1,
"is_oem": false,
"support_search_value": false
}
The request for uploading a custom value when adding/updating a product should be as follows:
"attribute_list": [
{
"attribute_id": 100519,
"attribute_value_list": [
{
"value_id": 0,
"original_value_name": "your customized name"
}
]
}
]
(3) For attributes with "input_type": 3 (FREE_TEXT_FIELD), you can upload only one "value_id", and you can enter a custom value. Therefore, you must upload "value_id": 0 and provide your custom value in the "original_value_name" field (please see Example 2 above).
(4) For attributes with "input_type": 4 (MULTI_DROP_DOWN), you can upload multiple "value_id" values, and these "value_id" values must be selected from the attribute list returned by the "v2.product.get_attribute_tree" API.
The request that needs to be uploaded when adding/updating a product should be as follows:
"attribute_list": [
{
"attribute_id": 100036,
"attribute_value_list": [
{
"value_id": 678
},
{
"value_id": 679
}
]
}
]
(5) For attributes with "input_type": 5 (MULTI_COMBO_BOX), you can upload multiple "value_id" values. You can select these "value_id" values from the attribute list returned by the "v2.product.get_attribute_tree" API, or set custom values.
Partial response from the "v2.product.get_attribute_tree" API:
{
"attribute_id": 100516,
"mandatory": false,
"name": "Audio Compatibility",
"attribute_value_list": [
{
"value_id": 2867,
"name": "Mobile",
"multi_lang": [
{
"language": "zh-Hant",
"value": "手機"
}
]
},
{
"value_id": 2903,
"name": "Others",
"multi_lang": [
{
"language": "zh-Hant",
"value": "其他"
}
]
}
],
"attribute_info": {
"input_type": 5,
"input_validation_type": 2,
"format_type": 1,
"max_value_count": 5,
"is_oem": false,
"support_search_value": false
}
The request that needs to be uploaded when adding/updating a product should be as follows:
"attribute_list": [
{
"attribute_id": 100516,
"attribute_value_list": [
{
"value_id": 0,
"original_value_name": "your customized name"
},
{
"value_id": 2867
}
]
}
]
(6) If attributes returned by the "v2.product.get_attribute_tree" API require a unit ("format_type": 2, FORMAT_QUANTITATIVE_WITH_UNIT), you must upload the value from the "attribute_unit_list" in the response of the "v2.product.get_attribute_tree" API to the "value_unit" field.
Partial response from the "v2.product.get_attribute_tree" API:
{
"attribute_id": 100323,
"mandatory": false,
"name": "Input Voltage",
"attribute_info": {
"input_type": 3,
"input_validation_type": 3,
"format_type": 2,
"attribute_unit_list": [
"V"
],
"is_oem": false,
"support_search_value": false
}
The request that needs to be uploaded when adding/updating a product should be as follows:
"attribute_list": [
{
"attribute_id": 100323,
"attribute_value_list": [
{
"value_id": 0,
"original_value_name": "your customized name"
"value_unit": "V"
}
]
}
]
(7) If attributes returned by the "v2.product.get_attribute_tree" API require a date ("input_validation_type": 4, VALIDATOR_DATE_TYPE), you must upload a Unix timestamp in the "original_value_name" field.
The request that needs to be uploaded when adding/updating a product should be as follows:
"attribute_list": [
{
"attribute_id": 100061,
"attribute_value_list": [
{
"value_id": 0,
"original_value_name": "1634526913"
}
]
}
]