# 商品管理

# 开发前准备

• 权限与凭证：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对权限集 ID：129的授权，使用 authorizer_access_token
• 消息推送配置：需配置消息推送回调 URL（配置一次即可接收所有事件回调）。商品管理涉及的事件：[事件] 商品审核 / product_spu_audit、[事件] 商品上下架 / product_spu_listing、[事件] 商品更新 / product_spu_update。详见 消息通知（回调）说明

# 商品数据模型

商品存在草稿数据和线上数据两份数据，理解这个模型是使用商品管理接口的前提。

# 两份数据的关系

调用 [API] 添加商品 / addproduct 和 [API] 更新商品 / updateproduct 修改的都是草稿数据，只有审核通过并上架后，草稿数据才会覆盖线上数据正式生效。

# 两份数据对比

# 草稿状态（edit_status）

# 线上状态（status）

# 查询数据时如何区分

通过 [API] 获取商品 / getproduct 的 data_type 参数控制：

从未上架过的商品没有线上数据，data_type=1 或 3 时不会返回 product 字段。

# 接入流程

# 阶段一：商品发品流程

发品流程分为前置准备、数据组装、提交审核上架三个环节。

# 1-1 前置准备：资质配置、校验与获取发布规则

发品前需完成运费模板、退货地址、品牌资质、类目权限的申请，然后进行发品前校验并获取发布规则。

以上接口分属类目管理、物流发货、品牌资质等模块，产出的 ID 将在 [API] 添加商品 / addproduct 中使用：

• template_id → express_info 参数
• address_id → after_sale_info 参数
• brand_id → brand_id 参数
• cat_id → cats 参数

[API] 发品前校验 / categoryprecheck 用于校验店铺和类目权限；校验通过后，调用 [API] 获取类目下商品发布规则 / getcategoryproductrule 获取类目的发布规则（product_attr_list、sale_attr_list、product_qua_list、size_chart、floor_price 等），用于动态构建商品发布表单。

# 1-2 数据组装：获取发品所需数据

# 1-3 数据组装：属性映射（ISV/跨平台场景）

此步骤主要面向 ISV 服务商或跨平台搬品场景，自研商家直接填写属性即可跳过。

# 1-4 提交发品与审核上架

[API] 添加商品 / addproduct 提交后商品进入审核，通过 [事件] 商品审核 / product_spu_audit 事件通知获取审核结果。审核通过后需主动调用 [API] 上架商品 / listingproduct 上架（也可通过 [API] 设置商品上架策略 / setproductauditstrategy 配置审核通过后自动上架）。审核不通过时，可通过 [API] 获取商品 / getproduct 查看 audit_info 中的审核原因。

# 阶段二：商品日常管理流程

# 2-1 商品信息更新

商品更新有两个接口，作用于不同的数据层：

两个更新接口的区别：

# 2-2 商品上下架与删除

下架后商品进入「未上架」状态，可重新上架。商品开售/取消开售用于控制定时上架场景。[事件] 商品上下架 / product_spu_listing 会推送上下架状态变更（status: 5-上架, 11-自主下架, 13-系统下架）。

# 2-3 商品查询与提审管理

# 阶段三：库存管理流程

库存管理涉及通用库存和区域仓库库存两套体系，内容较复杂，已独立整理到库存管理开发指南中。

详见：库存管理 - 开发指南

# 阶段四：赠品与买赠活动流程

# 4-1 添加非卖商品（赠品）

非卖商品的类目必须在 [API] 获取所有类目 / getallcategory 返回的可用范围内，超出范围的类目不支持添加为非卖商品。

# 4-2 在售商品转赠品 + 赠品管理

同一个在售商品只能被设置为一次非卖商品（转换不可重复）。

# 4-3 买赠活动管理

gift_id 对应的是非卖商品的 product_id（通过 [API] 添加非卖商品 / addgiftproduct 或 [API] 在售商品转赠品 / setproductasgift 获得）。

# 阶段五：限时抢购流程

# 商品状态流转

[API] 免审更新商品 / updateproductauditfree 直接更新线上数据，不改变商品状态。

# 状态流转操作对照表

审核通过后需主动调用 [API] 上架商品 / listingproduct 上架，或通过 [API] 设置商品上架策略 / setproductauditstrategy 设置自动上架。状态变更通过 3 个事件通知推送：[事件] 商品审核 / product_spu_audit、[事件] 商品上下架 / product_spu_listing、[事件] 商品更新 / product_spu_update。

# 前端对接说明

# 接口全览

# 必接接口

# API 接口

# 事件通知

# 全量接口

商品管理共 40 个 API 接口（商品 23 + 库存 4 + 赠品 6 + 买赠活动 3 + 限时抢购 4），完整列表请查看官方文档：

• 商品管理 API 接口全量列表
• 商品管理事件通知

# 相关运营文档

• 详见成长中心：商品上架指引
• 详见成长中心：申请类目
• 详见成长中心：商品SKU设置搜推运营指南
• 详见成长中心：避免虚假夸大宣传
• 详见成长中心：避免低价SKU引流

# 常见问题 FAQ

Q：调用 [API] 添加商品 / addproduct 提示需要开通运费险？ A：[API] 发品前校验 / categoryprecheck 返回 all_pass: true 代表店铺层面已开通运费险，但发品时还需在商品维度打开运费险开关。