XTan 主题

Appearance

订单接口 ​

类说明 ​

Orders 类提供订单相关的功能，包括创建订单、获取订单列表、查询订单详情、取消订单以及微信支付功能。

功能特点：

  • 支持余额支付和微信支付
  • 支持订单状态管理
  • 支持分页查询订单列表
  • 支持订单取消和退款
  • 与虎皮椒支付集成

支付方式说明：

  • pay_type = 1 : 余额支付
  • pay_type = 2 : 微信支付（虎皮椒）

创建订单 ​

Method : POST

URL : /wp-json/vtheme/v1/orders

Auth required : True

Headers :

  • Authorization: Bearer
  • Content-Type: application/json

Body :

json
{
  "item_id": 123,
  "quantity": 1,
  "pay_type": 1
}

参数说明：

  • item_id : [integer] 必填，商品ID
  • quantity : [integer] 选填，购买数量，默认为1
  • pay_type : [integer] 选填，支付方式，1=余额支付（默认），2=微信支付

Success Response ​

Code : 201 Created

Content example :

json
{
  "order_id": 123,
  "order_trade_no": "ORD202301011200001234",
  "order_amount": 10000,
  "pay_type": 1,
  "order_type": "wait-send"
}

返回字段说明：

  • order_id : 订单ID
  • order_trade_no : 订单号
  • order_amount : 订单金额（单位：分）
  • pay_type : 支付方式
  • order_type : 订单状态 (wait-pay=待支付, wait-send=待发货/已支付, completed=已完成, cancelled=已取消)

Error Response ​

Code : 400 Bad Request

Content examples :

json
{
  "code": "missing_params",
  "message": "Missing item ID",
  "data": {
    "status": 400
  }
}
json
{
  "code": "item_not_found",
  "message": "Item not found",
  "data": {
    "status": 404
  }
}
json
{
  "code": "invalid_price",
  "message": "Invalid item price",
  "data": {
    "status": 400
  }
}
json
{
  "code": "insufficient_balance",
  "message": "Insufficient balance",
  "data": {
    "status": 400
  }
}

Code : 500 Internal Server Error

Content example :

json
{
  "code": "order_creation_failed",
  "message": "Failed to create order",
  "data": {
    "status": 500
  }
}

获取订单列表 ​

Method : GET

URL : /wp-json/vtheme/v1/orders

Auth required : True

Headers :

  • Authorization: Bearer

Query Parameters :

  • page : [integer] 页码，默认1
  • per_page : [integer] 每页数量，默认10
  • order_type : [string] 订单状态筛选，可选值：wait-pay, wait-send, completed, cancelled

Success Response ​

Code : 200 OK

Content example :

json
{
  "orders": [
    {
      "id": 123,
      "user_id": 1,
      "order_trade_no": "ORD202301011200001234",
      "order_amount": 10000,
      "order_type": "wait-send",
      "pay_type": 1,
      "created_at": "2023-01-01 12:00:00",
      "items": [
        {
          "id": 123,
          "user_id": 1,
          "order_trade_no": "ORD202301011200001234",
          "item_id": 456,
          "item_price": 10000,
          "item_title": "商品标题",
          "quantity": 1
        }
      ]
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}

获取订单详情 ​

Method : GET

URL : /wp-json/vtheme/v1/orders/{id}

Auth required : True

URL Parameters :

  • id : [integer] 订单ID

Headers :

  • Authorization: Bearer

Success Response ​

Code : 200 OK

Content example :

json
{
  "id": 123,
  "user_id": 1,
  "order_trade_no": "ORD202301011200001234",
  "order_amount": 10000,
  "order_type": "wait-send",
  "pay_type": 1,
  "created_at": "2023-01-01 12:00:00",
  "items": [
    {
      "id": 123,
      "user_id": 1,
      "order_trade_no": "ORD202301011200001234",
      "item_id": 456,
      "item_price": 10000,
      "item_title": "商品标题",
      "quantity": 1
    }
  ]
}

Error Response ​

Code : 404 Not Found

Content example :

json
{
  "code": "order_not_found",
  "message": "Order not found",
  "data": {
    "status": 404
  }
}

取消订单 ​

Method : POST

URL : /wp-json/vtheme/v1/orders/{id}/cancel

Auth required : True

URL Parameters :

  • id : [integer] 订单ID

Headers :

  • Authorization: Bearer

Success Response ​

Code : 200 OK

Content example :

json
{
  "message": "Order cancelled successfully"
}

注意： 如果订单使用余额支付并且已经支付，会自动退款到用户余额

Error Response ​

Code : 404 Not Found

Content example :

json
{
  "code": "order_not_found",
  "message": "Order not found",
  "data": {
    "status": 404
  }
}

Code : 500 Internal Server Error

Content example :

json
{
  "code": "cancel_failed",
  "message": "具体错误信息",
  "data": {
    "status": 500
  }
}

生成微信支付二维码 ​

Method : POST

URL : /wp-json/vtheme/v1/orders/{id}/wechat-pay

Auth required : True

URL Parameters :

  • id : [integer] 订单ID

Headers :

  • Authorization: Bearer

Success Response ​

Code : 200 OK

Content example :

json
{
  "order_id": 123,
  "order_trade_no": "ORD202301011200001234",
  "pay_url": "https://api.xunhupay.com/payment/xxx",
  "qrcode": "weixin://wxpay/bizpayurl?pr=xxx",
  "qrcode_type": "text",
  "amount": "100.00"
}

返回字段说明：

  • order_id : 订单ID
  • order_trade_no : 订单号
  • pay_url : 支付页面URL
  • qrcode : 二维码内容（可能是URL或图片URL）
  • qrcode_type : 二维码类型，image=图片URL，text=文本内容
  • amount : 支付金额（元）

Error Response ​

Code : 400 Bad Request

Content examples :

json
{
  "code": "missing_order_id",
  "message": "Missing order ID",
  "data": {
    "status": 400
  }
}
json
{
  "code": "invalid_order_status",
  "message": "Order is not in pending payment status",
  "data": {
    "status": 400
  }
}
json
{
  "code": "invalid_payment_method",
  "message": "This order does not use WeChat payment",
  "data": {
    "status": 400
  }
}

Code : 500 Internal Server Error

Content example :

json
{
  "code": "create_payment_failed",
  "message": "具体错误信息",
  "data": {
    "status": 500
  }
}

使用示例 ​

创建订单 ​

javascript
// 创建余额支付订单
fetch('/wp-json/vtheme/v1/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    item_id: 123,
    quantity: 1,
    pay_type: 1  // 余额支付
  })
})
.then(response => response.json())
.then(data => {
  if (data.order_type === 'wait-send') {
    // 余额支付成功，订单已完成
    alert('余额支付成功！');
    window.location.href = '/account/orders/' + data.order_id;
  } else {
    // 待支付订单，跳转到支付页面
    alert('订单创建成功，请完成支付');
  }
})
.catch(error => {
  console.error('创建订单失败:', error);
});

微信支付 ​

javascript
// 获取微信支付二维码
function getWechatPayQrCode(orderId) {
  fetch(`/wp-json/vtheme/v1/orders/${orderId}/wechat-pay`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + token
    }
  })
  .then(response => response.json())
  .then(data => {
    console.log('订单号:', data.order_trade_no);
    console.log('金额:', data.amount);
    
    // 显示二维码
    if (data.qrcode_type === 'image') {
      document.getElementById('qrcode').src = data.qrcode;
    } else {
      // 使用qrcode库生成二维码
      new QRCode(document.getElementById('qrcode'), data.qrcode);
    }
    
    // 启动轮询检查订单状态
    startOrderPolling(orderId);
  })
  .catch(error => {
    console.error('获取支付二维码失败:', error);
  });
}

// 轮询检查订单状态
function startOrderPolling(orderId) {
  const maxAttempts = 60; // 最多轮询60次（5分钟）
  let attempts = 0;
  
  const pollInterval = setInterval(() => {
    attempts++;
    
    fetch(`/wp-json/vtheme/v1/orders/${orderId}`, {
      headers: {
        'Authorization': 'Bearer ' + token
      }
    })
    .then(response => response.json())
    .then(data => {
      if (data.order_type === 'completed' || data.order_type === 'wait-send') {
        // 支付成功
        clearInterval(pollInterval);
        alert('支付成功！');
        window.location.reload();
      } else if (attempts >= maxAttempts) {
        // 超时
        clearInterval(pollInterval);
        alert('支付超时，请重新尝试');
      }
    })
    .catch(error => {
      console.error('查询失败:', error);
    });
  }, 5000); // 每5秒查询一次
}

获取订单列表 ​

javascript
// 获取订单列表
function getOrders(page = 1, orderType = '') {
  let url = `/wp-json/vtheme/v1/orders?page=${page}&per_page=10`;
  if (orderType) {
    url += `&order_type=${orderType}`;
  }
  
  fetch(url, {
    headers: {
      'Authorization': 'Bearer ' + token
    }
  })
  .then(response => response.json())
  .then(data => {
    console.log('订单总数:', data.total);
    console.log('总页数:', data.total_pages);
    
    // 渲染订单列表
    renderOrderList(data.orders);
  });
}

// 渲染订单列表
function renderOrderList(orders) {
  const container = document.getElementById('orders-container');
  
  container.innerHTML = orders.map(order => `
    <div class="order-item">
      <div class="order-header">
        <span>订单号: ${order.order_trade_no}</span>
        <span>金额: ¥${(order.order_amount / 100).toFixed(2)}</span>
        <span class="status-${order.order_type}">${getStatusText(order.order_type)}</span>
      </div>
      <div class="order-items">
        ${order.items.map(item => `
          <div class="order-item-detail">
            <span>${item.item_title}</span>
            <span>×${item.quantity}</span>
            <span>¥${(item.item_price / 100).toFixed(2)}</span>
          </div>
        `).join('')}
      </div>
      <div class="order-actions">
        ${order.order_type === 'wait-pay' ? `
          <button onclick="payOrder(${order.id})">去支付</button>
          <button onclick="cancelOrder(${order.id})">取消订单</button>
        ` : ''}
        ${order.order_type === 'wait-send' ? `
          <button onclick="viewOrder(${order.id})">查看详情</button>
        ` : ''}
      </div>
    </div>
  `).join('');
}

function getStatusText(status) {
  const statusMap = {
    'wait-pay': '待支付',
    'wait-send': '待发货',
    'completed': '已完成',
    'cancelled': '已取消'
  };
  return statusMap[status] || status;
}

取消订单 ​

javascript
// 取消订单
function cancelOrder(orderId) {
  if (!confirm('确定要取消这个订单吗？')) {
    return;
  }
  
  fetch(`/wp-json/vtheme/v1/orders/${orderId}/cancel`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + token
    }
  })
  .then(response => response.json())
  .then(data => {
    alert('订单已取消');
    // 刷新订单列表
    getOrders();
  })
  .catch(error => {
    console.error('取消订单失败:', error);
  });
}

注意事项 ​

  1. 订单状态：

    • wait-pay : 待支付
    • wait-send : 待发货（余额支付已完成）
    • completed : 已完成（在线支付已完成）
    • cancelled : 已取消

  2. 支付方式：

    • 余额支付：支付成功后订单状态直接变为 wait-send
    • 微信支付：需要异步回调更新状态为 completed

  3. 退款机制：

    • 取消余额支付的订单会自动退款到用户余额
    • 取消微信支付的订单目前不支持退款

  4. 安全性：

    • 所有操作都需要登录
    • 用户只能操作自己的订单
    • 使用事务保证数据一致性

  5. 微信支付：

    • 需要配置虎皮椒支付参数
    • 前端需要轮询检查支付状态
    • 异步回调会自动更新订单状态