?

愛回收作為知名的二手電子產(chǎn)品回收與交易平臺，其提供的 API 接口是開發(fā)者接入其服務的重要橋梁。本文將聚焦于獲取商品詳情的 API 接口，介紹其基本用法、關鍵參數(shù)、響應數(shù)據(jù)結構以及使用時的注意事項。

1. 接口概述

功能描述：此接口用于根據(jù)指定的商品標識（如商品 ID），查詢并返回該商品在愛回收平臺上的詳細信息。

應用場景：適用于需要展示愛回收平臺商品詳情的應用場景，例如比價工具、商品聚合展示、庫存同步系統(tǒng)等。

請求方式：通常為 GET 或 POST（具體以官方文檔為準）。

接口地址：需要參考愛回收官方提供的最新 API 文檔獲取基礎 URL 和具體路徑，例如可能為 https://api.aihuishou.com/product/detail 或類似結構。

2. 關鍵請求參數(shù)

調用此接口，通常需要傳遞以下核心參數(shù)（具體參數(shù)名和是否必需請以官方文檔為準）：

product_id / item_id / spu_id / sku_id (必填)：用于唯一標識目標商品的 ID。這是調用此接口的核心參數(shù)。該 ID 通常需要通過其他接口（如搜索接口、商品列表接口）預先獲取。

access_token (通常必填)：用于 API 調用的訪問令牌，代表調用者的授權身份。需要通過愛回收提供的授權流程（如 OAuth 2.0）獲取。

timestamp (可能必填)：請求發(fā)起的時間戳，用于防止重放攻擊。

sign (可能必填)：根據(jù)請求參數(shù)、密鑰、時間戳等生成的簽名，用于驗證請求的合法性。簽名算法需參照官方文檔實現(xiàn)。

其他可選參數(shù)：可能包括 version（API 版本）、fields（指定需要返回的字段，用于減少響應數(shù)據(jù)量）等。

3. 響應數(shù)據(jù)結構

成功調用接口后，通常會收到一個 JSON 格式的響應。數(shù)據(jù)結構會包含商品的詳細信息，一般會分層級組織。以下是一個示意性的響應結構示例（實際字段名稱和結構請務必以官方文檔為準）：

{
  "code": 200, // 狀態(tài)碼，200 通常表示成功
  "msg": "success", // 狀態(tài)信息
  "data": {
    "product_id": "1234567890", // 商品ID
    "product_name": "Apple iPhone 13 Pro Max 256GB 遠峰藍", // 商品名稱
    "category": "手機", // 商品類目
    "brand": "Apple", // 品牌
    "model": "iPhone 13 Pro Max", // 型號
    "condition": "99新", // 成色描述
    "grade": "A", // 成色等級
    "price": 5999.00, // 當前售價 (單位：元)
    "original_price": 8799.00, // 原價/指導價
    "images": [ // 商品圖片列表
      "https://img.aihuishou.com/p1.jpg",
      "https://img.aihuishou.com/p2.jpg"
    ],
    "description": "國行全網(wǎng)通，功能正常，無拆無修，外觀輕微使用痕跡...", // 詳細描述
    "specs": { // 規(guī)格參數(shù)
      "storage": "256GB",
      "color": "遠峰藍",
      "network": "5G",
      "screen_size": "6.7英寸",
      "battery_health": "95%" // 電池健康度 (針對手機)
    },
    "service": { // 相關服務
      "has_warranty": true, // 是否有保修
      "warranty_period": "180天" // 保修時長
    },
    "stock": 1, // 庫存數(shù)量
    "status": "on_sale", // 商品狀態(tài) (如 on_sale, sold_out)
    // ... 可能還有其他字段，如標簽、優(yōu)惠信息、評分、評價數(shù)量等
  }
}

4. 錯誤處理

調用 API 時可能遇到各種錯誤。響應中的 code 字段將指示請求狀態(tài)。常見的錯誤狀態(tài)碼可能包括：

400 Bad Request：請求參數(shù)錯誤或缺失。

401 Unauthorized：訪問令牌無效或缺失。

403 Forbidden：無權限訪問該資源。

404 Not Found：指定的商品 ID 不存在。

429 Too Many Requests：請求過于頻繁，觸發(fā)了速率限制。

500 Internal Server Error：服務器內部錯誤。

開發(fā)者需要根據(jù)不同的 code 和 msg 進行相應的錯誤處理和提示。

5. 調用示例 (Python)

以下是一個使用 Python requests 庫調用該接口的示意性代碼片段（假設是 GET 請求，且簽名邏輯已封裝）：

import requests
import hashlib
import time

# 愛回收 API 配置 (需替換為實際值)
APP_KEY = "YOUR_APP_KEY"
APP_SECRET = "YOUR_APP_SECRET"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN" # 假設已獲取
BASE_URL = "https://api.aihuishou.com"
DETAIL_ENDPOINT = "/product/detail"

# 目標商品ID
product_id = "1234567890"

# 構造請求參數(shù)
params = {
    "product_id": product_id,
    "access_token": ACCESS_TOKEN,
    "timestamp": str(int(time.time())), # 當前時間戳
    # ... 其他參數(shù)
}

# 根據(jù)官方文檔要求生成簽名 (示例僅為示意，實際算法不同)
# 通常步驟：排序參數(shù) -> 拼接鍵值對 -> 拼接密鑰 -> 計算MD5/SHA等
sorted_params = sorted(params.items())
sign_str = "&".join([f"{k}{v}" for k, v in sorted_params]) + APP_SECRET
sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest()
params['sign'] = sign

# 發(fā)送請求
response = requests.get(BASE_URL + DETAIL_ENDPOINT, params=params)

# 處理響應
if response.status_code == 200:
    data = response.json()
    if data['code'] == 200:
        product_detail = data['data']
        print(f"商品名稱: {product_detail['product_name']}")
        print(f"當前價格: {product_detail['price']}")
        # ... 處理其他所需信息
    else:
        print(f"API 錯誤! Code: {data['code']}, Msg: {data['msg']}")
else:
    print(f"HTTP 請求失敗! Status Code: {response.status_code}")

6. 注意事項

官方文檔：以上內容僅為通用性指導。務必、務必、務必查閱愛回收平臺提供的最新、最權威的官方 API 文檔，以獲取準確的接口地址、參數(shù)列表、請求方式、簽名算法、響應字段定義、錯誤碼說明以及調用限制（如 QPS 限制）。

認證授權：安全地管理和刷新 access_token，避免泄露 APP_SECRET。

參數(shù)驗證：在調用前驗證請求參數(shù)的合法性。

錯誤處理：在代碼中妥善處理各種可能的錯誤響應和網(wǎng)絡異常。

數(shù)據(jù)緩存：對于不頻繁變動的數(shù)據(jù)（如商品基礎信息），可考慮在客戶端或服務端進行適當緩存，以減少 API 調用次數(shù)，但需注意緩存過期策略。

版本控制：關注 API 版本升級通知，及時調整代碼以適應新版本接口。

合規(guī)使用：遵守愛回收平臺的 API 使用條款和政策。

總結

通過愛回收的商品詳情 API，開發(fā)者可以便捷地獲取平臺上豐富的二手商品信息，為構建各種應用和服務提供數(shù)據(jù)支持。關鍵在于嚴格按照官方文檔規(guī)范進行開發(fā)，并做好認證、簽名、錯誤處理等環(huán)節(jié)，確保調用的穩(wěn)定性和安全性。

?審核編輯 黃宇