?

在電商開(kāi)發(fā)這行摸爬滾打快十年，對(duì)接過(guò)不少平臺(tái)的 API，但若說(shuō)最讓人頭疼的，1688商品詳情API絕對(duì)能排進(jìn)前三。從批發(fā)場(chǎng)景特有的數(shù)據(jù)結(jié)構(gòu)，到接口權(quán)限的嚴(yán)格管控，每一步都藏著 “驚喜”。今天就把這些年踩過(guò)的坑、攢下的實(shí)戰(zhàn)代碼分享出來(lái)，給同樣在 1688 開(kāi)發(fā)路上掙扎的朋友搭個(gè)橋。

第一次對(duì)接 1688API 時(shí)，光是申請(qǐng)權(quán)限就卡了整整五天。1688 作為批發(fā)平臺(tái)，對(duì)開(kāi)發(fā)者資質(zhì)審核格外嚴(yán)格，不僅要提供企業(yè)營(yíng)業(yè)執(zhí)照，還要詳細(xì)說(shuō)明用途 —— 是用于店鋪管理還是第三方工具開(kāi)發(fā)，甚至連預(yù)期調(diào)用量都要報(bào)備。好不容易拿到app_key和secret，簽名驗(yàn)證又給了我個(gè)下馬威。1688 的簽名算法要求把所有參數(shù)按 ASCII 排序，連時(shí)間戳格式都必須是yyyy-MM-dd HH:mm:ss，差個(gè)空格都會(huì)返回400錯(cuò)誤。那段時(shí)間對(duì)著文檔反復(fù)調(diào)試，終于寫(xiě)出能用的簽名函數(shù)：

python

運(yùn)行

import hashlib
import time
import urllib.parse

def generate_1688_sign(params, secret):
    # 按參數(shù)名ASCII排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # 拼接成key=value&key=value格式
    query_str = "&".join([f"{k}={urllib.parse.quote(str(v), safe='')}" for k, v in sorted_params])
    # 首尾加上secret
    sign_str = f"{secret}{query_str}{secret}"
    # SHA1加密后轉(zhuǎn)大寫(xiě)
    return hashlib.sha1(sign_str.encode()).hexdigest().upper()

# 使用示例
params = {
    "method": "alibaba.item.get",
    "app_key": "your_app_key",
    "item_id": "6123456789",
    "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
    "format": "json",
    "v": "1.0"
}
params["sign"] = generate_1688_sign(params, "your_secret")

解決了簽名問(wèn)題，又被 1688 特有的 “批發(fā)屬性” 坑了一把。普通電商 API 返回的價(jià)格通常是單售價(jià)，而 1688 會(huì)返回階梯價(jià)——1-10 件多少錢(qián)、10-50 件多少錢(qián)，甚至還有混批規(guī)則。有次給客戶做采購(gòu)系統(tǒng)，直接取了第一個(gè)價(jià)格字段，結(jié)果導(dǎo)致小批量采購(gòu)時(shí)報(bào)價(jià)出錯(cuò)，被運(yùn)營(yíng)追著改了一下午。后來(lái)專門(mén)寫(xiě)了個(gè)階梯價(jià)解析函數(shù)：

python

運(yùn)行

def parse_wholesale_price(price_data):
    """解析1688階梯價(jià)格"""
    try:
        prices = []
        # 1688返回的price字段是字符串格式，需要轉(zhuǎn)換
        for range_price in price_data.get("price", "").split(";"):
            if "-" in range_price:
                quantity_range, price = range_price.split("-")
                min_qty, max_qty = quantity_range.split(":")
                prices.append({
                    "min_quantity": int(min_qty),
                    "max_quantity": int(max_qty),
                    "price": float(price)
                })
        # 按起訂量排序
        return sorted(prices, key=lambda x: x["min_quantity"])
    except Exception as e:
        print(f"價(jià)格解析錯(cuò)誤: {e}")
        return []

# 示例調(diào)用
raw_price = {"price": "1:10:99;10:50:89;50:0:79"}  # 1-10件99元，10-50件89元，50件以上79元
parsed_prices = parse_wholesale_price(raw_price)

python實(shí)例點(diǎn)擊獲取key和秘鑰

"description": {
					"fields": {
						"bigPromotionBanner": {
							"bannerJumpUrl": "https://shop7586850002vz1.1688.com/page/activity.htm?offerId=724783106302#promotion",
							"bannerUrl": "",
							"hasBigPromotion": false
						},
						"detailUrl": "https://itemcdn.tmall.com/1688offer/icoss2932620515500292f66bc2481d",
						"label": "詳情描述",
						"uiType": "od_product_description"
					},
					"id": "description",
					"meta": {
						"scriptFileName": "pcOfferDetailDscDetailViewcomposer"
					},
					"position": "body",
					"tag": "description",
					"type": "od_product_description"
				},
				"discountCoupon": {
					"fields": {
						"bgColor": "#ff0e31",
						"buttonName": "領(lǐng)券",
						"couponInfoList": [
							{
								"buttonName": "領(lǐng)券",
								"displayType": "coupon",
								"extraInfo": {
									"$ref": "$.result.data.discountCoupon.fields.promotionModel.promotionList[0].extraInfo"
								},
								"name": "優(yōu)惠券",
								"promotionItems": [
									{
										"actionName": "立即領(lǐng)取",
										"applied": false,
										"applyDisplayInfo": "僅限新客戶領(lǐng)取",
										"availablePeriod": "有效期：2025.08.02 00:00:00-2025.08.31 23:59:59",
										"canApply": true,
										"couponId": 7567749995,
										"couponType": 0,
										"couponTypeName": "店鋪新寶專屬",
										"detail": "滿2元減1元",
										"displayContent": "1",
										"extendDetail": "",
										"label": "滿2減1券",
										"onlySupportMobile": false,
										"sellerId": 2215803758622,
										"showDiscountFee": true,
										"startTime": "Sat Aug 02 00:00:00 CST 2025",
										"summary": "滿2元減1元"
									}
								],
								"summary": "滿2元減1元",
								"type": "COUPON",
								"uiType": "COUPON"
							}
						],
						"couponList": [
							{
								"couponContent": "滿2減1券",
								"couponType": "COUPON"
							}
						],
						"label": "折扣優(yōu)惠",
						"linkUrl": "https://cybert.m.1688.com/43ohz283.html?sceneName=chimera_16527",
						"offerId": 724783106302,
						"pageName": "Page_GetCoupon",
						"promotionModel": {
							"buttonName": "領(lǐng)券",
							"promotionList": [
								{
									"buttonName": "領(lǐng)券",
									"displayType": "coupon",
									"extraInfo": {
										"uiType": "COUPON"
									},
									"name": "優(yōu)惠券",
									"promotionItems": [
										{
											"actionName": "立即領(lǐng)取",
											"applied": false,
											"applyDisplayInfo": "僅限新客戶領(lǐng)取",
											"availablePeriod": "有效期：2025.08.02 00:00:00-2025.08.31 23:59:59",
											"canApply": true,
											"couponId": 7567749995,
											"couponType": 0,
											"couponTypeName": "店鋪新寶專屬",
											"detail": "滿2元減1元",
											"displayContent": "1",
											"extendDetail": "",
											"label": "滿2減1券",
											"onlySupportMobile": false,
											"sellerId": 2215803758622,
											"showDiscountFee": true,
											"startTime": "Sat Aug 02 00:00:00 CST 2025",
											"summary": "滿2元減1元"
										}
									],
									"summary": "滿2元減1元",
									"type": "COUPON",
									"uiType": "COUPON"
								}
							]
						},
						"style": {
							"arrowsImg": "https://img.alicdn.com/tfs/TB19FQtP4D1gK0jSZFsXXbldVXa-26-44.png",
							"textColor": "#FF4000"
						},
						"trackInfo": [],
						"uiType": "od_discount_coupon"
					},
					"id": "discountCoupon",
					"meta": {
						"scriptFileName": "pcOfferDetailDscPromotionViewcomposer"
					},
					"position": "body",
					"tag": "discountCoupon",
					"type": "od_discount_coupon"

1688 的庫(kù)存數(shù)據(jù)也很有特色，很多商家支持 “預(yù)售” 和 “現(xiàn)貨” 混合模式，API 返回的庫(kù)存字段會(huì)區(qū)分stock（現(xiàn)貨）和book_count（預(yù)售）。有次做庫(kù)存監(jiān)控系統(tǒng)，只抓取了stock字段，導(dǎo)致預(yù)售商品顯示 “無(wú)貨”，被客戶投訴到老板那里。痛定思痛后，寫(xiě)了個(gè)庫(kù)存整合函數(shù)：

python

運(yùn)行

def parse_stock(stock_data):
    """整合1688現(xiàn)貨與預(yù)售庫(kù)存"""
    try:
        # 現(xiàn)貨庫(kù)存
        spot_stock = int(stock_data.get("stock", 0))
        # 預(yù)售庫(kù)存（部分商家可能不返回）
        pre_stock = int(stock_data.get("book_count", 0))
        # 總可售庫(kù)存
        total_stock = spot_stock + pre_stock
        return {
            "spot_stock": spot_stock,
            "pre_stock": pre_stock,
            "total_stock": total_stock,
            "is_pre_sale": pre_stock > 0
        }
    except Exception as e:
        print(f"庫(kù)存解析錯(cuò)誤: {e}")
        return {"total_stock": 0}

調(diào)用頻率限制也是個(gè)大麻煩。1688 對(duì)免費(fèi)開(kāi)發(fā)者的限流很嚴(yán)格，每分鐘最多 20 次請(qǐng)求，超過(guò)就會(huì)觸發(fā)429錯(cuò)誤。有次做批量商品采集，沒(méi)控制好節(jié)奏，直接被封了 3 小時(shí)接口權(quán)限。后來(lái)用隊(duì)列加定時(shí)任務(wù)實(shí)現(xiàn)了平滑調(diào)用：

python

運(yùn)行

import time
from queue import Queue
from threading import Thread

class APICaller:
    def __init__(self, max_calls_per_minute=20):
        self.queue = Queue()
        self.max_calls = max_calls_per_minute
        self.running = False
        self.thread = Thread(target=self._process_queue)
        
    def start(self):
        self.running = True
        self.thread.start()
        
    def stop(self):
        self.running = False
        self.thread.join()
        
    def add_task(self, func, *args, **kwargs):
        self.queue.put((func, args, kwargs))
        
    def _process_queue(self):
        while self.running:
            if not self.queue.empty():
                func, args, kwargs = self.queue.get()
                try:
                    func(*args, **kwargs)
                finally:
                    self.queue.task_done()
                    # 控制頻率：每分鐘最多max_calls次
                    time.sleep(60 / self.max_calls)
            else:
                time.sleep(1)

# 使用示例
caller = APICaller(max_calls_per_minute=20)
caller.start()
# 添加100個(gè)任務(wù)
for item_id in range(100):
    caller.add_task(fetch_product_detail, item_id)
caller.queue.join()
caller.stop()

這些年和 1688API 打交道，最大的感悟就是：批發(fā)場(chǎng)景的特殊性決定了它的數(shù)據(jù)結(jié)構(gòu)比零售平臺(tái)復(fù)雜得多。從階梯價(jià)格到混合庫(kù)存，從起訂量到混批規(guī)則，每一個(gè)字段都藏著業(yè)務(wù)邏輯。

?審核編輯 黃宇