搜索结果

×

搜索结果将在这里显示。

🛴 获取订单

订单 API 文档

本文档详细说明了与订单相关的 API 接口，包括获取订单列表和获取订单详情。

基础信息

  • 基础路径: /api
  • 响应格式: JSON
  • 认证方式: 部分接口需要登录认证（通过 login_required 装饰器）

1. 获取订单列表

获取系统中的订单列表，支持分页、搜索和筛选功能。

请求信息

  • URL: /api/orders
  • 方法: GET
  • 认证要求: 否

请求参数

参数名 类型 必选 默认值 描述
page integer 否 1 当前页码
pageSize integer 否 10 每页数量
search string 否 '' 搜索关键词，会匹配订单邮箱地址
status string 否 '' 订单状态筛选
payment_method string 否 '' 支付方式筛选

响应参数

参数名 类型 描述
success boolean 请求是否成功
message string 响应消息
data object 包含订单数据的对象
data.list array 订单列表数据
data.total integer 符合条件的总订单数
data.page integer 当前页码
data.pageSize integer 每页数量

订单对象结构

订单列表中的每个订单对象包含以下字段：

字段名 类型 描述
id integer 订单ID
customer_email string 客户邮箱地址
total_amount float 订单总金额
payment_method string 支付方式
status string 订单状态
created_at string 创建时间，格式为：YYYY-MM-DD HH:MM:SS
updated_at string 更新时间，格式为：YYYY-MM-DD HH:MM:SS

示例请求

GET /api/orders?page=1&pageSize=10&search=example@email.com&status=pending

成功响应示例

{
  "data": {
    "list": [
      {
        "created_at": "2025-04-16 11:35:10",
        "customer_email": "2524090391@qq.com",
        "id": 1290,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 11.0,
        "updated_at": "2025-04-16 11:35:10"
      },
      {
        "created_at": "2025-04-16 11:29:21",
        "customer_email": "cymber@163.com",
        "id": 1289,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 10.0,
        "updated_at": "2025-04-16 11:29:21"
      },
      {
        "created_at": "2025-04-16 11:26:16",
        "customer_email": "cymber@163.com",
        "id": 1288,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 10.0,
        "updated_at": "2025-04-16 11:26:16"
      },
      {
        "created_at": "2025-04-16 11:12:53",
        "customer_email": "cymber@163.com",
        "id": 1287,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 10.0,
        "updated_at": "2025-04-16 11:12:53"
      },
      {
        "created_at": "2025-04-16 11:12:29",
        "customer_email": "cymber@163.com",
        "id": 1286,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 10.0,
        "updated_at": "2025-04-16 11:12:29"
      },
      {
        "created_at": "2025-04-15 18:57:28",
        "customer_email": "cymber@163.co",
        "id": 1285,
        "payment_method": "unknown",
        "status": "failed",
        "total_amount": 11.0,
        "updated_at": "2025-04-15 18:58:09"
      },
      {
        "created_at": "2025-04-15 18:39:39",
        "customer_email": "cymber@163.com",
        "id": 1284,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 10.0,
        "updated_at": "2025-04-15 18:39:39"
      },
      {
        "created_at": "2025-04-14 11:38:17",
        "customer_email": "2524090391@qq.com",
        "id": 1283,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 11.0,
        "updated_at": "2025-04-14 11:38:17"
      },
      {
        "created_at": "2025-04-11 15:57:40",
        "customer_email": "2524090391@qq.com",
        "id": 1282,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 11.0,
        "updated_at": "2025-04-11 15:57:40"
      },
      {
        "created_at": "2025-04-11 11:38:03",
        "customer_email": "2524090391@qq.com",
        "id": 1281,
        "payment_method": "unknown",
        "status": "paid",
        "total_amount": 11.0,
        "updated_at": "2025-04-11 15:55:14"
      }
    ],
    "page": 1,
    "pageSize": 10,
    "total": 158
  },
  "message": "操作成功",
  "success": true
}

错误响应示例

{
  "success": false,
  "message": "查询订单失败: 数据库连接错误"
}

2. 获取订单详情

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

请求信息

  • URL: /api/orders/{order_id}
  • 方法: GET
  • 认证要求: 否

路径参数

参数名 类型 必选 描述
order_id integer 是 订单ID

响应参数

返回一个包含订单所有详细信息的对象。

订单详情对象结构

字段名 类型 描述
id integer 订单ID
cart_token string 购物车令牌
user_id integer 用户ID
shop_id integer 商店ID
original_price float 商品原价
shipping_fee float 运费
total_amount float 订单总金额
status string 订单状态
payment_status string 支付状态
shopify_order_id string Shopify订单ID
order_number string 订单编号
currency string 货币代码，如 USD
financial_status string 财务状态
fulfillment_status string 履行状态
customer_email string 客户邮箱地址
customer_phone string 客户电话号码
customer_name string 客户姓名
shipping_address object 配送地址信息
billing_address object 账单地址信息
payment_method string 支付方式
payment_details object 支付详情
notes string 订单备注
transaction_id string 交易ID
order_status_url string 订单状态URL
created_at string 创建时间，格式为：YYYY-MM-DD HH:MM:SS
updated_at string 更新时间，格式为：YYYY-MM-DD HH:MM:SS
paid_at string 支付时间，格式为：YYYY-MM-DD HH:MM:SS
order_items array 订单项目列表
line_items array 订单产品条目
shipping_lines array 配送方式信息
tax_lines array 税费信息
customer object 客户完整信息

地址对象结构

shipping_address 和 billing_address 字段包含以下属性：

字段名 类型 描述
first_name string 名字
last_name string 姓氏
address1 string 地址行1
address2 string 地址行2
city string 城市
province string 省/州
country string 国家
zip string 邮政编码
phone string 电话号码

订单项目对象结构

line_items 数组中的每个对象包含以下属性：

字段名 类型 描述
id integer 订单项ID
variant_id integer 产品变体ID
title string 产品标题
quantity integer 数量
sku string 产品SKU
price string 单价
product_id integer 产品ID

示例请求

GET /api/orders/12345

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 12345,
    "cart_token": "Z2NwLXVzLWVhc3QxOjAxSlJXRU0yVEtLNUJEMFBSU0IxR1RaWkY2",
    "shop_id": 42,
    "original_price": 49.99,
    "shipping_fee": 10.00,
    "total_amount": 59.99,
    "status": "pending",
    "payment_status": "unpaid",
    "shopify_order_id": "5023658479",
    "order_number": "1001",
    "currency": "USD",
    "financial_status": "pending",
    "fulfillment_status": "unfulfilled",
    "customer_email": "example@email.com",
    "customer_phone": "9076196279",
    "customer_name": "陈尧",
    "shipping_address": {
      "first_name": "尧",
      "last_name": "陈",
      "address1": "123 Street",
      "address2": "",
      "city": "武汉市",
      "province": "AK",
      "country": "US",
      "zip": "99502",
      "phone": "9076196279"
    },
    "billing_address": {
      "first_name": "尧",
      "last_name": "陈",
      "address1": "123 Street",
      "address2": "",
      "city": "武汉市",
      "province": "AK",
      "country": "US",
      "zip": "99502",
      "phone": "9076196279"
    },
    "payment_method": "worldxinpay",
    "payment_details": {
      "transaction_id": "wxp_123456789",
      "payment_method": "worldxinpay",
      "amount": 59.99,
      "currency": "USD",
      "status": "pending"
    },
    "notes": "通过支付网关创建的订单",
    "transaction_id": "wxp_123456789",
    "order_status_url": "https://runningshoesflashsale.com/46166360324/orders/123456789/authenticate",
    "created_at": "2025-04-16 10:30:45",
    "updated_at": "2025-04-16 10:30:45",
    "line_items": [
      {
        "id": 12789456,
        "variant_id": 45997023526964,
        "title": "Knitted Rhombus Geometric Jacquard Polo - coffee / S",
        "quantity": 1,
        "sku": "KR-GP-CS",
        "price": "6.99",
        "product_id": 8569874123
      }
    ],
    "shipping_lines": [
      {
        "title": "Standard Shipping",
        "price": "10.00"
      }
    ],
    "customer": {
      "id": 45678,
      "email": "example@email.com",
      "first_name": "尧",
      "last_name": "陈",
      "phone": "9076196279"
    }
  }
}

错误响应示例

{
  "code": 1,
  "msg": "订单不存在",
  "status": 404
}

3. Shopify 订单详情接口

通过 Shopify API 获取订单详情。

请求信息

  • URL: /api/shopify/orders/{order_id}
  • 方法: GET
  • 认证要求: 是，需要 shop_domain 和 access_token

请求参数

参数名 类型 必选 描述
shop_domain string 是 Shopify 商店域名
access_token string 是 Shopify API 访问令牌
shop_id integer 否 系统内部商店 ID

路径参数

参数名 类型 必选 描述
order_id string 是 Shopify 订单 ID

响应参数

参数名 类型 描述
success boolean 请求是否成功
order object Shopify 订单对象

示例请求

GET /api/shopify/orders/5023658479
Content-Type: application/json

{
  "shop_domain": "runningshoesflashsale.com",
  "access_token": "shpat_xxxx",
  "shop_id": 42
}

成功响应示例

{
  "success": true,
  "order": {
    "id": 5023658479,
    "name": "#1001",
    "email": "example@email.com",
    "created_at": "2025-04-16T10:30:45-04:00",
    "updated_at": "2025-04-16T10:30:45-04:00",
    "number": 1001,
    "note": "通过支付网关创建的订单",
    "token": "abc123",
    "gateway": "worldxinpay",
    "total_price": "59.99",
    "subtotal_price": "49.99",
    "total_tax": "0.00",
    "currency": "USD",
    "financial_status": "pending",
    "fulfillment_status": null,
    "confirmed": true,
    "total_discounts": "0.00",
    "contact_email": "example@email.com",
    "order_status_url": "https://runningshoesflashsale.com/46166360324/orders/123456789/authenticate",
    "line_items": [
      {
        "id": 12789456,
        "variant_id": 45997023526964,
        "title": "Knitted Rhombus Geometric Jacquard Polo - coffee / S",
        "quantity": 1,
        "sku": "KR-GP-CS",
        "variant_title": "coffee / S",
        "price": "6.99",
        "product_id": 8569874123
      }
    ],
    "shipping_address": {
      "first_name": "尧",
      "last_name": "陈",
      "address1": "123 Street",
      "address2": "",
      "city": "武汉市",
      "province": "AK",
      "country": "US",
      "zip": "99502",
      "phone": "9076196279"
    },
    "billing_address": {
      "first_name": "尧",
      "last_name": "陈",
      "address1": "123 Street",
      "address2": "",
      "city": "武汉市",
      "province": "AK",
      "country": "US",
      "zip": "99502",
      "phone": "9076196279"
    },
    "customer": {
      "id": 45678,
      "email": "example@email.com",
      "first_name": "尧",
      "last_name": "陈",
      "phone": "9076196279"
    },
    "shipping_lines": [
      {
        "id": 369258147,
        "title": "Standard Shipping",
        "price": "10.00",
        "code": "Standard"
      }
    ],
    "transactions": [
      {
        "id": 123456789,
        "order_id": 5023658479,
        "kind": "sale",
        "gateway": "worldxinpay",
        "status": "pending",
        "amount": "59.99",
        "created_at": "2025-04-16T10:30:45-04:00"
      }
    ],
    "fulfillments": []
  }
}

错误响应示例

{
  "success": false,
  "error": "获取订单失败: Order not found",
  "status_code": 404
}

状态代码

订单状态 (status) 可能的值:

  • pending: 待处理
  • processing: 处理中
  • completed: 已完成
  • cancelled: 已取消
  • refunded: 已退款
  • failed: 失败

支付状态 (payment_status) 可能的值:

  • unpaid: 未支付
  • paid: 已支付
  • partially_paid: 部分支付
  • refunded: 已退款
  • partially_refunded: 部分退款

财务状态 (financial_status) 可能的值:

  • pending: 待处理
  • authorized: 已授权
  • paid: 已支付
  • partially_paid: 部分支付
    -refunded: 已退款
  • voided: 已取消
  • partially_refunded: 部分退款

发货状态 (fulfillment_status) 可能的值:

  • fulfilled: 已发货
  • unfulfilled: 未发货
  • partially_fulfilled: 部分发货
  • restocked: 已重新入库
  • null: 无状态