商户与结算 API

本文归纳商户、仓库、库存、钱包、保证金、提现、佣金策略和结算接口。

使用场景

场景 主要接口 说明
商户资料 商户账户、商户资质文件、商户店铺 入驻、资料维护和店铺管理
商户仓库 商户仓库、商户库存、库存流水 商户备货、库存调整和库存查询
钱包资金 商户钱包、保证金钱包、提现申请 商户余额、保证金、提现审核和打款
佣金规则 佣金策略、策略历史 平台抽佣规则和店铺绑定历史
结算 结算批次、结算单、结算明细、结算汇总 商户收入对账和平台结算

结算业务流程

  1. 平台维护佣金策略。
  2. 店铺绑定佣金策略，形成策略版本和历史记录。
  3. 订单完成后进入可结算范围。
  4. 平台执行结算批次。
  5. 系统生成商户结算单和结算明细。
  6. 商户钱包余额和流水更新。
  7. 商户发起提现申请。
  8. 平台审核、驳回或打款。

后端结算逻辑

商户结算以订单项为最小业务单元。订单支付时会保存佣金策略快照，订单完成后进入可结算范围，结算批次执行时按快照计算商户应结金额。

阶段 后端处理
店铺绑定策略 店铺保存当前佣金策略 ID，策略变更保留历史
支付成功 订单项保存佣金策略快照和营销结算基数
订单完成 订单项具备可结算条件
批次执行 按商户、店铺和订单项生成结算单和结算明细
钱包入账 结算成功后写入商户钱包余额和钱包流水
退款或异常 通过结算反冲、退款异常或营销结算后调整处理

营销接入后，结算金额不仅受商品价格和佣金影响，还会受活动价、商户券、平台补贴和补贴确认影响。排查结算差异时要同时看订单项快照、优惠券分摊、预算流水和补贴确认记录。

关键字段

字段 说明
merchantAccountId 商户账户 ID，商户域核心身份
shopId 店铺 ID，商品上架、订单归属和佣金绑定依赖该字段
warehouseId 商户仓库 ID
inventoryId 商户库存 ID
walletId 商户钱包或保证金钱包 ID
policyId 佣金策略 ID
batchId 结算批次 ID
settlementId 结算单 ID
requestId 提现申请 ID

钱包和流水口径

对象 说明 对账口径
商户钱包 商户经营收入和提现来源 余额应能由钱包流水反推
保证金钱包 店铺保证金专用资金 与普通商户钱包分账
提现申请 商户将钱包余额提现吗 审核、驳回、打款都有状态和流水
预算充值 商户营销预算从商户钱包划转 需要同时核对商户钱包流水和营销预算流水
结算单 店铺或商户维度结算结果 汇总多个结算明细
结算明细 订单项级别结算依据 可追踪到订单项、佣金和营销影响
端别 接口名称 方法 路径 权限标识 主要用途 主要调用端 后端 Controller
shared 商户店铺 GET /list、GET /page、GET /{shopId}、POST、PUT、DELETE、PUT /{shopId}/commission-policy /api/v1/merchant/shop *:merchant:shop:* 店铺管理和佣金策略绑定 admin、ops MerchantShopController
shared 商户仓库 GET /list、GET /page、GET /{warehouseId}、POST、PUT、DELETE /api/v1/merchant/warehouse *:merchant:warehouse:* 商户仓库维护 admin、ops MerchantWarehouseController
shared 商户库存 GET /list、GET /page、GET /{inventoryId}、POST、PUT /{inventoryId}/inbound/stock、PUT /{inventoryId}/inbound/revision、PUT /{inventoryId}/outbound/revision、PUT /{inventoryId}/disable、DELETE /api/v1/merchant/inventory *:merchant:inventory:* 商户库存和库存调整 admin、ops MerchantInventoryController
shared 商户库存日志 GET /page、GET /{logId} /api/v1/merchant/inventory/log *:merchant:inventory:log:* 库存流水查询 admin、ops MerchantInventoryLogController
shared 商户钱包 GET、GET /page、GET /{walletId}、GET /transaction/page、GET /transaction/{transactionId}、POST /recharge /api/v1/merchant/wallet *:merchant:wallet:* 商户钱包、充值和流水 admin、ops MerchantWalletController
shared 保证金钱包 GET /page、GET /{walletId}、GET /shop/{merchantShopId}、GET /transaction/page、GET /transaction/{transactionId}、POST /init、POST /recharge、POST /deduct /api/v1/merchant/deposit-wallet *:merchant:deposit-wallet:* 商户保证金钱包 admin、ops MerchantDepositWalletController
shared 提现申请 POST、GET /page、GET /{requestId}、PUT /{requestId}/cancel、PUT /{requestId}/approve、PUT /{requestId}/reject、PUT /{requestId}/pay /api/v1/merchant/withdraw-request *:merchant:withdraw-request:* 提现申请、取消、审核、驳回和打款 admin、ops MerchantWithdrawRequestController
shared 佣金策略 GET /list、GET /page、GET /{policyId}、POST、PUT、DELETE /api/v1/merchant/commission-policy *:merchant:commission-policy:* 平台佣金策略维护和商户查询 admin、ops MerchantCommissionPolicyController
shared 佣金策略历史 GET /list、GET /page、GET /{historyId} /api/v1/merchant/commission-policy/history *:merchant:commission-policy:history:* 策略变更历史 admin、ops MerchantCommissionPolicyHistoryController
admin 结算批次 GET /list、GET /page、GET /{batchId}、POST /execute /api/v1/merchant/settlement/batch admin:merchant:settlement:batch:* 日批结算执行和查询 admin MerchantSettlementBatchController
shared 结算单 GET /list 或 GET /page、GET /{settlementId} /api/v1/merchant/settlement *:merchant:settlement:* 商户结算单查询 admin、ops MerchantSettlementController
shared 结算明细 GET /list 或 GET /page、GET /{detailId} /api/v1/merchant/settlement/detail *:merchant:settlement:detail:* 结算明细查询 admin、ops MerchantSettlementDetailController
shared 结算汇总 GET /api/v1/merchant/settlement/summary *:merchant:settlement:summary:* 结算概览数据 admin、ops MerchantSettlementSummaryController

前端封装

  • admin/src/api/accountApi.ts、walletApi.ts、operation.ts。
  • ops 当前重点覆盖商户发货和物流作业，结算类接口后续可在运营小程序按角色补齐。

维护注意事项

  • 佣金策略变更应保留历史版本，避免影响历史订单结算解释。
  • 结算批次执行需要防重复，避免同一订单重复生成结算明细。
  • 钱包余额必须能通过钱包流水反推，提现审核和打款都需要生成可追踪记录。
  • 商户只能查看和操作自己的店铺、仓库、库存、钱包和结算数据。
  • 保证金钱包和普通商户钱包需要清晰分账，避免资金用途混淆。
  • 商户营销预算充值会影响商户钱包，联调时需要同时核对营销预算池和商户钱包。
  • 已结算订单发生退款时，需要有反冲或异常治理记录，不能直接修改历史结算明细。

联调验收

场景 验收口径
佣金策略 新建、修改、绑定店铺和历史记录完整
订单结算 完成订单能进入结算批次，重复执行不会重复生成明细
钱包入账 结算后商户钱包余额和流水一致
提现流程 申请、取消、审核、驳回、打款状态正确
保证金 初始化、充值、扣减和流水可追踪
营销成本 商户券和商户活动价影响的成本能在预算流水和结算口径中解释
退款异常 退款后结算反冲、异常记录和钱包调整可追踪
previous 物流履约 next 系统基础数据与文件