订单 API

本文档详细介绍订单相关的 API 接口。

创建订单

接口地址: POST /order/create

请求参数

参数	类型	必填	说明
addressId	string	是	收货地址 ID
items	array	是	商品列表
items[].productId	string	是	商品 ID
items[].skuId	string	是	SKU ID
items[].quantity	int	是	购买数量
remark	string	否	订单备注
couponId	string	否	优惠券 ID

请求示例

POST /order/create
Content-Type: application/json

{
  "addressId": "A10001",
  "items": [
    {
      "productId": "P10001",
      "skuId": "SKU001",
      "quantity": 1
    }
  ],
  "remark": "请尽快发货",
  "couponId": "C10001"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "orderId": "RT202401110001",
    "orderNo": "2024011100001",
    "totalAmount": 8999.00,
    "currency": "CNY",
    "rubAmount": 112487.50,
    "exchangeRate": 12.5,
    "discountAmount": 500.00,
    "finalAmount": 8499.00,
    "status": "待付款",
    "paymentExpireTime": "2024-01-11 11:30:00",
    "createTime": "2024-01-11 10:30:00"
  }
}

获取订单列表

接口地址: GET /order/list

请求参数

参数	类型	必填	说明
status	string	否	订单状态
page	int	否	页码，默认 1
pageSize	int	否	每页数量，默认 20

订单状态

状态值	说明
pending_payment	待付款
pending_shipment	待发货
shipped	已发货
completed	已完成
cancelled	已取消
refunding	退款中
refunded	已退款

请求示例

GET /order/list?status=pending_shipment&page=1&pageSize=20

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "orderId": "RT202401110001",
        "orderNo": "2024011100001",
        "status": "待发货",
        "statusText": "待发货",
        "totalAmount": 8999.00,
        "rubAmount": 112487.50,
        "items": [
          {
            "productId": "P10001",
            "productName": "iPhone 15 Pro Max 256GB",
            "skuName": "原色钛金属",
            "price": 8999.00,
            "quantity": 1,
            "image": "https://img.russia-taobao.com/product/P10001.jpg"
          }
        ],
        "createTime": "2024-01-11 10:30:00",
        "paymentTime": "2024-01-11 10:35:00"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 5,
      "totalPages": 1
    }
  }
}

获取订单详情

接口地址: GET /order/{id}

路径参数

参数	类型	必填	说明
id	string	是	订单 ID

请求示例

GET /order/RT202401110001

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "orderId": "RT202401110001",
    "orderNo": "2024011100001",
    "status": "已发货",
    "statusText": "已发货",
    "totalAmount": 8999.00,
    "currency": "CNY",
    "rubAmount": 112487.50,
    "exchangeRate": 12.5,
    "discountAmount": 500.00,
    "finalAmount": 8499.00,
    "items": [
      {
        "productId": "P10001",
        "productName": "iPhone 15 Pro Max 256GB",
        "skuName": "原色钛金属",
        "price": 8999.00,
        "quantity": 1,
        "image": "https://img.russia-taobao.com/product/P10001.jpg"
      }
    ],
    "shippingAddress": {
      "id": "A10001",
      "receiverName": "张三",
      "phone": "+7-123-456-7890",
      "country": "俄罗斯",
      "city": "莫斯科",
      "address": "Example Street 123",
      "zipCode": "123456"
    },
    "shipping": {
      "company": "中国邮政",
      "companyCode": "EMS",
      "trackingNumber": "EA123456789CN",
      "shippingTime": "2024-01-11 14:00:00",
      "estimatedArrival": "2024-01-26"
    },
    "payment": {
      "method": "card",
      "paymentTime": "2024-01-11 10:35:00",
      "transactionId": "TXN2024011100001"
    },
    "remark": "请尽快发货",
    "createTime": "2024-01-11 10:30:00",
    "paymentTime": "2024-01-11 10:35:00",
    "shippingTime": "2024-01-11 14:00:00"
  }
}

取消订单

接口地址: POST /order/{id}/cancel

路径参数

参数	类型	必填	说明
id	string	是	订单 ID

请求参数

参数	类型	必填	说明
reason	string	是	取消原因

请求示例

POST /order/RT202401110001/cancel
Content-Type: application/json

{
  "reason": "不想要了"
}

响应示例

{
  "code": 200,
  "message": "订单取消成功",
  "data": {
    "orderId": "RT202401110001",
    "status": "已取消",
    "cancelTime": "2024-01-11 15:00:00"
  }
}

申请退款

接口地址: POST /order/{id}/refund

路径参数

参数	类型	必填	说明
id	string	是	订单 ID

请求参数

参数	类型	必填	说明
reason	string	是	退款原因
refundAmount	decimal	否	退款金额，不传则全额退款
images	array	否	退款凭证图片

请求示例

POST /order/RT202401110001/refund
Content-Type: application/json

{
  "reason": "商品与描述不符",
  "refundAmount": 8499.00,
  "images": [
    "https://img.russia-taobao.com/refund/IMG001.jpg"
  ]
}

响应示例

{
  "code": 200,
  "message": "退款申请已提交",
  "data": {
    "orderId": "RT202401110001",
    "status": "退款中",
    "refundId": "RF202401110001",
    "refundAmount": 8499.00,
    "applyTime": "2024-01-11 16:00:00"
  }
}

查询退款状态

接口地址: GET /order/{id}/refund/status

路径参数

参数	类型	必填	说明
id	string	是	订单 ID

请求示例

GET /order/RT202401110001/refund/status

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "refundId": "RF202401110001",
    "status": "processing",
    "statusText": "处理中",
    "refundAmount": 8499.00,
    "reason": "商品与描述不符",
    "applyTime": "2024-01-11 16:00:00",
    "processTime": null,
    "completeTime": null,
    "rejectReason": null
  }
}

错误码

错误码	说明
3001	订单不存在
3002	订单状态错误
3003	订单已支付，无法取消
3004	订单已发货，无法退款
3005	收货地址不存在
3006	商品库存不足
3007	优惠券不可用

示例代码

JavaScript

class OrderAPI {
  constructor(accessToken) {
    this.baseURL = 'https://api.russia-taobao.com/v1';
    this.headers = {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    };
  }

  // 创建订单
  async createOrder(orderData) {
    const response = await fetch(`${this.baseURL}/order/create`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(orderData)
    });
    return await response.json();
  }

  // 获取订单列表
  async getOrderList(params = {}) {
    const response = await fetch(
      `${this.baseURL}/order/list?${new URLSearchParams(params)}`,
      { headers: this.headers }
    );
    return await response.json();
  }

  // 获取订单详情
  async getOrderDetail(orderId) {
    const response = await fetch(
      `${this.baseURL}/order/${orderId}`,
      { headers: this.headers }
    );
    return await response.json();
  }

  // 取消订单
  async cancelOrder(orderId, reason) {
    const response = await fetch(`${this.baseURL}/order/${orderId}/cancel`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ reason })
    });
    return await response.json();
  }

  // 申请退款
  async applyRefund(orderId, refundData) {
    const response = await fetch(`${this.baseURL}/order/${orderId}/refund`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(refundData)
    });
    return await response.json();
  }
}

Python

import requests

class OrderAPI:
    def __init__(self, access_token):
        self.base_url = 'https://api.russia-taobao.com/v1'
        self.headers = {
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json'
        }
    
    def create_order(self, order_data):
        """创建订单"""
        url = f'{self.base_url}/order/create'
        response = requests.post(url, headers=self.headers, json=order_data)
        return response.json()
    
    def get_order_list(self, **params):
        """获取订单列表"""
        url = f'{self.base_url}/order/list'
        response = requests.get(url, headers=self.headers, params=params)
        return response.json()
    
    def get_order_detail(self, order_id):
        """获取订单详情"""
        url = f'{self.base_url}/order/{order_id}'
        response = requests.get(url, headers=self.headers)
        return response.json()
    
    def cancel_order(self, order_id, reason):
        """取消订单"""
        url = f'{self.base_url}/order/{order_id}/cancel'
        response = requests.post(url, headers=self.headers, json={'reason': reason})
        return response.json()
    
    def apply_refund(self, order_id, refund_data):
        """申请退款"""
        url = f'{self.base_url}/order/{order_id}/refund'
        response = requests.post(url, headers=self.headers, json=refund_data)
        return response.json()
    
    def get_refund_status(self, order_id):
        """查询退款状态"""
        url = f'{self.base_url}/order/{order_id}/refund/status'
        response = requests.get(url, headers=self.headers)
        return response.json()

创建订单​

请求参数​

请求示例​

响应示例​

获取订单列表​

请求参数​

订单状态​

请求示例​

响应示例​

获取订单详情​

路径参数​

请求示例​

响应示例​

取消订单​

路径参数​

请求参数​

请求示例​

响应示例​

申请退款​

路径参数​

请求参数​

请求示例​

响应示例​

查询退款状态​

路径参数​

请求示例​

响应示例​

错误码​

示例代码​

JavaScript​

Python​

创建订单

请求参数

请求示例

响应示例

获取订单列表

请求参数

订单状态

请求示例

响应示例

获取订单详情

路径参数

请求示例

响应示例

取消订单

路径参数

请求参数

请求示例

响应示例

申请退款

路径参数

请求参数

请求示例

响应示例

查询退款状态

路径参数

请求示例

响应示例

错误码

示例代码

JavaScript

Python