youzan-datahub/docs/餐饮零售数据中台/4.有赞云接口对应表.md

# 餐饮零售数据中台 V2.0 - 有赞云接口对应表（能力包维度）

**文档版本：** V1.0  
**说明：** 本表基于“能力包名称”整理，不使用未验证的具体接口方法名。待在控制台确认“能力包详情页的字段/接口清单”后，再补齐字段映射。

---

## 一、交易与售后域（订单净额与复购口径）

| 能力包名称 | 核心接口 (API) | 权限状态 | 用途 | 关键字段（待确认） |
|---|---|---|---|---|
| 订单同步 | `youzan.trades.sold.get` | 已获得 | 订单主表与明细拉取，构建销售事实表 | 订单号 (`tid`), 支付时间 (`pay_time`), 实付金额 (`pay_info.payment`), 订单状态 (`status`), 用户 (`buyer_info.buyer_phone`, `buyer_info.yz_open_id`), 明细列表 (`orders` 包含 `sku_id`, `num`, `price`) |
| 售后单同步 | `youzan.trade.refund.search` | 已获得 | 退款/退货列表与详情，用于净额口径 | 售后单号 (`refund_id`), 关联订单 (`tid`), 退款金额 (`refund_fee`), 退款状态 (`status`) |
| 售后单审核处理 | `youzan.trade.refund.agree` / `reject` | 已获得 | 售后状态变化的最终一致性 | 售后单状态 (`status`), 处理时间 (`updated_time`) |
| 网店仅退款 | `youzan.trade.refund.search` | 已获得 | 网店退款数据补充 | 售后单号 (`refund_id`), 金额 (`refund_fee`), 原因 (`reason`) |
| 网店退货退款 | `youzan.trade.refund.search` | 已获得 | 网店退货退款数据补充 | 退货单号 (`refund_id`), 金额 (`refund_fee`) |
| 门店仅退款基于有赞POS | `youzan.trade.refund.search` | 已获得 | 门店退款数据补充 | 门店ID (`offline_id`), 售后单号 (`refund_id`), 金额 (`refund_fee`) |
| 门店退货退款基于有赞POS | `youzan.trade.refund.search` | 已获得 | 门店退货退款数据补充 | 门店ID (`offline_id`), 售后单号 (`refund_id`), 金额 (`refund_fee`) |

**口径建议：**  
- 销售额以“支付成功订单金额 - 完成退款金额”为净额。  
- 退款/退货必须与订单明细关联，避免SKU动销失真。

---

## 二、商品与SKU域（商品洞察基础）

| 能力包名称 | 核心接口 (API) | 权限状态 | 用途 | 关键字段（待确认） |
|---|---|---|---|---|
| 商品查询 | `youzan.item.search`, `youzan.item.detail` | 已获得 | 商品与SKU基础信息 | 商品ID (`item_id`), SKU ID (`sku_id`), 外部编码 (`outer_id`, `outer_item_id`), 名称 (`title`), 售价 (`price`) |
| 商品更新 | `youzan.item.update` | 已获得 | 未来可选：打折标识或状态调整 | 商品ID (`item_id`), 价格 (`price`), 状态 (`is_listing`) |
| 上下架商品 | `youzan.item.update.listing` | 已获得 | 上下架策略执行 | 商品ID (`item_id`), 上下架状态 |
| 商品分组 | `youzan.itemcategories.get` | 已获得 | 运营分组维度 | 分组ID (`group_id`), 分组名称 (`group_name`) |
| 商品标准 | `youzan.item.standard.search` | 已获得 | 标准化信息辅助归类 | 标准ID, 标准名称 |
| 门店商品管理 | `youzan.multistore.goods.sku.search` | 已获得 | 门店维度商品归属 | 门店ID (`kdt_id`/`offline_id`), 商品ID (`item_id`) |
| 店铺商品上下架到网点 | `youzan.multistore.goods.listing` | 已获得 | 网点商品状态 | 网点ID (`offline_id`), 商品ID, 状态 |
| 多网点商品关联配送方式 | `youzan.multistore.goods.delivery` | 已获得 | 配送方式区分热食/冷链 | 网点ID (`offline_id`), 配送方式 (`delivery_template_id`) |

**口径建议：**  
- 使用“商家外部编码/自定义字段”建立热食与冷链SKU的统一映射（若有）。  
- 若无统一编码，需人工维护“SKU映射表”。

---

## 三、客户与会员域（客户洞察基础）

| 能力包名称 | 核心接口 (API) | 权限状态 | 用途 | 关键字段（待确认） |
|---|---|---|---|---|
| 店铺客户信息同步 | `youzan.users.info.query`, `scrm.customer.get` | 已获得 | 客户主数据 | 有赞账户ID (`yz_open_id`/`buyer_id`), 手机号 (`mobile`), 注册时间 (`created_at`) |
| 店铺客户标签管理 | `youzan.scrm.customer.tags.get` | 已获得 | 标签分层与画像 | 标签ID (`tag_id`), 标签名 (`tag_name`), 账户ID (`yz_open_id`) |
| 会员等级打通 | `youzan.scrm.customer.level.get` | 已获得 | 等级分层 | 等级ID (`level_id`), 等级名称 (`level_name`) |
| 会员权益卡打通 | `youzan.scrm.card.list` | 已获得 | 权益识别 | 权益卡ID (`card_id`), 有效期 |
| 微信粉丝关联有赞用户 | `youzan.users.info.query` | 已获得 | 微信粉丝与有赞用户关系 | 微信应用ID (`app_id`), `open_id`, `union_id`, 关联账户 (`yz_open_id`) |
| 微信粉丝查询 | `youzan.users.weixin.follower.get` | 已获得 | 微信粉丝基础信息 | 粉丝标签, 关注状态, 关注时间 |
| 微信粉丝标签管理 | `youzan.users.weixin.follower.tags.get` | 已获得 | 粉丝标签画像 | 标签ID, 标签名, 粉丝标识 (`open_id`) |

**口径建议：**  
- OneID 以手机号为主键，必须输出“识别率”指标（手机号覆盖率）。  
- 若手机号缺失，仅做同端用户画像，不做跨端强绑定。
 - 微信粉丝能力可用于“公众号触达+人群标签”，但需与 buyer_id 关联可用率配套监控。

---

## 四、门店/网点与仓库域

| 能力包名称 | 核心接口 (API) | 权限状态 | 用途 | 关键字段（待确认） |
|---|---|---|---|---|
| 网店门店仓库信息同步 | `youzan.multistore.offline.search` | 已获得 | 门店/网点/仓库主数据 | 门店ID、名称、类型、地址、状态 |

---

## 五、库存与进销存域（动销、损耗、补货）

| 能力包名称 | 核心接口 (API) | 权限状态 | 用途 | 关键字段（待确认） |
|---|---|---|---|---|
| ERP全渠道库存同步 | `youzan.inventory.quantity.update` | 已获得 | 库存总量与门店库存 | SKU、门店ID、可用库存 |
| 多网点有赞库存同步线下 | `youzan.retail.open.stock.sku.get` | 已获得 | 有赞 -> 线下库存同步 | SKU、门店ID、库存变化 |
| 多网点线下库存同步有赞 | `youzan.retail.open.stock.sku.update` | 已获得 | 线下 -> 有赞库存同步 | SKU、门店ID、库存变化 |
| 网店库存调整 | `youzan.inventory.quantity.sync` | 已获得 | 盘盈盘亏/调整 | SKU、门店ID、调整数量 |
| 库存盘点 | `youzan.retail.open.inventory.check` | 已获得 | 盘点差异 | 盘点单ID、差异数量 |
| 库存采购 | `youzan.retail.open.purchase.order` | 已获得 | 进货记录 | 采购单ID、SKU、数量、时间 |
| 采购退货 | `youzan.retail.open.purchase.return` | 已获得 | 进货退货 | 退货单ID、SKU、数量、时间 |
| 库存调拨 | `youzan.retail.open.allocate.order` | 已获得 | 门店间调拨 | 调拨单ID、来源/目标门店、SKU、数量 |
| 连锁库存同步（总部/网店） | `youzan.retail.open.stock.chain.sync` | 已获得 | 连锁库存结构 | 总部/网店库存状态 |

**口径建议：**  
- 以“采购/调拨/盘点/调整”构建库存流水，配合订单明细计算真实动销与损耗。  
- 若有报损字段，需单独建“报损原因”维度。

---

## 六、营销与评价域（运营辅助）

| 能力包名称 | 核心接口 (API) | 权限状态 | 用途 | 关键字段（待确认） |
|---|---|---|---|---|
| 营销活动查询 | `youzan.ump.activities.get` | 已获得 | 活动效果评估 | 活动ID (`activity_id`), 活动类型 (`activity_type`) |
| 优惠券管理 | `youzan.ump.voucher.search`, `voucheractivity.send` | 已获得 | 优惠券活动、发放与核销 | 券组ID (`coupon_group_id`), 券码 (`verify_code`), 发放/核销时间, 核销门店 (`offline_id`) |
| 限时折扣 | `youzan.ump.limitdiscount.get` | 已获得 | 折扣与动销关联 | 折扣活动ID (`activity_id`), SKU (`sku_id`), 折扣价 |
| 自定义会员价 | `youzan.ump.memberprice.get` | 已获得 | 会员价影响评估 | SKU (`sku_id`), 会员等级 (`level_id`), 价格 (`price`) |
| 评价管理 | `youzan.trade.rate.get` | 已获得 | 口碑与复购关联 | 订单号 (`tid`), 评分, 评价时间 |
| 电子卡券核销 | `youzan.ump.ticket.verify` | 已获得 | 卡券核销记录 | 卡券码 (`verify_code`), 核销时间, 核销门店 (`offline_id`) |

**说明：** 已具备优惠券发放与核销能力，可支持“自动化发券闭环”。

---

## 七、同步策略（建议）

1. **订单/售后**：日级增量 + T+1 对账  
2. **库存/进销存**：日级增量（必要时加小时级）  
3. **商品/会员/门店**：日级全量或按更新时间增量  
4. **营销活动**：日级全量  
5. **优惠券/核销**：日级增量  
6. **实时能力**：当前按“非实时”设计，若未来需要实时再评估 Webhook/消息订阅能力包  

---

## 八、待确认清单（接口联调前最后核对）

1. **API 返回的字段结构层级**：如 `orders` 数组内的商品明细嵌套深度，需在控制台/Postman调用后确认。
2. **手机号解密**：有赞对部分手机号 (`mobile`) 会进行脱敏或加密返回（依赖数据安全组件），需确认业务上是否已开通手机号明文获取权限，否则 OneID 需降级使用 `yz_open_id` / `union_id`。
3. **退款金额类型**：确认 `refund_fee` 是否只包含实退金额，是否扣除运费和营销抵扣。
4. **外部商家编码 (`outer_id`)的必填约束**：请业务侧运营保证所有新商品上架时，必须规范填写 `outer_id`（针对冷链版和热食版统一编码），中台逻辑才可闭环。