Shopee 香港與台灣雙平台同步管理教學：庫存、訂單與自動化

若要同步管理 Shopee 香港與台灣店鋪，核心是建立「單一商品主檔 + 中介層」：以 SKU 為唯一識別碼，透過 Shopee Open Platform API 分別為 HK、TW 兩個 region 取得 access token，再用 webhook 與定時任務雙軌同步庫存與訂單，避免超賣。

為什麼 Shopee 的「跨站點」不等於「同步」？

Shopee 對賣家提供兩種跨境模式：一種是 Shopee 國際平台（SIP, Shopee International Platform），由 Shopee 主動把主站商品複製到其他站點並代為翻譯、物流；另一種是賣家自行在各站點開設本地店鋪（Local Seller），各自獨立營運。

兩者的管理邏輯完全不同：

• SIP 模式：主站（多為 TW 或 SG）為母店，子店庫存由 Shopee 自動帶動，賣家在子站幾乎無法直接改價改量。根據 Shopee Open Platform 官方文件，SIP 子店的 item 相關寫入 API 多數會回傳權限錯誤。
• 本地店鋪模式：HK 與 TW 各自是獨立 shop_id，各自有獨立的 access token、獨立的商品 ID、獨立的運費範本與結算幣別（HKD / TWD）。這種情況下，「同步」必須由賣家自己做。

本篇教學聚焦第二種：你在香港與台灣各有一間自營 Shopee 店鋪，需要一套同步機制。

亞太區的賣家會遇到這個題目，通常是因為市場結構。根據 Shopee 母公司 Sea Limited 於 2024 年財報揭露，Shopee 的 GMV 主要來自東南亞與台灣市場，而台灣長期是其單一市場中客單價較高的區域之一；香港則規模較小但物流半徑短、跨境清關相對單純。對歐美品牌而言，以香港作為結算與營運中心、台灣作為量體市場，是常見的亞太佈局。

開始之前需要準備什麼？

帳號與權限

1. 兩個已通過認證的 Shopee 賣家帳號（HK region、TW region）。
2. 一個 Shopee Open Platform 開發者帳號，於 https://open.shopee.com 申請。
3. 建立一個 App，取得 partner_id 與 partner_key。注意：Shopee 的 test 環境與 live 環境 partner_id 不同，且 API host 也不同。
4. 在 App 設定中加入 redirect URL（授權回呼網址），必須是 HTTPS。

技術環境

• Python 3.10+ 或 Node.js 18+（本文以 Python 示範）
• 一個可公開存取的 HTTPS endpoint（接收 webhook 與授權回呼）
• 一個資料庫（PostgreSQL / MySQL）存放 SKU 主檔與 token
• Redis 或同等的鎖機制（處理併發扣庫存）

商業前置作業

這一步比寫 code 更容易出錯：

• 統一 SKU 命名規則。HK 與 TW 的商品若用不同內部編號，後面所有同步邏輯都會崩。建議採用 品牌-品類-款號-顏色-尺寸 的結構，例如 BR8-TEE-1042-BLK-M。
• 確認稅務與幣別。Shopee TW 以 TWD 結算，HK 以 HKD 結算。價格同步不能直接複製數字，必須走定價規則（見後文）。
• 確認是否共用同一批實體庫存。若 HK 與 TW 各自有倉，則是「獨立庫存」；若共用一個第三方倉（如香港或深圳倉出貨到兩地），則是「共享庫存池」，這是超賣風險最高的情境。

如何完成 HK 與 TW 的雙店授權？

Shopee 的授權流程是 OAuth-like，但簽章方式特殊：每個 API 呼叫都要用 HMAC-SHA256 產生 sign。

第一步：產生授權連結

不同 region 使用不同的 API host。根據 Shopee Open Platform 文件，正式環境主機為 https://partner.shopeemobile.com，而中國大陸部署的賣家另有獨立 host。授權連結需要對 partner_id + path + timestamp 做簽章：

1import hashlib, hmac, time, urllib.parse
2
3PARTNER_ID = 1012345
4PARTNER_KEY = b"your_partner_key_here"
5HOST = "https://partner.shopeemobile.com"
6PATH = "/api/v2/shop/auth_partner"
7REDIRECT = "https://ops.example.com/shopee/callback"
8
9def auth_url():
10    ts = int(time.time())
11    base = f"{PARTNER_ID}{PATH}{ts}".encode()
12    sign = hmac.new(PARTNER_KEY, base, hashlib.sha256).hexdigest()
13    qs = urllib.parse.urlencode({
14        "partner_id": PARTNER_ID,
15        "timestamp": ts,
16        "sign": sign,
17        "redirect": REDIRECT,
18    })
19    return f"{HOST}{PATH}?{qs}"
20
21print(auth_url())

預期輸出：

1https://partner.shopeemobile.com/api/v2/shop/auth_partner?partner_id=1012345&timestamp=1767225600&sign=9f3c...

用 HK 帳號登入並授權一次，再用 TW 帳號登入並授權一次。回呼網址會收到 code 與 shop_id。

第二步：換取 access token 並分區儲存

1import requests
2
3def get_token(code: str, shop_id: int):
4    path = "/api/v2/auth/token/get"
5    ts = int(time.time())
6    sign = hmac.new(PARTNER_KEY,
7                    f"{PARTNER_ID}{path}{ts}".encode(),
8                    hashlib.sha256).hexdigest()
9    r = requests.post(
10        f"{HOST}{path}",
11        params={"partner_id": PARTNER_ID, "timestamp": ts, "sign": sign},
12        json={"code": code, "shop_id": shop_id, "partner_id": PARTNER_ID},
13        timeout=15,
14    )
15    return r.json()

回傳結構大致如下：

1{
2  "access_token": "xxxxxxxxxxxxxxxx",
3  "refresh_token": "yyyyyyyyyyyyyyyy",
4  "expire_in": 14400,
5  "request_id": "a1b2c3"
6}

關鍵提醒：access_token 有效期為 4 小時（14400 秒），refresh_token 效期較長但一經使用即輪替。務必在資料庫中以 (region, shop_id) 為主鍵儲存，並設定排程在到期前 30 分鐘自動更新：

1CREATE TABLE shopee_tokens (
2  region        VARCHAR(4)  NOT NULL,   -- 'HK' | 'TW'
3  shop_id       BIGINT      NOT NULL,
4  access_token  TEXT        NOT NULL,
5  refresh_token TEXT        NOT NULL,
6  expires_at    TIMESTAMPTZ NOT NULL,
7  PRIMARY KEY (region, shop_id)
8);

我們在為一家港台雙市場經營的美妝代理商建置中介層時，最常見的事故不是 API 寫錯，而是 refresh token 被兩個 worker 同時使用導致整條授權失效。解法是把 refresh 動作放進單一 cron job，並加上資料庫 row lock。

商品主檔該怎麼設計才不會越同步越亂？

不要讓 HK 店鋪的商品去「對應」TW 店鋪的商品。正確做法是建立第三方主檔（Master Product），兩邊都只是它的投影。

三層資料結構

第一層：Master SKU

• sku_code（唯一）
• base_cost_hkd
• weight_g、dimensions
• stock_pool_id（共享庫存池識別）

第二層：Region Listing

• sku_code + region
• shopee_item_id、shopee_model_id
• title_zh_hk / title_zh_tw（文案不同，不只是繁簡差異）
• price_override（可為 null，null 則走定價規則）
• is_active

第三層：同步日誌

• 每次寫入 Shopee 的 request/response 全留存，含 request_id。Shopee 技術支援幾乎一定會跟你要 request_id。

香港與台灣的文案不能直接複製

這是很多團隊低估的地方。港台雖同用繁體中文，但用詞差異實際存在：香港慣用「平」「筍貨」「免運」，台灣則是「便宜」「超值」「免運費」；尺寸標示、電壓規格、保養條款也不同。直接複製貼上會明顯降低轉換。

實務上可以用 LLM 做首輪在地化改寫，再由本地編輯複核。以下是一個可行的 prompt 骨架：

1你是台灣電商文案編輯。以下是香港 Shopee 商品標題與賣點，
2請改寫為台灣消費者習慣的用語，保留規格數字不變，
3標題不超過 60 字元，不得使用誇大用語。
4---
5{hk_title}
6{hk_bullets}

重點是不要讓 LLM 碰規格數字。把尺寸、容量、保固月數從 prompt 中抽離成固定欄位，僅讓模型處理形容語句。

庫存同步要怎麼做才不會超賣？

這是雙平台管理的核心風險。Shopee 沒有跨站點共用庫存的原生機制（SIP 除外），所以必須由中介層分配。

策略一：固定配額（Fixed Allocation）

把庫存池切成固定比例，例如 HK 30% / TW 70%。

• 優點：零超賣風險，實作最簡單。
• 缺點：一邊缺貨另一邊壓貨，資金效率差。
• 適用：季節性低、銷量穩定的常備品。

策略二：共享池 + 安全水位（Shared Pool with Buffer）

兩邊都看到 可售量 = 實際庫存 - 安全水位，任一邊成交就立即扣減並推送到另一邊。

• 優點：資金效率高。
• 缺點：有同步延遲窗口，低庫存時風險陡增。
• 適用：高流轉商品，且有可靠的 webhook。

策略三：混合制

庫存 > 20 件走共享池；≤ 20 件自動切回固定配額。這是多數港台雙店賣家的實務選擇。

扣庫存的實作

1import redis
2r = redis.Redis()
3
4BUFFER = 3  # 安全水位
5
6def reserve(sku: str, qty: int) -> bool:
7    lock = r.lock(f"lock:sku:{sku}", timeout=5)
8    if not lock.acquire(blocking=True, blocking_timeout=3):
9        raise RuntimeError("lock timeout")
10    try:
11        available = int(r.get(f"stock:{sku}") or 0) - BUFFER
12        if available < qty:
13            return False
14        r.decrby(f"stock:{sku}", qty)
15        enqueue_push(sku)   # 推送新庫存到 HK 與 TW
16        return True
17    finally:
18        lock.release()

推送庫存到 Shopee 使用 /api/v2/product/update_stock：

1def push_stock(region: str, item_id: int, model_id: int, qty: int):
2    tok = load_token(region)
3    path = "/api/v2/product/update_stock"
4    ts = int(time.time())
5    base = f"{PARTNER_ID}{path}{ts}{tok.access_token}{tok.shop_id}".encode()
6    sign = hmac.new(PARTNER_KEY, base, hashlib.sha256).hexdigest()
7    payload = {
8        "item_id": item_id,
9        "stock_list": [{
10            "model_id": model_id,
11            "seller_stock": [{"stock": qty}]
12        }]
13    }
14    return requests.post(f"{HOST}{path}", params={
15        "partner_id": PARTNER_ID, "timestamp": ts, "sign": sign,
16        "access_token": tok.access_token, "shop_id": tok.shop_id,
17    }, json=payload, timeout=15).json()

注意簽章 base string 在「需要授權的 API」中要多串 access_token 與 shop_id，這是初次接 Shopee API 最常見的錯誤來源。

訂單同步與對帳怎麼處理？

雙軌：Webhook 為主，輪詢為輔

Shopee Open Platform 提供 push mechanism，可訂閱 order_status_push（code 3）等事件。但網路不可靠，必須加上輪詢補漏：

1from datetime import datetime, timedelta
2
3def poll_orders(region: str):
4    tok = load_token(region)
5    now = int(time.time())
6    params = {
7        "time_range_field": "update_time",
8        "time_from": now - 900,      # 回看 15 分鐘
9        "time_to": now,
10        "page_size": 50,
11        "order_status": "READY_TO_SHIP",
12    }
13    # ... 簽章與請求同前

建議排程：每 5 分鐘輪詢一次，回看視窗 15 分鐘，形成三倍重疊。所有訂單以 order_sn 做 upsert，天然冪等。

幣別與對帳

HK 店結算 HKD、TW 店結算 TWD。對帳時建議：

1. 以下單當日的匯率鎖定記帳匯率，不要用結算日匯率，否則毛利分析會抖動。
2. 分開記錄 Shopee 手續費、金流費、活動補貼，各站點費率結構不同。
3. 保留 escrow 明細（/api/v2/payment/get_escrow_detail），這是唯一能對上實收金額的來源。

定價規則而非價格複製

1FX = {"HKD_TWD": 4.05}   # 由每日排程更新
2
3def tw_price(cost_hkd: float, margin: float = 0.45) -> int:
4    raw = cost_hkd / (1 - margin) * FX["HKD_TWD"]
5    # 台灣市場心理價位：進位到 9 結尾
6    return int(raw // 10 * 10 + 9)

匯率來源建議用中央銀行或可稽核的公開來源；香港金融管理局與台灣中央銀行都公布每日參考匯率。

常見錯誤與排除方法

error_sign / Invalid signature

九成是 base string 組錯。檢查順序：

1. 公開 API：partner_id + path + timestamp
2. 店鋪 API：partner_id + path + timestamp + access_token + shop_id
3. path 必須包含 /api/v2 前綴，且不含 query string
4. 伺服器時間偏移超過 5 分鐘會被拒絕，請確認 NTP：

1timedatectl status | grep "System clock synchronized"

error_auth / Token expired

檢查是否兩個 region 的 token 被寫進同一筆記錄。這在用全域變數快取 token 的實作中極常發生。

error_param：model_id 不存在

有多規格（variation）的商品必須用 model_id 更新庫存，不能用 item_id。先呼叫 /api/v2/product/get_model_list 取得對應關係並快取。

庫存更新成功但前台沒變

Shopee 前台有快取，且若商品處於活動（Flash Sale、商城活動）中，庫存可能被活動鎖定。檢查 item_status 與是否有進行中的促銷。

Rate limit

Shopee Open Platform 對各 API 有呼叫頻率限制。實作時務必：

• 使用批次 API（如 get_item_base_info 一次可帶多個 item_id）
• 對 429 / error_rate_limit 做指數退避（exponential backoff），初始 2 秒、上限 60 秒
• 庫存推送做合併：同一 SKU 在 10 秒內的多次變動只送最後一次

自動化能幫你省下哪些人力？

雙平台管理真正耗時的不是 API，而是重複性判斷。目前較成熟、可用 LLM 或規則引擎處理的環節包括：

• 文案在地化初稿：港版轉台版、台版轉港版，人工只做複核。
• 客服回覆草稿：Shopee Chat API 可取得對話，由模型產生草稿、客服一鍵送出。注意：涉及退換貨承諾、價格讓步的訊息不應自動送出。
• 異常訂單分類：把備註、地址、金額異常的訂單自動分流，而非人工逐筆看。
• 庫存預測：用兩站點的歷史銷量推估配額，每週調整一次比每日調整穩定。

根據麥肯錫 2024 年《The State of AI》調查，多數導入生成式 AI 的企業將其用於行銷文案與客戶服務這兩類高重複性任務——電商營運的情況與此一致。務實的期待是：AI 處理初稿與分類，人處理例外與承諾。

一個可落地的自動化清單

1. 每 4 小時：token 自動 refresh（單一 worker + row lock）
2. 每 5 分鐘：雙站訂單輪詢補漏
3. 即時：webhook 觸發庫存重算與雙向推送
4. 每日 02:00（HKT）：匯率更新 + 定價規則重算 + 價格差異報表
5. 每日 03:00：escrow 明細抓取與對帳差異告警
6. 每週一：庫存配額依上週銷售重新分配

跨境營運的團隊配置考量

港台雙平台的難點之一是時區與語境。台灣的促銷節奏（雙 11、618、各式商城活動）與香港的消費旺季（農曆新年、暑假）並不完全重疊，客服高峰也不同。

對歐美品牌而言，比較務實的結構是：以香港作為結算、法務與供應商管理中心，台灣端配置熟悉本地平台規則與消費語境的營運人員，技術中介層則可由新加坡、台灣或越南的工程團隊維護——UTC+7 至 UTC+8 的時區帶本身就能覆蓋歐洲早班與美西晚班的交接窗口。

重點不是找最便宜的人，而是把「需要本地語境判斷」的工作留在本地，把「可標準化」的工作放進系統。

如果你正在規劃 Shopee 港台雙站同步、或需要把 Shopee 與既有 ERP、Shopify、倉儲系統打通，Branch8 在香港、台灣、新加坡與越南都有交付團隊，熟悉亞太各站點的平台規則與跨境結算實務——歡迎與我們談談你目前的架構與瓶頸。

Sources

• Shopee Open Platform — Developer Documentation
• Sea Limited — Investor Relations
• McKinsey — The State of AI
• Hong Kong Monetary Authority
• Central Bank of the Republic of China (Taiwan)
• Redis — Distributed Locks Documentation
• Python Requests — Documentation