本文介绍LinkedMall API V2.0商品类接口对接最佳实践。
一、概述
LinkedMall API为分销商提供了一系列商品相关接口和消息，分销商可通过合理调用各接口和商品消息消费，实现商品的同步、查询等功能。
本文档旨在规范接口调用的流程并提示相关注意事项，以协助分销商避免不合理调用接口导致的问题，从而提升系统的稳定性和可靠性。文档通过四个典型场景阐明如何正确使用接口。
分销商在系统设计和调用接口时，还应充分考虑各接口QPS限制，详情请参考LinkedMall API V2.0 接口QPS限制说明。
二、典型场景说明
场景1：商品同步并回流
说明
商品同步是指将商品信息从一个系统同步到另一个系统，并将同步结果回流。通常用于系统间的数据初始化或不定期更新。
典型业务场景
典型业务场景 | 场景说明 | 相关接口 | 相关消息 |
首次获取全量商品（商品初始化） | 分销商完成入驻和店铺开通后，渠道商将为分销商完成商品铺货。 铺货完成后，分销商可通过调用查询商品池选品列表接口逐页获取全量商品。 说明
| 无 | |
业务正常运维阶段的增量商品获取（不定期更新） | 完成Kafka消息对接后，建议分销商及时消费商品创建消息获取增量商品。 | 无 | |
业务正常运维阶段的商品信息更新（不定期更新） | 完成Kafka消息对接后，建议分销商及时消费商品各类消息，以完成商品信息、状态等更新。 | 无 | 各商品类信息 |
商品按页查询 | 分销商自建商品管理后台中，如需按页查询商品，可调用查询商品池选品列表接口指定查询页获取商品信息。 | 无 |
注意事项
确保调用接口时的参数完整性和准确性，避免因参数错误导致数据缺失。
应及时消费商品各类消息，以正确获得增量商品及商品状态等更新。
场景2：搜索接口同步商品并回流
说明
通过搜索接口同步商品信息并回流，适用于根据特定条件动态获取商品数据的场景。
LinkedMall分销商控制台提供了商品筛选和商品出库、入库功能，分销商也可以通过控制台进行操作，请参考控制台说明文档分销商选品。
如分销商自建商品管理后台需集成商品筛选和商品出库、入库功能，请参考下文典型业务场景中的内容。
商品出库、入库功能，目前仅开放给已加白（2025年1月1日（含）后入驻的）分销商。未加白（2025年1月1日前入驻的）的分销商可忽略此功能和商品信息中的商品出入库状态字段inGroup。详情请咨询LinkedMall技术支持小二。
典型业务场景
典型业务场景 | 场景说明 | 相关接口 | 相关消息 |
按条件筛选或搜索指定商品 | 商品搜索接口提供与分销商控制台商品管理模块一致的筛选与搜索能力。 分销商如有自建商品管理后台，可调用接口实现筛选或搜索符合接口入参条件的商品。 说明 非按条件筛选或搜索商品场景时的商品分页查询，建议使用查询商品池选品列表接口。 | 无 | |
按条件筛选或搜索指定商品后完成商品出库、入库 |
说明 分销商在LinkedMall分销商控制台进行出库、入库操作后，如需同步商品出入库状态，请及时消费商品出库消息和商品入库消息。 |
注意事项
搜索条件的准确性对结果至关重要，确保搜索参数的合理性和完整性。
目前，商品出入库功能及消息等，仅适用于已加白（2025年1月1日（含）后入驻的）出入库功能的分销商，请参考下表。
功能
加白分销伙伴
未加白分销伙伴
优化后的商品消息发送策略
遵循新策略（参考下一张表格）
全量发送和消费
商品出库、入库接口
需对接或在控制台操作出入库
出入库操作不生效
商品出库、入库消息
需及时消费
需忽略
商品出入库状态inGroup字段
需关注或处理
需忽略
LinkedMall系统针对已入库和未入库（已出库）的商品采用不同的商品消息发送和策略。详情请参考下表。
重要商品出库、入库功能，目前仅开放给部分已加白（2025年1月1日（含）后入驻的）分销商。未加白（2025年1月1日前入驻的）的分销商的全类商品消息均会发送（可忽略下表）。详情请咨询LinkedMall技术支持小二。
消息
未入库商品是否发送
已入库商品是否发送
是
是
是
是
否
是
是
是
是
是
是
是
否
是
是
是
是
是
是
是
否
是
是
是
场景3：购物车商品列表展示场景
说明
电商业务通常需要配置购物车模块。当买家加购商品后，商品进入购物车商品列表。
典型业务场景
典型业务场景 | 场景说明 | 相关接口 | 相关消息 |
购物车商品列表信息展示 | 当买家进入购物车查看商品列表时，需要购物车呈现所加购的商品的可售状态等，此时分销商可调用批量查询选品池SKU销售信息接口批量查询商品的SKU销售信息。 说明
| 无 |
注意事项
确保购物车中的SKUID准确无误，避免查询到错误的商品信息。
如需按买家收货地址查询对应区域是否可售，需在调用接口时传入
divisionCode字段。
场景4：商详展示和导购展示场景
说明
商详与导购场景是指业务根据用户的需求推荐商品，通常需要查询商品详情和售卖信息。
典型业务场景
典型业务场景 | 场景说明 | 相关接口 | 相关消息 |
导购场景下的商品状态等信息查询 | 电商业务中的导购场景如首页瀑布流等，通常需要在加载商品前获取商品可售状态等信息，分销商可调用查询选品池商品销售信息接口进行查询 | 无 | |
商详展示 |
| 各商品类信息 |
注意事项
导购场景中，商品推荐的准确性依赖于商品详情和售卖信息的完整性，确保接口调用时参数正确。
如需查询商品在指定区域是否可售，调用接口时需传入
divisionCode参数。
三、商品接口及消息介绍
四、商品域部分重要字段和结构体说明
字段或结构体名 | 说明 | 存在结构体 | 关联接口或消息 |
| SKU和商品规格值别名。当 | ||
| SKU标题。建议分销商取 SkuSpec 结构体中的 | ||
skuAlias | SKU备注说明。作为SKU的补充说明，可补充在拼接完成的SKU标题后展示。 | ||
商品限购规则。 | - | ||
商品扩展属性。包含了商品购买倍数、品牌Logo、商品导购标题等扩展属性内容。 | - |