logan

Appearance

1 获取投诉列表（合并接口） ​

接口地址： /merchantapi/order/complaint/list

请求方式： POST

接口说明： 获取投诉列表，包含自营订单和下级订单的投诉（已合并原 proxyList 和 allList 接口）

请求参数：

参数名类型必填说明
statusstring否投诉状态：0=待商户处理，1=等待买家申请平台介入，2=平台介入中，3=已完结 更新于 2026-02-01
order_typestring否订单类型：own=自营订单，proxy=下级订单，空=全部 新增于 2026-02-05
pageint否页码，默认 1
limitint否每页数量，默认 20

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 1000,
        "source_user_id": 0,
        "buyer_user_id": 1008,
        "trade_no": "Q251114702349f4",
        "desc": "投诉内容",
        "status": 0,
        "create_at": "2025-11-14 02:11:59",
        "create_ip": "127.0.0.1",
        "result": 0,
        "expire_at": "2025-11-15 02:11:59",
        "platform_expire_at": "",
        "platform_intervene_at": "",
        "merchant_reject_at": "",
        "closed_at": "",
        "is_refunded": 0,
        "refund_at": "",
        "update_at": "2025-11-14 02:11:59",
        "orders": {
          "id": 10,
          "trade_no": "Q251114702349f4",
          "goods_id": 88,
          "goods_name": "商品名称",
          "category_name": "虚拟点卡",
          "total_price": "95.00",
          "status": 1,
          "create_at": "2025-11-14 02:00:00"
        },
        "goods_name": "商品名称",
        "order_type": "own",
        "order_type_text": "自营订单",
        "can_refund": true
      },
      {
        "id": 2,
        "user_id": 1001,
        "source_user_id": 1000,
        "buyer_user_id": 1009,
        "trade_no": "Q251114702349f5",
        "desc": "下级订单投诉",
        "status": 0,
        "create_at": "2025-11-14 03:20:15",
        "create_ip": "127.0.0.1",
        "result": 0,
        "expire_at": "2025-11-15 03:20:15",
        "platform_expire_at": "",
        "platform_intervene_at": "",
        "merchant_reject_at": "",
        "closed_at": "",
        "is_refunded": 0,
        "refund_at": "",
        "update_at": "2025-11-14 03:20:15",
        "orders": {
          "id": 11,
          "trade_no": "Q251114702349f5",
          "goods_id": 89,
          "goods_name": "代理商品",
          "category_name": "会员服务",
          "total_price": "38.00",
          "status": 1,
          "create_at": "2025-11-14 03:10:00"
        },
        "goods_name": "代理商品",
        "order_type": "proxy",
        "order_type_text": "下级订单",
        "can_refund": true
      }
    ],
    "total": 10
  }
}

字段说明：

  • 列表项返回投诉模型字段和 orders 订单关联对象，并额外追加 goods_name、order_type、order_type_text、can_refund
  • orders.category_name: 商品分类名称；订单关联对象内部的 goods 关联不返回
  • order_type: 订单类型
    • own: 自营订单（当前用户 = user_id）
    • proxy: 下级订单（当前用户 ≠ user_id，为代理订单）
  • order_type_text: 订单类型文本描述
  • can_refund: 是否可以退款
    • 代理订单：只有货源商户（source_user_id）可以退款
    • 非代理订单：只有直接商户（user_id）可以退款

说明：

  • 返回所有相关投诉（包括自己的和下级代理的）
  • 状态为 0、1、2 的进行中投诉属于待办事项，不受商户 7/15/40 天数据展示周期限制；已完结投诉才按展示周期过滤
  • 自动识别订单类型并标注
  • 自动判断退款权限

2.2 获取投诉详情 ​

接口地址： /merchantapi/order/complaint/detail

请求方式： POST

请求参数：

参数名类型必填说明
idint是投诉 ID

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "complaint": {
      "id": 1,
      "user_id": 1000,
      "source_user_id": 0,
      "buyer_user_id": 1008,
      "trade_no": "Q251114702349f4",
      "desc": "购买的卡密无法使用",
      "status": 0,
      "create_at": "2025-11-14 02:11:59",
      "create_ip": "127.0.0.1",
      "result": 0,
      "expire_at": "2025-11-15 02:11:59",
      "platform_expire_at": "",
      "platform_intervene_at": "",
      "merchant_reject_at": "",
      "closed_at": "",
      "is_refunded": 0,
      "refund_at": "",
      "update_at": "2025-11-14 02:11:59",
      "buyer_appeal_expire_at": ""
    },
    "order": {
      "id": 10,
      "trade_no": "Q251114702349f4",
      "user_id": 1000,
      "buyer_user_id": 1008,
      "goods_id": 88,
      "goods_name": "QQ币100元",
      "category_name": "虚拟点卡",
      "quantity": 1,
      "price": "95.00",
      "total_price": "95.00",
      "status": 1,
      "is_proxy": 0,
      "source_user_id": 0,
      "parent_user_id": 0,
      "source_goods_id": 0,
      "parent_goods_id": 0,
      "create_at": "2025-11-14 02:00:00"
    },
    "buyer": {
      "id": 100,
      "username": "买家A",
      "avatar": "https://example.com/avatar.jpg"
    },
    "messages": [
      {
        "id": 1,
        "from_user_id": 100,
        "from_type": "buyer",
        "content": "卡密无法使用",
        "create_at": 1699999999
      }
    ],
    "canRefund": true,
    "canReply": true,
    "myRole": "merchant"
  }
}

字段说明：

  • complaint: 投诉模型字段，隐藏内部关联对象 orders、buyerUser
  • order: 订单模型字段，额外追加 category_name 商品分类名称；内部关联对象 goods 不返回
  • canRefund: 当前用户是否可以退款
  • canReply: 当前用户是否可以回复；代理订单中销售代理为 false，只有货源商户为 true
  • myRole: 当前用户角色（merchant=商户，proxy=代理商/货源商户）
  • messages: 投诉会话消息，按 id 正序返回，第一条通常为买家提交投诉时填写的 desc
  • messages[].from_type: 消息来源：buyer=买家，merchant=商户，proxy=货源商户/代理货源方，admin=平台，system=系统状态消息

退款权限规则：

  • 代理订单：只有货源商户（source_user_id）可以退款
  • 非代理订单：只有直接商户（user_id）可以退款

消息兼容说明：

  • 2026-07-06 起，买家提交投诉时的投诉说明会作为 from_type=buyer 的第一条消息保存
  • 历史数据中如果第一条投诉说明曾保存为 from_type=system、from_user_id=0，接口返回时会按买家消息兼容为 from_type=buyer、from_user_id=buyer_user_id
  • 真正的系统流程消息仍保持 from_type=system，例如平台介入、投诉结束等状态通知

2.3 发送投诉消息 ​

接口地址： /merchantapi/order/complaint/send

请求方式： POST

请求参数：

参数名类型必填说明
idint是投诉 ID
contentstring是消息内容

响应示例：

json
{
  "code": 1,
  "msg": "发送成功"
}

业务规则：

  • 投诉已结束时不能发送消息
  • 代理订单只有货源商户（source_user_id）可以发送消息，销售代理只能查看沟通记录
  • 非代理订单只有直接商户（user_id）可以发送消息
  • 实时推送消息给相关方，频道名为 private-group-complaint-{投诉ID}，事件名为 message
  • 投诉详情页建议先请求详情接口获取历史消息，再订阅 WebSocket 频道接收新增消息

2.4 商户退款处理 ​

接口地址： /merchantapi/order/complaint/refund

请求方式： POST

请求参数：

参数名类型必填说明
idint是投诉 ID

响应示例：

json
{
  "code": 1,
  "msg": "退款成功"
}

业务规则：

  • 只有源头商户可以处理退款
  • 代理商无权操作退款
  • 代理订单：只有货源商户可以退款
  • 非代理订单：只有直接商户可以退款
  • 退款入账并完结投诉后，系统会向买家端“我的消息”写入投诉退款通知

2.5 商户拒绝退款 ​

更新于 2026-02-01：拒绝后买家 24 小时内可申请平台介入

接口地址： /merchantapi/order/complaint/rejectrefund

请求方式： POST

请求参数：

参数名类型必填说明
idint是投诉 ID
reasonstring是拒绝理由

响应示例：

json
{
  "code": 1,
  "msg": "已拒绝退款，买家可在24小时内申请平台介入"
}

业务规则：

  • 只有源头商户可以拒绝退款
  • 更新于 2026-02-01 拒绝后买家 24 小时内可申请平台介入，超时未申请则商家冻结资金正常结算
  • 权限规则与退款相同
  • 拒绝结果会写入买家端“我的消息”，提醒买家在 24 小时内申请平台介入

业务规则总结 ​

1. 订单状态 ​

  • 0：未支付
  • 1：已支付
  • 2：已关闭
  • 3：已退款

2. 投诉状态 ​

更新于 2026-02-01：调整状态 1 的含义

  • 0：待商户处理
  • 1：等待买家申请平台介入
  • 2：平台介入中
  • 3：已完结

3. 投诉处理流程 ​

更新于 2026-02-01：调整拒绝退款后的流程

买家发起投诉
    ↓
商户24小时内处理
    ├─ 同意退款 → 完结
    ├─ 拒绝退款 → 买家24小时内可申请平台介入
    │              ├─ 买家申请 → 平台介入（48小时）
    │              └─ 买家未申请 → 商家资金正常结算
    └─ 超时未处理 → 平台介入

4. 代理订单投诉处理 ​

代理订单投诉
    ├─ 货源商户（source_user_id）：可退款、可拒绝
    └─ 代理商户（user_id）：只能沟通，不能退款

5. 卡密查看权限 ​

  • 自己的订单：可以查看
  • 代理订单：只有源头商户可以查看
  • 其他情况：不能查看

注意事项 ​

  1. 投诉处理有时间限制（24 小时/48 小时）
  2. 代理订单的退款权限在货源商户
  3. 投诉消息实时推送给相关方
  4. 订单收益会扣除平台手续费
  5. 查看卡密时会自动触发发货（如果未发货）
  6. 投诉已结束后不能再发送消息
  7. 拒绝退款会自动触发平台介入
  8. 投诉详情中的 messages 按时间正序展示，投诉说明按买家消息展示，系统流程消息仍为 system