9.4 KiB
9.4 KiB
餐饮零售数据中台 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) |
说明： 已具备优惠券发放与核销能力，可支持“自动化发券闭环”。
七、同步策略（建议）
- 订单/售后：日级增量 + T+1 对账
- 库存/进销存：日级增量（必要时加小时级）
- 商品/会员/门店：日级全量或按更新时间增量
- 营销活动：日级全量
- 优惠券/核销：日级增量
- 实时能力：当前按“非实时”设计，若未来需要实时再评估 Webhook/消息订阅能力包
八、待确认清单（接口联调前最后核对）
- API 返回的字段结构层级：如
orders数组内的商品明细嵌套深度，需在控制台/Postman调用后确认。 - 手机号解密：有赞对部分手机号 (
mobile) 会进行脱敏或加密返回（依赖数据安全组件），需确认业务上是否已开通手机号明文获取权限，否则 OneID 需降级使用yz_open_id/union_id。 - 退款金额类型：确认
refund_fee是否只包含实退金额，是否扣除运费和营销抵扣。 - 外部商家编码 (
outer_id)的必填约束：请业务侧运营保证所有新商品上架时，必须规范填写outer_id（针对冷链版和热食版统一编码），中台逻辑才可闭环。