来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 OpenAPI Updates for Escrow API and FBS Model Edit
Dear Developers,
Please notice the following API changes:
- To enhance payment flexibility, the BR region now supports using combined payment methods for a single order. This feature may be gradually expanded to other regions based on business needs.
We have introduced a new field, tenure_info_list, in the v2.payment.get_escrow_detail API.
When two payment methods are used, the payment_channel_name field will return the specific payment channel names.
The corresponding installment plan details will also be returned if installment payments are involved.
API Response Updates
For Orders Using Two Payment Methods:
{"buyer_payment_method": "Combined Payment", "buyer_payment_method_detail": "", "tenure_info_list": [ {"payment_channel_name": "Credit Card Installment", "instalment_plan": 1}, {"payment_channel_name": "Credit Card Installment", "instalment_plan": 3}]}
For Orders Using a Single Payment Method:
{"buyer_payment_method": "Pix",
"instalment_plan": "N/A", "tenure_info_list": [ {"instalment_plan": "N/A"}]}
Affected API: v2.payment.get_escrow_detail
Effective Date on Live: 2025.02.17
- We are introducing updates to the Fulfillment by Shopee (FBS) model edit in various OpenAPI endpoints.
- FBS Model Identification in Item and Model Queries
The following APIs now return the is_fulfillment_by_shopee flag to indicate whether a product or model is part of the FBS program:
v2.global_product.get_global_item_info
v2.product.get_item_base_info
Returns is_fulfillment_by_shopee = true for items with only FBS default models.
Returns is_fulfillment_by_shopee = false for items with non-FBS models or not single SKU product(only default model)
v2.product.get_model_list
v2.global_product.get_global_model_list
Returns is_fulfillment_by_shopee = true for FBS default models.
Returns is_fulfillment_by_shopee = false for non-FBS models.
The v2.product.init_tier_variation and v2.global_product.init_tier_variation APIs rules when modifying FBS model structures:
Model ID Validation
- Incorrect or non-existent model IDs will return an error.
- Only existing FBS models can be reused when switching from a one-tier to a two-tier structure.
- Switching from two-tier to one-tier with an FBS model ID is not allowed.
FBS Model Deletion Restrictions
- Deleting or partially modifying an FBS model list is not allowed and will return an error.
Handling Multiple Model IDs
- Duplicate model IDs in a one-tier structure will result in an error.
- Omitting required FBS model IDs in an update will return an error message.
Affected API:
v2.global_product.get_global_item_info
v2.product.get_model_list
v2.product.get_item_base_info
v2.global_product.get_global_model_list
v2.product.init_tier_variation
v2.global_product.init_tier_variation
Effective Date on Live: 2025.02.17
- The "GTIN" field will be mandatory for some of listing categories in BR.
v2.product.get_item_limit now includes "gtin_limit": {"gtin_validation_rule": "xxx"}, with possible values: "Mandatory", "Flexible", "Optional".
- Mandatory: This field is required and must contain a correctly formatted GTiN number.
- Flexible: This field is required and must contain either a correctly formatted GTlN number or "00" to declare that the item/model has no valid GTlN. - Optional: This field is optional and can contain a correctly formatted GTiN number, "00" or be omitted entirely.
When calling v2.product.add_item, v2.product.update_item, v2.product.init_tier_variation, v2.product.add_model, or v2.product.update_model, errors will be returned if the rule is not met.
Affected API:
v2.product.get_item_limit
v2.product.add_item
v2.product.update_item
v2.product.init_tier_variation
v2.product.add_model
v2.product.update_model
Effective Date on Live: 2025.02.13
尊敬的开发者，
请留意以下变更：
- 由于业务需求，BR地区支持一个订单使用两支付方式进行支付，后续会根据需求逐步开放至各个地区。
在接口 v2.payment.get_escrow_detail 新增字段：tenure_info_list，当使用两种支付方式，payment_channel_name 会返回具体的支付渠道名字。如果有分期付款，则会返回对应分期付款的信息
使用两种支付方式时，对应的接口返回参数如下：
"buyer_payment_method": "Combined Payment",
"buyer_payment_method_detail": "",
"tenure_info_list": [
{
"payment_channel_name": "Credit Card Installment",
"instalment_plan": 1
},
{
"payment_channel_name": "Credit Card Installment",
"instalment_plan": 3
}
]
}
},
使用一种支付方式时，对应接口返回如下：
"buyer_payment_method": "Pix",
"instalment_plan": "N/A",
"tenure_info_list": [
{
"instalment_plan": "N/A"
}
]
},
影响接口：v2.payment.get_escrow_detail
上线时间: 2025.02.17
- 支持了对 FBS model 通过 OpenAPI 进行编辑
1）以下 API 现在会返回 is_fulfillment_by_shopee 标志，以指示某个商品或 model 是否属于 FBS：
v2.global_product.get_global_item_info
v2.product.get_item_base_info
对于仅包含 FBS 默认 model 的商品，返回 is_fulfillment_by_shopee = true。 对于包含非 FBS model 或者非单 SKU 商品（仅默认 model）的商品，返回 is_fulfillment_by_shopee = false。
v2.product.get_model_list
v2.global_product.get_global_model_list
对于 FBS 默认 model，返回 is_fulfillment_by_shopee = true。 对于非 FBS model，返回 is_fulfillment_by_shopee = false。
2）v2.product.init_tier_variation 和 v2.global_product.init_tier_variation API 对 FBS model 编辑的规则：
model ID 验证
- 传入错误或不存在的 model ID 将返回错误信息。
- 仅支持使用现有的 FBS model ID 进行从单层model到双层model的转换。
- 不允许从双层规格转换为单层规格（如果涉及 FBS model ID）。
FBS model 删除限制
- 禁止删除或部分修改 FBS model列表，违规则返回错误。
多 model ID 处理
- 在单层规格结构中重复传入相同的 model ID 将返回错误。
- 在更新时遗漏必须包含的 FBS model ID 将返回错误信息。
- 在部分 BR 地区的商品类目中，GTIN（全球贸易项目编号）字段将成为必填项
- v2.product.get_item_limit 现已新增字段 "gtin_limit": {"gtin_validation_rule": "xxx"}， 其中 gtin_validation_rule 可能的取值如下：
Mandatory（必填）：必须填写 GTIN，并且格式必须正确。
Flexible（灵活）：必须填写 GTIN，可以填写正确格式的 GTIN，或者填写 "00" 以声明该商品/规格无有效 GTIN。
Optional（可选）：可填写正确格式的 GTIN，或 "00"，或不填写
- API 调用影响
如果 GTIN 字段未满足对应规则，在调用以下 API 时将返回错误：v2.product.add_item，v2.product.update_item，v2.product.init_tier_variation，v2.product.add_model，v2.product.update_model
影响接口:
v2.product.get_item_limit
v2.product.add_item
v2.product.update_item
v2.product.init_tier_variation
v2.product.add_model
v2.product.update_model
上线日期: 2025.02.13