商品 API
本文档详细介绍商品相关的 API 接口。
获取商品列表
接口地址: GET /product/list
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| categoryId | string | 否 | 商品分类 ID |
| keyword | string | 否 | 搜索关键词 |
| page | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页数量，默认 20 |
| sortBy | string | 否 | 排序字段：price/sales/time |
| sortOrder | string | 否 | 排序方向：asc/desc |
请求示例
GET /product/list?categoryId=1001&page=1&pageSize=20&sortBy=sales&sortOrder=desc
响应示例
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"id": "P10001",
"name": "iPhone 15 Pro Max 256GB",
"price": 8999.00,
"originalPrice": 9999.00,
"currency": "CNY",
"rubPrice": 112487.50,
"image": "https://img.russia-taobao.com/product/P10001.jpg",
"sales": 1234,
"rating": 4.8,
"stock": 50,
"status": "on_sale"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
}
获取商品详情
接口地址: GET /product/{id}
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 商品 ID |
请求示例
GET /product/P10001
响应示例
{
"code": 200,
"message": "success",
"data": {
"id": "P10001",
"name": "iPhone 15 Pro Max 256GB",
"description": "全新原装正品，支持全国联保...",
"price": 8999.00,
"originalPrice": 9999.00,
"currency": "CNY",
"rubPrice": 112487.50,
"exchangeRate": 12.5,
"images": [
"https://img.russia-taobao.com/product/P10001_1.jpg",
"https://img.russia-taobao.com/product/P10001_2.jpg"
],
"skus": [
{
"id": "SKU001",
"name": "原色钛金属",
"price": 8999.00,
"stock": 20
},
{
"id": "SKU002",
"name": "蓝色钛金属",
"price": 8999.00,
"stock": 30
}
],
"sales": 1234,
"rating": 4.8,
"reviewCount": 567,
"stock": 50,
"status": "on_sale",
"shipping": {
"freeShipping": true,
"shippingFee": 0.00,
"estimatedDays": 15
},
"attributes": [
{
"name": "品牌",
"value": "Apple"
},
{
"name": "型号",
"value": "iPhone 15 Pro Max"
}
],
"createTime": "2024-01-01 10:00:00",
"updateTime": "2024-01-10 15:30:00"
}
}
搜索商品
接口地址: GET /product/search
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | 是 | 搜索关键词 |
| page | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页数量，默认 20 |
| priceMin | decimal | 否 | 最低价格 |
| priceMax | decimal | 否 | 最高价格 |
| sortBy | string | 否 | 排序字段：relevance/price/sales |
请求示例
GET /product/search?keyword=iPhone&page=1&pageSize=20&sortBy=relevance
响应示例
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"id": "P10001",
"name": "iPhone 15 Pro Max 256GB",
"price": 8999.00,
"rubPrice": 112487.50,
"image": "https://img.russia-taobao.com/product/P10001.jpg",
"sales": 1234,
"rating": 4.8
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 50,
"totalPages": 3
},
"suggestions": ["iPhone 15", "iPhone 14", "苹果手机"]
}
}
获取商品分类
接口地址: GET /product/category
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| parentId | string | 否 | 父分类 ID，不传则获取顶级分类 |
请求示例
GET /product/category
响应示例
{
"code": 200,
"message": "success",
"data": [
{
"id": "100",
"name": "数码电器",
"icon": "https://img.russia-taobao.com/category/digital.png",
"level": 1,
"children": [
{
"id": "1001",
"name": "手机",
"level": 2
},
{
"id": "1002",
"name": "平板电脑",
"level": 2
}
]
},
{
"id": "200",
"name": "服装鞋包",
"icon": "https://img.russia-taobao.com/category/clothing.png",
"level": 1
}
]
}
获取商品评价
接口地址: GET /product/{id}/reviews
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 商品 ID（路径参数） |
| page | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页数量，默认 20 |
| rating | int | 否 | 评价星级：1-5 |
请求示例
GET /product/P10001/reviews?page=1&pageSize=20
响应示例
{
"code": 200,
"message": "success",
"data": {
"summary": {
"total": 567,
"average": 4.8,
"distribution": {
"5": 450,
"4": 80,
"3": 25,
"2": 8,
"1": 4
}
},
"list": [
{
"id": "R10001",
"userId": "U123456",
"userName": "用户***",
"avatar": "https://img.russia-taobao.com/user/avatar.jpg",
"rating": 5,
"content": "商品质量很好，发货速度快！",
"images": [
"https://img.russia-taobao.com/review/R10001_1.jpg"
],
"skuInfo": "原色钛金属",
"createTime": "2024-01-10 15:30:00"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 567,
"totalPages": 29
}
}
}
错误码
| 错误码 | 说明 |
|---|---|
| 2001 | 商品不存在 |
| 2002 | 商品已下架 |
| 2003 | 库存不足 |
| 2004 | 商品分类不存在 |
示例代码
JavaScript
// 获取商品列表
async function getProductList(params) {
const response = await fetch(
`https://api.russia-taobao.com/v1/product/list?${new URLSearchParams(params)}`,
{
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
}
);
return await response.json();
}
// 获取商品详情
async function getProductDetail(productId) {
const response = await fetch(
`https://api.russia-taobao.com/v1/product/${productId}`,
{
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
}
);
return await response.json();
}
// 搜索商品
async function searchProducts(keyword, params = {}) {
const response = await fetch(
`https://api.russia-taobao.com/v1/product/search?keyword=${encodeURIComponent(keyword)}&${new URLSearchParams(params)}`,
{
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
}
);
return await response.json();
}
Python
import requests
class ProductAPI:
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_product_list(self, **params):
"""获取商品列表"""
url = f'{self.base_url}/product/list'
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 search_products(self, keyword, **params):
"""搜索商品"""
url = f'{self.base_url}/product/search'
params['keyword'] = keyword
response = requests.get(url, headers=self.headers, params=params)
return response.json()
def get_product_reviews(self, product_id, **params):
"""获取商品评价"""
url = f'{self.base_url}/product/{product_id}/reviews'
response = requests.get(url, headers=self.headers, params=params)
return response.json()