交易订单与售后 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 |
平台查询订单和处理售后 |
| 第三方商品采购 | /api/v1/third-party/platform/order、/api/v1/third-party/platform/purchase-order |
支付后由平台确认订单，采购人员到第三方平台下单并登记入库物流 |
标准下单流程
- 消费者进入商品详情或购物车。
- 选择 SKU、数量和收货地址。
- 调用预创建接口，后端返回商品价格、运费、优惠和可下单结果。
- 前端展示订单确认页。
- 用户确认后调用正式创建接口。
- 支付成功后调用支付接口，订单进入待发货。
- 商户通过发货单或订单侧能力处理发货。
- 消费者查看订单物流，签收后确认完成或申请退货。
第三方商品采购与中央仓入库
本流程适用于消费者在 client-we 购买第三方平台商品的场景。当前不直接调用第三方平台的下单 API，由采购人员在 admin 查看商品、复制中央仓收货信息，手动到第三方平台完成下单和支付。
flowchart TD
A["client-we 用户下单并支付"] --> B["第三方订单进入 WAITING_CONFIRM"]
B --> C["admin 确认订单并生成待采购单"]
C --> D["采购人员选择中央仓并到第三方平台下单"]
D --> E["登记平台订单号，采购单进入 ORDERED"]
E --> F["平台发货后选择物流公司并登记第三方物流单号"]
F --> G["创建采购入库履约单、包裹、内部运单和轨迹"]
G --> H["中央仓按现有物流流程收货"]
H --> I["采购单进入 DOMESTIC_RECEIVED"]
I --> J["admin 创建客户配送履约单"]
操作顺序
| 阶段 | admin 操作 |
接口 | 结果 |
|---|---|---|---|
| 支付后确认 | 在“第三方订单”中对 WAITING_CONFIRM 订单点击“确认订单”并核对订单；确认时间默认当前时间，备注可按需修改 |
PUT /api/v1/third-party/platform/order/{orderId}/confirm |
按平台和店铺生成 WAITING_PURCHASE 采购单 |
| 第三方平台下单 | 在“采购单”中对 WAITING_PURCHASE 采购单点击“平台下单”，选择中央仓并复制收货信息，在第三方平台完成下单后填写平台订单号；采购金额、采购时间、备注和采购明细可按实际情况补充 |
GET /api/v1/logistics/warehouse/list?abroad=false&status=ENABLE、PUT /api/v1/third-party/platform/purchase-order/{purchaseOrderId}/confirm |
页面要求选择中央仓并填写平台订单号，提交后采购单进入 ORDERED |
| 创建采购入库履约 | 平台发货后，对 ORDERED 采购单点击“入库履约”，再次选择同一中央仓，从启用的物流公司中选择承运方并填写平台物流单号；发货时间和发货人信息可选填 |
GET /api/v1/system/logistics/company/list?status=ENABLE、PUT /api/v1/third-party/platform/purchase-order/{purchaseOrderId}/inbound-delivery |
中央仓、物流公司和平台物流单号必填；创建采购入库履约单、包裹、内部运单和轨迹，采购单进入 PLATFORM_SHIPPED |
| 中央仓收货 | 仓库人员按现有入库流程处理包裹 | 现有仓入库接口 | 采购单联动进入 DOMESTIC_RECEIVED |
| 创建客户配送 | 对 DOMESTIC_RECEIVED 采购单点击“客户配送”；发件人和发件人电话可选填，不填时使用入库中央仓信息 |
PUT /api/v1/third-party/platform/purchase-order/{purchaseOrderId}/customer-delivery |
创建客户履约单，后续继续走现有配送流程 |
按钮与权限
| 状态 | 可执行操作 | 接口权限 | 查询和资源权限 |
|---|---|---|---|
WAITING_CONFIRM |
确认订单 | admin:third-party:order:confirm |
admin:third-party:order:query |
WAITING_PURCHASE |
平台下单 | admin:third-party:purchase-order:edit |
admin:third-party:purchase-order:query、admin:logistics:warehouse:list |
ORDERED |
入库履约 | admin:third-party:purchase-order:edit |
admin:third-party:purchase-order:query、admin:logistics:warehouse:list、admin:system:logistics:company:list |
DOMESTIC_RECEIVED |
客户配送 | admin:third-party:purchase-order:edit |
admin:third-party:purchase-order:query |
页面按钮同时受采购状态和接口权限控制。状态不匹配或账号缺少对应权限时，按钮不会显示。
单号与字段口径
| 字段 | 含义 | 录入时机 |
|---|---|---|
platformOrderNo |
采购人员在拼多多、1688、淘宝或京东下单后获得的平台订单号 |
第三方平台下单完成后 |
inboundWaybillNo |
第三方平台或供应商发货后的物流单号 | 平台发货后 |
inboundCompanyId |
选择物流公司后由页面提交的系统物流公司主数据 ID，不需要手工录入 | 创建采购入库履约单时 |
inboundCompany |
选择物流公司后由页面自动回填的物流公司名称 | 创建采购入库履约单时 |
warehouseId |
第三方商品寄送的目标中央仓 ID | 平台下单时用于查看收货信息，入库履约时作为正式接口字段提交 |
waybillNo |
采购入库履约创建后由系统生成的内部运单号 | 系统自动生成，不由采购人员录入 |
当前边界
- 平台下单是人工操作。
admin只提供商品链接、中央仓收货信息和采购结果登记，不代替采购人员在第三方平台支付。 - 平台下单界面选择的中央仓只用于展示和复制收货信息，不随采购确认接口保存。平台发货后，采购人员必须在“入库履约”中再次选择同一中央仓。
- 中央仓下拉框复用物流仓库列表接口，采购角色除采购单权限外，还需要
admin:logistics:warehouse:list权限。 - 物流公司下拉框只查询启用的物流公司，采购角色还需要
admin:system:logistics:company:list权限。 - 中央仓收货后会联动采购状态，但客户配送履约单目前仍由工作人员在
admin手动创建。
后端订单逻辑
订单域以“试算 -> 创建 -> 支付 -> 履约 -> 完成或售后”为主线。试算和正式创建会复用价格、库存、地址和营销校验，但只有正式创建会持久化订单和锁定优惠券。
| 阶段 | 后端处理 |
|---|---|
| 购物车试算 | 校验购物车归属、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 /list、GET /page、GET /{orderId}、PUT /{orderId}/confirm、PUT /{orderId}/close |
/api/v1/third-party/platform/order |
admin:third-party:order:* |
查询支付后订单，后台确认并生成待采购单 | admin |
ThirdPartyPlatformOrderController |
| admin | 第三方平台采购单 | GET /list、GET /page、GET /{purchaseOrderId}、PUT /{purchaseOrderId}/confirm、PUT /{purchaseOrderId}/abnormal、PUT /{purchaseOrderId}/inbound-delivery、PUT /{purchaseOrderId}/customer-delivery |
/api/v1/third-party/platform/purchase-order |
admin:third-party:purchase-order:* |
登记平台采购、入库物流和客户配送履约 | admin |
ThirdPartyPlatformPurchaseOrderController |
| admin | 采购中央仓选项 | GET /list |
/api/v1/logistics/warehouse |
admin:logistics:warehouse:list |
查询启用的国内仓库和收货信息 | admin |
LogisticsWarehouseController |
| admin | 采购物流公司选项 | GET /list |
/api/v1/system/logistics/company |
admin:system:logistics:company:list |
查询启用的物流公司，供入库履约选择 | admin |
LogisticsCompanyController |
| 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。admin/src/api/thirdPartyPlatformApi.ts封装第三方订单、采购确认、采购入库和客户配送接口。admin/src/views/third-party/order/index.vue承载支付后订单确认，admin/src/views/third-party/purchase/index.vue承载平台下单、物流登记和客户配送。client/api/index.js的shoppingCart、personalOrder、cartOrder、orderDemo分组。app/src/screens/order-*和app/src/services/trade-api.ts当前覆盖订单列表、订单确认和订单成功等基础页面。ops/api/logistics.js和ops-app/src/services/api.ts中商户发货页面会消费发货单和发货明细接口，详见物流履约.md。
维护注意事项
- 预创建接口只用于展示和校验，不应产生不可回滚的业务副作用。
- 正式创建、支付、取消、确认收货等动作需要幂等，避免用户重复点击造成重复扣款或重复状态推进。
- 订单金额字段需要明确原价、优惠、运费、实付和币种。
- 退货申请需要校验订单状态、商品数量、售后期限和是否已有未完成售后。
- 商户订单和平台订单的查询范围不同，不能只靠前端隐藏数据，后端必须做数据权限控制。
- 支付前会重新校验锁定优惠券，失败时订单优惠可能需要重新试算。
- 退款完成后需要联动优惠券、预算、补贴和商户结算反冲，不能只改变退货申请状态。
- 第三方平台订单号与物流单号是两个业务字段，不能相互替代。
- 平台下单阶段的中央仓选择不作为持久化事实来源，创建采购入库履约单前需要采购人员再次核对。
联调验收
| 场景 | 验收口径 |
|---|---|
| 购物车下单 | 购物车归属、数量调整、库存、价格和地址都按后端校验 |
| SKU 直购 | 单商品试算和正式订单金额一致 |
| 带券下单 | 创建订单后卡券锁定，重复下单不能重复使用同一张券 |
| 支付成功 | 订单状态、支付流水、用券记录、预算流水和补贴记录完整 |
| 取消订单 | 待支付订单取消后卡券释放，订单状态不可继续支付 |
| 退货申请 | 已完成或符合售后条件的订单项才能申请退货 |
| 商户处理 | 商户只能查看和处理自己店铺的订单和退货 |
| 平台代操作 | 平台操作需要状态日志和明确业务原因 |
| 第三方订单确认 | WAITING_CONFIRM 订单确认后生成对应待采购单 |
| 第三方平台下单 | 平台订单号保存后，采购单进入 ORDERED |
| 采购入库履约 | 重新核对中央仓，从启用列表选择物流公司并提交平台物流单号后生成包裹、运单和轨迹 |
| 中央仓收货后 | 采购单进入 DOMESTIC_RECEIVED，可在 admin 创建客户配送履约单 |