跳到主要内容

客户端 API 概览

本文档介绍俄罗斯代购淘宝平台的客户端 API 接口，供移动端和 Web 端开发者使用。

基础信息​

  • Base URL: https://api.russia-taobao.com/v1
  • 认证方式: Bearer Token
  • 数据格式: JSON
  • 字符编码: UTF-8

认证​

获取 API 密钥​

  1. 注册平台账号
  2. 登录后台管理系统
  3. 进入"开发者中心"
  4. 创建应用并获取 API Key 和 Secret

请求头​

所有 API 请求需要包含以下请求头：

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept-Language: zh-CN

获取访问令牌​

接口地址: POST /auth/token

请求参数:

{
  "apiKey": "your_api_key",
  "apiSecret": "your_api_secret",
  "grantType": "client_credentials"
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

通用响应格式​

成功响应​

{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1704946800
}

错误响应​

{
  "code": 400,
  "message": "参数错误",
  "error": "缺少必填参数: userId",
  "timestamp": 1704946800
}

状态码​

状态码说明
200请求成功
201创建成功
400请求参数错误
401未授权 / Token 过期
403禁止访问
404资源不存在
429请求过于频繁
500服务器内部错误

业务错误码​

错误码说明
1001用户不存在
1002用户已被禁用
2001商品不存在
2002商品已下架
2003库存不足
3001订单不存在
3002订单状态错误
4001支付失败
4002余额不足

速率限制​

  • 每分钟最多 100 次请求
  • 超过限制将返回 429 状态码
  • 响应头包含速率限制信息：
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704946860

分页参数​

所有列表接口支持分页：

参数类型必填说明
pageint否页码，默认 1
pageSizeint否每页数量，默认 20，最大 100

分页响应格式:

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

API 接口列表​

用户相关​

接口方法说明
/user/profileGET获取用户信息
/user/profilePUT更新用户信息
/user/addressGET获取收货地址列表
/user/addressPOST添加收货地址
/user/address/{id}PUT更新收货地址
/user/address/{id}DELETE删除收货地址

商品相关​

接口方法说明
/product/listGET获取商品列表
/product/{id}GET获取商品详情
/product/searchGET搜索商品
/product/categoryGET获取商品分类
/product/{id}/reviewsGET获取商品评价

订单相关​

接口方法说明
/order/createPOST创建订单
/order/listGET获取订单列表
/order/{id}GET获取订单详情
/order/{id}/cancelPOST取消订单
/order/{id}/refundPOST申请退款

支付相关​

接口方法说明
/payment/createPOST创建支付
/payment/statusGET查询支付状态
/payment/refundPOST申请退款

物流相关​

接口方法说明
/shipping/trackingGET查询物流轨迹
/shipping/companiesGET获取物流公司列表

示例代码​

JavaScript (fetch)​

// 获取商品列表
async function getProducts(page = 1, pageSize = 20) {
  const response = await fetch(
    `https://api.russia-taobao.com/v1/product/list?page=${page}&pageSize=${pageSize}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      }
    }
  );
  const data = await response.json();
  return data;
}

// 创建订单
async function createOrder(orderData) {
  const response = await fetch(
    'https://api.russia-taobao.com/v1/order/create',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(orderData)
    }
  );
  const data = await response.json();
  return data;
}

Python (requests)​

import requests

class RussiaTaobaoAPI:
    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 get_products(self, page=1, page_size=20):
        """获取商品列表"""
        url = f'{self.base_url}/product/list'
        params = {'page': page, 'pageSize': page_size}
        response = requests.get(url, headers=self.headers, params=params)
        return response.json()
    
    def get_product_detail(self, product_id):
        """获取商品详情"""
        url = f'{self.base_url}/product/{product_id}'
        response = requests.get(url, headers=self.headers)
        return response.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()

Java (OkHttp)​

import okhttp3.*;
import com.google.gson.Gson;

public class RussiaTaobaoAPI {
    private static final String BASE_URL = "https://api.russia-taobao.com/v1";
    private final OkHttpClient client;
    private final Gson gson;
    private String accessToken;

    public RussiaTaobaoAPI(String accessToken) {
        this.client = new OkHttpClient();
        this.gson = new Gson();
        this.accessToken = accessToken;
    }

    public ProductListResponse getProducts(int page, int pageSize) throws IOException {
        HttpUrl url = HttpUrl.parse(BASE_URL + "/product/list").newBuilder()
            .addQueryParameter("page", String.valueOf(page))
            .addQueryParameter("pageSize", String.valueOf(pageSize))
            .build();

        Request request = new Request.Builder()
            .url(url)
            .addHeader("Authorization", "Bearer " + accessToken)
            .addHeader("Content-Type", "application/json")
            .build();

        try (Response response = client.newCall(request).execute()) {
            String body = response.body().string();
            return gson.fromJson(body, ProductListResponse.class);
        }
    }
}

SDK 下载​

我们提供以下语言的官方 SDK：

技术支持​

如有 API 使用问题，请联系：