??在工業(yè)采購(gòu)與供應(yīng)鏈管理領(lǐng)域，西域西域（Xiyuwang）作為專業(yè)的 MRO 工業(yè)用品采購(gòu)平臺(tái)，其商品數(shù)據(jù)對(duì)于工業(yè)電商系統(tǒng)、采購(gòu)分析工具等應(yīng)用具有重要價(jià)值。本文將詳細(xì)介紹西域平臺(tái)關(guān)鍵字搜索接口的調(diào)用方法，涵蓋認(rèn)證機(jī)制、參數(shù)配置、分頁(yè)處理及數(shù)據(jù)解析的完整流程，并提供可直接復(fù)用的 Python 代碼實(shí)現(xiàn)，幫助開(kāi)發(fā)者快速對(duì)接西域開(kāi)放平臺(tái)。

一、西域搜索接口基礎(chǔ)信息

西域提供的商品搜索接口（/api/v1/products/search）是獲取工業(yè)用品列表的核心接口，支持多維度篩選條件，特別適用于工業(yè)零部件、工具設(shè)備等商品的精準(zhǔn)檢索。

接口特點(diǎn)：

采用 API Key+Token 的雙重認(rèn)證機(jī)制
支持按關(guān)鍵字、分類、品牌、價(jià)格、庫(kù)存等多條件組合篩選
分頁(yè)加載數(shù)據(jù)，最大頁(yè)容量為 50 條
響應(yīng)包含商品基本信息、規(guī)格參數(shù)、價(jià)格、庫(kù)存、供應(yīng)商等工業(yè)用品特有數(shù)據(jù)

接口端點(diǎn)：https://api.xiyuwang.com/api/v1/products/search

二、認(rèn)證機(jī)制與參數(shù)說(shuō)明

1. 認(rèn)證流程

西域接口采用基于 API Key 和 Token 的認(rèn)證方式，具體流程如下：

在西域開(kāi)發(fā)者平臺(tái)注冊(cè)應(yīng)用，獲取 API Key
通過(guò) API Key 調(diào)用令牌接口獲取訪問(wèn) Token（有效期 24 小時(shí)）
在所有請(qǐng)求的 Header 中攜帶 Token 進(jìn)行身份驗(yàn)證

2. 核心參數(shù)說(shuō)明

公共 Header 參數(shù)：
X-API-Key：應(yīng)用的 API Key
Authorization：令牌，格式為Bearer {token}

查詢參數(shù)：

keyword：搜索關(guān)鍵字（必填）
page：頁(yè)碼（默認(rèn) 1）
size：每頁(yè)條數(shù)（1-50，默認(rèn) 20）
categoryId：分類 ID（可選）
brandId：品牌 ID（可選）
priceMin/priceMax：價(jià)格區(qū)間（可選）
stockMin：最低庫(kù)存（可選）
sort：排序方式（default - 默認(rèn)，priceAsc - 價(jià)升，priceDesc - 價(jià)降，stockDesc - 庫(kù)存降）
spec：規(guī)格篩選（可選，如 "voltage:220V"）

點(diǎn)擊獲取key和secret

三、完整代碼實(shí)現(xiàn)

以下是 Python 實(shí)現(xiàn)的西域平臺(tái)關(guān)鍵字搜索功能，包含令牌管理、多條件篩選和結(jié)果解析：

import requests
import time
from typing import Dict, List, Optional, Any

class XiyuwangSearchAPI:
def init(self, api_key: str, api_secret: str):
"""
初始化西域搜索API客戶端

:param api_key: 應(yīng)用的API Key
:param api_secret: 應(yīng)用的API Secret
"""
self.api_key = api_key
self.api_secret = api_secret
self.base_url = "api.xiyuwang.com"
self.search_endpoint = "/api/v1/products/search"
self.token_endpoint = "/api/v1/auth/token"
self.max_page_size = 50 # 最大每頁(yè)條數(shù)
self.token = None
self.token_expiry = 0 # 令牌過(guò)期時(shí)間戳(秒)

def _get_token(self) -> Optional[str]:
"""獲取或刷新訪問(wèn)令牌"""
# 檢查令牌是否有效（提前300秒刷新）
if self.token and time.time() < self.token_expiry - 300:
return self.token

# 準(zhǔn)備請(qǐng)求參數(shù)
headers = {
"X-API-Key": self.api_key,
"Content-Type": "application/json"
}

payload = {
"secret": self.api_secret,
"grantType": "client_credentials"
}

try:
response = requests.post(
f"{self.base_url}{self.token_endpoint}",
json=payload,
headers=headers,
timeout=10
)
response.raise_for_status()
result = response.json()

if result.get("success"):
self.token = result.get("data", {}).get("token")
expires_in = result.get("data", {}).get("expiresIn", 86400) # 默認(rèn)24小時(shí)
self.token_expiry = time.time() + expires_in
return self.token
else:
print(f"獲取令牌失敗: {result.get('message')}")
return None

except requests.exceptions.RequestException as e:
print(f"令牌請(qǐng)求異常: {str(e)}")
return None

def search_products(self,
keyword: str,
page: int = 1,
size: int = 20,
category_id: Optional[str] = None,
brand_id: Optional[str] = None,
price_min: Optional[float] = None,
price_max: Optional[float] = None,
stock_min: Optional[int] = None,
sort: str = "default",
spec: Optional[str] = None) -> Dict[str, Any]:
"""
搜索西域平臺(tái)商品

:param keyword: 搜索關(guān)鍵字
:param page: 頁(yè)碼
:param size: 每頁(yè)條數(shù)(1-50)
:param category_id: 分類ID
:param brand_id: 品牌ID
:param price_min: 最低價(jià)格
:param price_max: 最高價(jià)格
:param stock_min: 最低庫(kù)存
:param sort: 排序方式
:param spec: 規(guī)格篩選
:return: 搜索結(jié)果
"""
# 獲取令牌
token = self._get_token()
if not token:
return {
"success": False,
"error_msg": "無(wú)法獲取訪問(wèn)令牌"
}

# 限制最大頁(yè)容量
size = min(size, self.max_page_size)

# 構(gòu)建查詢參數(shù)
params: Dict[str, Any] = {
"keyword": keyword,
"page": page,
"size": size,
"sort": sort
}

# 添加可選參數(shù)
if category_id:
params["categoryId"] = category_id
if brand_id:
params["brandId"] = brand_id
if price_min is not None:
params["priceMin"] = price_min
if price_max is not None:
params["priceMax"] = price_max
if stock_min is not None:
params["stockMin"] = stock_min
if spec:
params["spec"] = spec

# 設(shè)置請(qǐng)求頭
headers = {
"X-API-Key": self.api_key,
"Authorization": f"Bearer {token}",
"Accept": "application/json"
}

try:
# 發(fā)送請(qǐng)求
response = requests.get(
f"{self.base_url}{self.search_endpoint}",
params=params,
headers=headers,
timeout=15
)
response.raise_for_status()

# 解析響應(yīng)
result = response.json()

# 處理API錯(cuò)誤
if not result.get("success"):
return {
"success": False,
"error_code": result.get("code"),
"error_msg": result.get("message", "未知錯(cuò)誤")
}

# 處理正常響應(yīng)
return self._parse_search_result(result.get("data", {}))

except requests.exceptions.RequestException as e:
return {
"success": False,
"error_msg": f"請(qǐng)求異常: {str(e)}"
}
except Exception as e:
return {
"success": False,
"error_msg": f"處理響應(yīng)失敗: {str(e)}"
}

def _parse_search_result(self, raw_data: Dict[str, Any]) -> Dict[str, Any]:
"""
解析原始搜索結(jié)果為結(jié)構(gòu)化數(shù)據(jù)

:param raw_data: 原始API響應(yīng)數(shù)據(jù)
:return: 結(jié)構(gòu)化的搜索結(jié)果
"""
# 提取分頁(yè)信息
pagination = {
"total": raw_data.get("total", 0),
"page": raw_data.get("page", 1),
"size": raw_data.get("size", 20),
"pages": raw_data.get("pages", 0)
}

# 解析商品列表
products = []
for item in raw_data.get("list", []):
# 解析規(guī)格參數(shù)
specifications = []
for spec in item.get("specifications", []):
specifications.append({
"name": spec.get("name"),
"value": spec.get("value")
})

# 解析價(jià)格信息
price_info = {
"price": item.get("price"),
"original_price": item.get("originalPrice"),
"currency": item.get("currency", "CNY"),
"moq": item.get("moq", 1), # 最小起訂量
"discount": item.get("discount") # 折扣信息
}

products.append({
"product_id": item.get("id"),
"sku": item.get("sku"),
"name": item.get("name"),
"model": item.get("model"), # 型號(hào)
"image": item.get("mainImage"),
"brand": {
"id": item.get("brandId"),
"name": item.get("brandName")
},
"category": {
"id": item.get("categoryId"),
"name": item.get("categoryName")
},
"price": price_info,
"stock": {
"quantity": item.get("stockQuantity"),
"warehouse": item.get("warehouseName")
},
"specifications": specifications,
"certifications": item.get("certifications", []), # 認(rèn)證信息
"delivery": {
"lead_time": item.get("leadTime"), # 交貨期
"support_batch": item.get("supportBatch", False) # 是否支持批量
},
"url": item.get("productUrl")
})

return {
"success": True,
"pagination": pagination,
"products": products,
"filters": self._parse_filters(raw_data.get("filters", {}))
}

def _parse_filters(self, raw_filters: Dict[str, Any]) -> Dict[str, Any]:
"""解析可用篩選條件"""
filters = {}

# 分類篩選
if "categories" in raw_filters:
filters["categories"] = [
{"id": item.get("id"), "name": item.get("name"), "count": item.get("count")}
for item in raw_filters["categories"]
]

# 品牌篩選
if "brands" in raw_filters:
filters["brands"] = [
{"id": item.get("id"), "name": item.get("name"), "count": item.get("count")}
for item in raw_filters["brands"]
]

# 規(guī)格篩選
if "specs" in raw_filters:
specs = {}
for spec in raw_filters["specs"]:
specs[spec.get("name")] = [
{"value": item.get("value"), "count": item.get("count")}
for item in spec.get("values", [])
]
filters["specs"] = specs

return filters

def batch_fetch_products(self,
keyword: str,
max_pages: int = 5,
kwargs) -> Dict[str, Any]:
"""
批量獲取多頁(yè)搜索結(jié)果

:param keyword: 搜索關(guān)鍵字
:param max_pages: 最大獲取頁(yè)數(shù)
:paramkwargs: 其他搜索參數(shù)
:return: 合并的搜索結(jié)果
"""
all_products = []
current_page = 1
total_pages = 1

while current_page <= max_pages and current_page <= total_pages:
# 搜索當(dāng)前頁(yè)
result = self.search_products(
keyword=keyword,
page=current_page,
**kwargs
)

if not result.get("success"):
return result

# 收集商品
all_products.extend(result.get("products", []))

# 更新分頁(yè)信息
pagination = result.get("pagination", {})
total_pages = pagination.get("pages", 1)

# 準(zhǔn)備下一頁(yè)
current_page += 1

# 添加請(qǐng)求間隔，避免觸發(fā)頻率限制
time.sleep(2)

return {
"success": True,
"total_products": len(all_products),
"products": all_products,
"summary": {
"total_pages": total_pages,
"fetched_pages": current_page - 1,
"total_available": pagination.get("total", 0)
}
}

# 使用示例
if name == "main":
# 替換為你的應(yīng)用憑證
API_KEY = "your_api_key"
API_SECRET = "your_api_secret"

# 初始化API客戶端
xiyu_api = XiyuwangSearchAPI(API_KEY, API_SECRET)

# 示例1：基礎(chǔ)搜索（工業(yè)電機(jī)）
basic_result = xiyu_api.search_products(
keyword="三相異步電機(jī)",
page=1,
size=20,
sort="priceAsc",
price_min=1000,
stock_min=10
)

if basic_result["success"]:
print(f"基礎(chǔ)搜索: 找到 {basic_result['pagination']['total']} 個(gè)商品")
print(f"第一頁(yè)商品數(shù)量: {len(basic_result['products'])}")
if basic_result["products"]:
product = basic_result["products"][0]
print(f"第一個(gè)商品: {product['name']}, 價(jià)格: {product['price']['price']}{product['price']['currency']}")
print(f"規(guī)格: {[f'{s["name"]}:{s["value"]}' for s in product['specifications'][:3]]}")

# 示例2：批量獲取多頁(yè)結(jié)果
multi_page_result = xiyu_api.batch_fetch_products(
keyword="精密軸承",
max_pages=3,
size=50,
sort="stockDesc"
)

if multi_page_result["success"]:
print(f"n多頁(yè)搜索: 共獲取 {multi_page_result['total_products']} 個(gè)商品")

四、代碼核心功能解析

令牌管理機(jī)制：
自動(dòng)處理令牌的獲取與過(guò)期刷新，無(wú)需手動(dòng)干預(yù)
提前 300 秒刷新令牌，避免請(qǐng)求時(shí)令牌過(guò)期
封裝令牌請(qǐng)求邏輯，簡(jiǎn)化核心搜索功能實(shí)現(xiàn)

工業(yè)用品數(shù)據(jù)處理：
專門針對(duì)工業(yè)商品特性設(shè)計(jì)數(shù)據(jù)結(jié)構(gòu)，包含型號(hào)、規(guī)格、認(rèn)證等特有字段
解析最小起訂量（MOQ）、交貨期等工業(yè)采購(gòu)關(guān)鍵信息
提取產(chǎn)品認(rèn)證信息，滿足工業(yè)采購(gòu)合規(guī)性要求

搜索功能增強(qiáng)：
支持規(guī)格參數(shù)篩選，滿足工業(yè)用品精準(zhǔn)搜索需求
提供批量獲取多頁(yè)數(shù)據(jù)的高級(jí)方法
內(nèi)置請(qǐng)求間隔控制，符合平臺(tái)調(diào)用規(guī)范

結(jié)構(gòu)化解析：
將原始響應(yīng)數(shù)據(jù)轉(zhuǎn)換為清晰的層級(jí)結(jié)構(gòu)
分類組織商品信息（基礎(chǔ)信息、價(jià)格、庫(kù)存、規(guī)格等）
解析可用篩選條件，便于前端實(shí)現(xiàn)高級(jí)篩選功能

五、實(shí)戰(zhàn)注意事項(xiàng)

接口權(quán)限與申請(qǐng)：
西域 API 需要企業(yè)資質(zhì)申請(qǐng)，主要面向工業(yè)供應(yīng)鏈相關(guān)企業(yè)
不同類型的應(yīng)用有不同的調(diào)用配額，工業(yè)企業(yè)應(yīng)用配額更高
部分特殊品類（如特種設(shè)備）的數(shù)據(jù)需要額外資質(zhì)審核

搜索策略優(yōu)化：
工業(yè)用品搜索建議結(jié)合分類 ID 和規(guī)格參數(shù)，提高精準(zhǔn)度
批量獲取數(shù)據(jù)時(shí)，注意控制請(qǐng)求頻率（建議間隔 2 秒以上）
對(duì)常用物料建立本地緩存，緩存時(shí)間建議設(shè)置為 24 小時(shí)

數(shù)據(jù)處理建議：
型號(hào)和規(guī)格是工業(yè)用品的核心標(biāo)識(shí)，需重點(diǎn)處理和存儲(chǔ)
注意區(qū)分不同包裝規(guī)格的價(jià)格差異
庫(kù)存數(shù)據(jù)具有時(shí)效性，關(guān)鍵采購(gòu)場(chǎng)景建議實(shí)時(shí)獲取

合規(guī)與安全：
嚴(yán)格遵守西域平臺(tái)的數(shù)據(jù)使用協(xié)議，不得用于非工業(yè)采購(gòu)場(chǎng)景
API Key 和 Secret 需妥善保管，避免泄露
生產(chǎn)環(huán)境建議部署在服務(wù)端，避免客戶端直接調(diào)用

六、功能擴(kuò)展方向

集成商品詳情接口，獲取完整的技術(shù)參數(shù)和供應(yīng)商信息
開(kāi)發(fā)價(jià)格對(duì)比功能，分析不同規(guī)格、品牌的性價(jià)比
實(shí)現(xiàn)庫(kù)存預(yù)警功能，監(jiān)控關(guān)鍵物料的庫(kù)存水平
開(kāi)發(fā)采購(gòu)?fù)扑]系統(tǒng)，基于歷史搜索和規(guī)格參數(shù)推薦合適產(chǎn)品

通過(guò)本文提供的方案，開(kāi)發(fā)者可以快速實(shí)現(xiàn)西域平臺(tái)的工業(yè)用品搜索功能，為工業(yè)電商、采購(gòu)管理系統(tǒng)等應(yīng)用提供精準(zhǔn)的數(shù)據(jù)支持。實(shí)際開(kāi)發(fā)中，建議根據(jù)工業(yè)采購(gòu)的業(yè)務(wù)特性，優(yōu)化搜索參數(shù)和數(shù)據(jù)處理邏輯，提升采購(gòu)效率。

審核編輯 黃宇