API文档

订单管理API

创建、查询和管理快递订单

创建订单

创建一个新的快递订单。

POST https://www.guansuda-express.com/api/v1/orders

请求参数

参数名 类型 必填 说明
sender Object 是 寄件人信息
receiver Object 是 收件人信息
item Object 是 物品信息
service_type String 否 服务类型：standard, express, same_day

请求示例

{
  "sender": {
    "name": "张三",
    "phone": "13800138000",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "detail": "三里屯街道1号"
  },
  "receiver": {
    "name": "李四",
    "phone": "13800138001",
    "province": "上海市",
    "city": "上海市",
    "district": "浦东新区",
    "detail": "陆家嘴金融中心1号"
  },
  "item": {
    "name": "文件",
    "description": "重要合同文件",
    "weight": 0.5,
    "value": 100.00,
    "quantity": 1
  },
  "service_type": "standard"
}

响应示例

{
  "success": true,
  "data": {
    "id": 12345,
    "order_no": "ORD20240722001",
    "tracking_number": "TRK20240722123456",
    "status": "pending",
    "estimated_fee": 25.00,
    "created_at": "2024-07-22T10:30:00Z"
  },
  "message": "订单创建成功"
}

获取订单列表

获取当前用户的订单列表。

GET https://www.guansuda-express.com/api/v1/orders

查询参数

参数名 类型 必填 说明
page Integer 否 页码，默认为1
limit Integer 否 每页数量，默认为10，最大100
status String 否 订单状态筛选
date_from Date 否 开始日期 (YYYY-MM-DD)
date_to Date 否 结束日期 (YYYY-MM-DD)

响应示例

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "order_no": "ORD20240722001",
      "tracking_number": "TRK20240722123456",
      "status": "in_transit",
      "payment_status": "paid",
      "actual_fee": 25.00,
      "item_name": "文件",
      "created_at": "2024-07-22T10:30:00Z",
      "sender": {
        "name": "张三",
        "city": "北京市"
      },
      "receiver": {
        "name": "李四",
        "city": "上海市"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 48,
    "per_page": 10
  }
}

获取订单详情

根据订单ID获取订单的详细信息。

GET https://www.guansuda-express.com/api/v1/orders/{id}

响应示例

{
  "success": true,
  "data": {
    "id": 12345,
    "order_no": "ORD20240722001",
    "tracking_number": "TRK20240722123456",
    "status": "in_transit",
    "payment_status": "paid",
    "service_type": "standard",
    "estimated_fee": 25.00,
    "actual_fee": 25.00,
    "created_at": "2024-07-22T10:30:00Z",
    "updated_at": "2024-07-22T14:30:00Z",
    "sender": {
      "name": "张三",
      "phone": "13800138000",
      "address": "北京市朝阳区三里屯街道1号"
    },
    "receiver": {
      "name": "李四",
      "phone": "13800138001",
      "address": "上海市浦东新区陆家嘴金融中心1号"
    },
    "item": {
      "name": "文件",
      "description": "重要合同文件",
      "weight": 0.5,
      "value": 100.00,
      "quantity": 1
    }
  }
}

取消订单

取消一个待支付或已支付的订单。

DELETE https://www.guansuda-express.com/api/v1/orders/{id}

响应示例

{
  "success": true,
  "message": "订单已成功取消"
}

订单状态说明

状态值 说明 可执行操作
pending 待支付 支付、取消
paid 已支付 取消、申请退款
processing 处理中 查看详情
picked 已取件 查看详情
in_transit 运输中 查看详情、追踪
delivering 派送中 查看详情、追踪
delivered 已送达 查看详情、评价
completed 已完成 查看详情
cancelled 已取消 查看详情