交易订单与售后 API
交易订单与售后 API
本文归纳购物车、个人订单、商户订单、平台订单、支付动作、确认收货、退货和售后处理接口。
使用场景
| 场景 | 主要接口 | 说明 |
|---|---|---|
| 购物车管理 | /api/v1/personal/shopping/cart |
加购、查询当前用户购物车、删除 |
| 直接购买 | /api/v1/personal/order/demo、/api/v1/personal/order/create |
从商品详情直接下单 |
| 购物车下单 | /api/v1/personal/order/cart/demo、/api/v1/personal/order/cart/create |
从已勾选购物车生成订单 |
| 支付 | /api/v1/personal/order/{orderId}/payment |
支付订单并推进状态 |
| 订单查询 | /api/v1/personal/order/page、/api/v1/personal/order/{orderId} |
消费者订单列表和详情 |
| 商户处理 | /api/v1/merchant/order、/api/v1/merchant/return/order |
商户查看订单、确认或拒绝退货 |
| 平台监管 | /api/v1/order、/api/v1/order/return-request |
平台查询订单和处理售后 |
标准下单流程
- 消费者进入商品详情或购物车。
- 选择 SKU、数量和收货地址。
- 调用预创建接口，后端返回商品价格、运费、优惠和可下单结果。
- 前端展示订单确认页。
- 用户确认后调用正式创建接口。
- 支付成功后调用支付接口，订单进入待发货。
- 商户通过发货单或订单侧能力处理发货。
- 消费者查看订单物流，签收后确认完成或申请退货。
后端订单逻辑
订单域以“试算 -> 创建 -> 支付 -> 履约 -> 完成或售后”为主线。试算和正式创建会复用价格、库存、地址和营销校验，但只有正式创建会持久化订单和锁定优惠券。
| 阶段 | 后端处理 |
|---|---|
| 购物车试算 | 校验购物车归属、SKU、货架、库存、地址、当前价格和优惠券结构 |
| SKU 直购试算 | 校验 SKU、SPU、店铺、库存、地址、当前价格和优惠券适用范围 |
| 创建订单 | 保存主订单、子订单、订单项、状态日志，锁定所选优惠券，移除已下单购物车项 |
| 支付订单 | 校验待支付状态，校验锁券有效性，支付成功后标记用券、创建补贴、记录钱包入账 |
| 取消订单 | 待支付订单取消，释放锁定优惠券和预算预占 |
| 确认收货 | 推进订单项完成，触发后续评价和结算条件 |
| 申请退货 | 校验订单项状态、数量、售后窗口和是否已有未完成申请 |
订单金额计算来源：
| 金额 | 来源 |
|---|---|
| 商品原价 | 店铺货架价乘以数量 |
| 商品优惠 | 价格策略或活动价 |
| 优惠券优惠 | 平台券和商户券 |
| 运费 | 国内和国际运费规则 |
| 实付金额 | 商品金额减优惠加运费 |
| 商户结算基数 | 订单项快照，由价格和营销规则决定 |
关键状态
| 状态 | 业务含义 | 主要操作 |
|---|---|---|
| 待支付 | 订单已创建但未支付 | 支付、取消 |
| 待发货 | 支付完成，等待商户履约 | 商户发货、平台查询 |
| 待收货 | 已进入物流履约 | 查看物流、确认收货 |
| 待评价 | 订单完成但未评价 | 创建评价 |
| 售后中 | 用户发起退货或退款 | 商户确认、平台审核 |
| 已完成 | 交易闭环完成 | 结算、评价、售后限制 |
优惠券订单流程
优惠券已经接入订单预览、创建和支付。
| 步骤 | 接口 | 结果 |
|---|---|---|
| 不带券试算 | POST /personal/order/cart/demo 或 POST /personal/order/demo |
返回基础金额和按店铺拆单结果 |
| 查询可用券 | POST /personal/order/cart/available-coupon 或 POST /personal/order/available-coupon |
返回当前订单可用平台券和商户券 |
| 带券试算 | 预览接口传 platformCouponWalletItemId 和 merchantCouponWalletItems |
返回优惠后金额 |
| 创建订单 | 创建接口传同一组卡券字段 | 保存订单并锁定优惠券 |
| 支付订单 | POST /personal/order/{orderId}/payment |
用券、生成分摊记录和补贴确认 |
| 取消或超时 | 取消接口或定时任务 | 释放卡券和预算预占 |
跨店订单中，平台券最多一张，商户券按店铺维度传入，每个店铺最多一张商户券。
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 购物车 | GET /list、GET /page、GET /{cartId}、GET /personal、POST、DELETE |
/api/v1/personal/shopping/cart |
*:personal:shopping:cart:* |
购物车查询、加购和删除 | admin、client |
ShoppingCartController |
| client | 个人订单交易 | POST /cart/demo、POST /cart/create、POST /demo、POST /create、POST /{orderId}/payment、PUT /cancel、PUT /sub-order/{orderSubItemId}/completed、PUT /sub-order/{orderSubItemId}/return |
/api/v1/personal/order |
client:personal:order:* |
预下单、下单、支付、取消、确认和申请退货 | client |
PersonalOrderTransactionController |
| client | 个人订单查询 | GET /count、GET /page、GET /page/pending-payment、GET /sub-order/page、GET /sub-order/page/waiting-ship、GET /sub-order-item/page/waiting-receive、GET /sub-order-item/page/waiting-comment、GET /sub-order-item/page/completed、GET /sub-order-item/{orderSubItemId}/shipping-detail、GET /{orderId} |
/api/v1/personal/order |
client:personal:order:query |
订单列表、详情、状态计数和物流详情 | client |
PersonalOrderQueryController |
| client | 个人退货申请 | GET /page、GET /{requestId}、POST、PUT /{requestId}/cancel |
/api/v1/personal/return/order |
client:personal:return:order:* |
消费者退货申请和取消 | client |
PersonalReturnOrderController |
| client | 商户订单 | GET /page、GET /{orderSubItemId}、PUT /sub-order/confirm |
/api/v1/merchant/order |
client:merchant:order:* |
商户侧订单查询和确认 | ops |
MerchantOrderController |
| client | 商户退货处理 | GET /page、GET /{requestId}、PUT /{requestId}/confirm、PUT /{requestId}/reject |
/api/v1/merchant/return/order |
client:merchant:return:order:* |
商户确认或拒绝退货 | ops |
MerchantReturnOrderController |
| admin | 平台订单查询 | GET /list、GET /page、GET /{orderId} |
/api/v1/order |
admin:order:* |
平台订单列表和详情 | admin |
OrderQueryController |
| admin | 平台订单交易 | POST /cart/demo、POST /cart/create、POST /demo、POST /create、POST /{orderId}/payment、PUT /{orderId}/cancel、PUT /{orderId}/close、PUT /sub-order/{orderSubItemId}/confirm、PUT /sub-order/{orderSubItemId}/payment-cancel、PUT /sub-order/{orderSubItemId}/confirm-cancel、PUT /sub-order/{orderSubItemId}/arrived、PUT /sub-order/{orderSubItemId}/completed、PUT /sub-order/{orderSubItemId}/return-completed |
/api/v1/order |
admin:order:* |
平台代操作订单状态 | admin |
OrderTransactionController |
| admin | 平台退货申请 | GET /page、GET /{requestId}、PUT /{requestId}/approve、PUT /{requestId}/reject、PUT /{requestId}/complete |
/api/v1/order/return-request |
admin:order:return-request:* |
平台售后审核和完成 | admin |
OrderReturnRequestController |
| admin | 账户异常工单 | GET /page、GET /{caseId}、POST、PUT、DELETE |
/api/v1/account/abnormal-case |
admin:account:abnormal-case:* |
账户异常与业务问题处理 | admin |
AccountAbnormalCaseController |
| admin | 商户退款异常 | GET /page、GET /{recordId} |
/api/v1/merchant/refund-exception |
admin:merchant:refund-exception:* |
商户退款异常查询 | admin |
MerchantRefundExceptionController |
| client | 商户退款异常 | GET /page、GET /{recordId} |
/api/v1/merchant/refund-exception |
client:merchant:refund-exception:* |
商户侧退款异常查询 | ops |
MerchantRefundExceptionController |
前端封装
admin/src/api/orderApi.ts。client/api/index.js的shoppingCart、personalOrder、cartOrder、orderDemo分组。ops/api/logistics.js中商户发货页面会消费发货单和发货明细接口，详见物流履约.md。
维护注意事项
- 预创建接口只用于展示和校验，不应产生不可回滚的业务副作用。
- 正式创建、支付、取消、确认收货等动作需要幂等，避免用户重复点击造成重复扣款或重复状态推进。
- 订单金额字段需要明确原价、优惠、运费、实付和币种。
- 退货申请需要校验订单状态、商品数量、售后期限和是否已有未完成售后。
- 商户订单和平台订单的查询范围不同，不能只靠前端隐藏数据，后端必须做数据权限控制。
- 支付前会重新校验锁定优惠券，失败时订单优惠可能需要重新试算。
- 退款完成后需要联动优惠券、预算、补贴和商户结算反冲，不能只改变退货申请状态。
联调验收
| 场景 | 验收口径 |
|---|---|
| 购物车下单 | 购物车归属、数量调整、库存、价格和地址都按后端校验 |
| SKU 直购 | 单商品试算和正式订单金额一致 |
| 带券下单 | 创建订单后卡券锁定，重复下单不能重复使用同一张券 |
| 支付成功 | 订单状态、支付流水、用券记录、预算流水和补贴记录完整 |
| 取消订单 | 待支付订单取消后卡券释放，订单状态不可继续支付 |
| 退货申请 | 已完成或符合售后条件的订单项才能申请退货 |
| 商户处理 | 商户只能查看和处理自己店铺的订单和退货 |
| 平台代操作 | 平台操作需要状态日志和明确业务原因 |