如何使用 AI 加速 API 串接

前言

約莫是一年前開始，嘗試將 AI 整合進 API 的串接流程中，
想跟大家分享這段時間的一些嘗試與心得。

想像今天我們要幫網路賣家開發後台系統，
讓他們能同時在蝦皮、Momo、PChome 上架商品、同步庫存、撈取訂單。

聽起來很合理，但實際動手做你會發現：
每個平台的 API 都長得不一樣，做的事情很像，但格式、規則、欄位命名全都不同。

這是個典型的「重複但不簡單」的工程問題。

本文將分享如何導入 AI 輔助開發，
從 v1（claude-3.7-sonnet） 到 v2（claude-4-sonnet） 的演進過程，
讓這類工作從耗時的苦差事，變成有方法可循的流程。

---

目錄

• 前言
• 目錄
• 多平台電商串接的挑戰
• V1 階段：用 AI 加速整合
  • 問題一：文件格式不一致
  • 問題二：產生一致性的程式碼
  • 問題三：減少 AI 幻覺（Hallucination）
    • ShopeeDataDocs.md
    • DataRules.mdc（Cursor Rules 檔案）
    • prompt.md
  • 問題四：輸出 code 的品質
• 轉折
• V2 階段：更進一步的 AI 協作
  • 建立 arc42 架構文件
  • 建立整合文件（Integration Docs）
  • 為 Domain Model 加上描述
  • 其他技巧：建立串接平台的 API 文件
  • V2 的整合流程
• V1 vs V2：
• 成效比較
• 結論與心得
  • 1. Context 與 Accuracy 的平衡
  • 2. 高層次文件的重要性
  • 3. 建立自己專案或團隊的文件

---

多平台電商串接的挑戰

假設今天要串接蝦皮、Momo、PChome 三個平台，每個平台你都要做：

• 商品上架（建立商品、設定 SKU、上傳圖片）
• 庫存同步（即時更新各平台庫存數量）
• 訂單撈取（定時拉取新訂單到後台）

同樣的事情做三遍，但每家平台都有：

• 各自格式不同的 API 文件
• 不同的資料格式與欄位命名
• 各種特殊規則

目標：縮短每新增一個平台所需的時間、提升程式碼品質與一致性。

---

V1 階段：用 AI 加速整合

使用模型：claude-3.7-sonnet

問題一：文件格式不一致

痛點：

蝦皮的文件是英文 Swagger、Momo 給的是 Word 檔、PChome 只有 HTML 頁面。
格式雜亂，無法直接給 AI 閱讀。

解法：先把文件標準化成 Markdown

使用 Microsoft markitdown 的 MCP 工具，將各種格式統一轉換為 Markdown。

平台 API 文件 (Swagger / Word / HTML)
         ↓ markitdown
      統一的 Markdown 格式
         ↓
      AI 更容易理解與比對

Markdown 清楚的結構讓 AI 在解讀文件時大幅減少誤解，
也讓開發者在不同平台文件之間的比對更直觀。

---

問題二：產生一致性的程式碼

痛點： AI 的輸出品質高度依賴給予的參考檔案 (reference files)。

如果沒有範本，每次串接新平台，AI 產出的程式碼風格、結構都不一樣，
後續維護會變得很麻煩。

解法：建立標準化的範例（Standardized Platform Examples）

• 統一程式碼風格與架構（例如：Controller / Service / Proxy 的分層方式）
• 記錄最佳實踐（例如：錯誤處理、API 重試機制）
• 讓 AI 有明確的參考基準

我們建立 ExampleShop 相關的 markdown 及程式碼作為串接其他平台時的參考。

核心觀念：AI 的輸出品質取決於你給的參考品質。

ʕ •ᴥ•ʔ：你給 AI 一份好的範例程式碼，它就會照著寫。
你給它沒有規範的程式碼，它就會「自由發揮」。

---

問題三：減少 AI 幻覺（Hallucination）

痛點： AI 在填入平台特定資料時容易「捏造」不存在的資訊，尤其是：

• 商品分類代碼對應（每個平台的 category_id 定義完全不同）
• 運費計算規則
• 圖片上傳規格（尺寸、格式、大小限制）

解法：用 Markdown 補充缺失資訊，並透過規則約束 AI 行為

建立三個關鍵檔案：

ShopeeDataDocs.md

包含平台所有已確認的資訊：

• 支援的商品類別（使用 Table 格式做代碼對應）
• API Routes 清單
• 圖片規格與限制
• 手續費計算方式
• 其他平台特定規則

DataRules.mdc（Cursor Rules 檔案）

- ExampleShopData.md 是我們期望的格式範例
- 如果找不到某項資訊，請不要做任何假設，保留空白
- 商品分類代碼必須來自平台官方文件，不可自行推測
- 圖片規格若未明確標示，請標記為「待確認」

prompt.md

- Follow @DataRules.mdc
- Using @ShopeeAPI.md and save to @ShopeeDataDocs.md
- Let me know the source of the data you used for each section

• ExampleShopData.md 是前一步驟建立的格式範例，作為 AI 的輸出參考基準。
• ShopeeDataDocs.md 則是針對蝦皮平台實際填入的資料文件。

關鍵設計： 要求 AI 標示每個資料的來源，讓人工驗證有跡可循。

---

問題四：輸出 code 的品質

痛點： 準確度不夠高的原因可能是：

• 一次給 AI 的 context 太長，資訊互相干擾？
• 缺少具體、可驗證的中間結果？

舉例：如果一次叫 AI 完成「商品上架 + 庫存同步 + 訂單撈取」全部，
錯誤率很高，而且很難找出哪裡出問題。

解法：拆分成更小的範疇（Break into smaller scopes）

把整合流程拆成多個獨立步驟，每個步驟都有明確的輸入與輸出：

一次完成全部（複雜度高、容易出錯）
         ↓ 拆分
Step 1：先完成商品上架 API
Step 2：再完成庫存同步 API
Step 3：最後完成訂單撈取 API
（每步驟各自可測試、可驗證）

每個小任務完成後立刻測試，問題更容易定位。

---

轉折

原本解決輸出 code 品質時，我們懷疑是因為 context 太長導致 AI 表現變差。

但在 Tech Day 與其他工程師交流後，發現有人使用了相當長的 prompt 來執行，
也得到了不錯的結果 —— AI 能夠更完整地理解需求、輸出更符合預期的程式碼。

這讓我們重新思考：問題可能不是「context 太多」，
而是 context 給的不夠充足？

也許 AI 需要的是「更完整的背景資訊」，而不是「更簡短的指令」。

---

V2 階段：更進一步的 AI 協作

使用模型：claude-4-sonnet

建立 arc42 架構文件

在開始串接新平台之前，先讓 AI 讀懂整個系統。

arc42 是一個用於架構溝通與文件記錄的模板：

• Introduction（這個系統是做什麼的）
• System Scope and Context（系統邊界與外部依賴）
• Building Block View（模組與元件關係）
• Runtime View（實際執行時的流程）
• Glossary（重要名詞定義，例如：SKU、平台手續費等）

使用 Cursor 的 Research Mode 搭配以下 prompt：

Help me come out the detail documentation for the current project.
Refer to @https://docs.arc42.org/home/
Need to include:
- Introduction
- System Scope and Context
- Building Block View
- Runtime View
- Glossary
DONT use emoji, ONLY show fact

讓 AI 自動閱讀現有程式碼，產生完整的架構文件。

有了這份文件，後續所有 AI 的回應更符合系統整體設計。

---

建立整合文件（Integration Docs）

目標： 建立一份「如何整合新電商平台」的參考 SOP，
讓下一次串接新平台時有標準流程可循。

Prompt 設計：

Refer to @arc42.md to understand the responsibilities of this project.
Use the ExampleShop integration flow as reference:
  @ExampleShopService.cs
  @AdminExampleShopDataController.cs
  ...
The flow should cover:
  - Adding product data
  - Create listing request
  - Sync inventory
  - Fetch orders
Document the process of "How to integrate a new platform" into @platform-integration.md.
The goal is to create a reference guide for future platform integrations.

迭代過程：

1. 產生初版文件後，拿真實平台（如蝦皮）來比對差異：

Now, refer to @platform-integration.md and review the Shopee integration flow.
Tell me what is missing from the document or what differs from it.

2. 進一步泛化文件，移除平台特定名稱，讓 SOP 真正通用：

I'd like this document to not just focus on ExampleShop & Shopee (please remove those names),
but instead follow the platform's API documentation and adjust accordingly
(e.g., authentication method, product schema mapping, rate limiting rules, etc.).
How should I provide the information so that you can properly revise this document?

---

為 Domain Model 加上描述

電商系統的 domain model 往往很複雜，例如一個 Product 可能包含數十個屬性：

• spu（Standard Product Unit，標準商品單元）
• sku（Stock Keeping Unit，庫存單位）
• category_path（分類路徑）
• listing_status（上架狀態）
• …

讓 AI 為 domain model 中的每個屬性加上說明，
我們再根據實際情況作修正，
新成員就不需要靠猜測來理解每個屬性的用途。

---

其他技巧：建立串接平台的 API 文件

串接 API 時，最花時間的事之一是：手動在 Postman 建立測試請求。

透過建立 PlatformDocsRules.md，讓 AI 讀取平台的 API 文件後，
自動產生 postman_collection.json：

根據 @ShopeeAPI.md，幫我產生 Postman collection，
包含以下 API：
- 商品上架（Create Product）
- 更新庫存（Update Stock）
- 查詢訂單（Get Orders）
並填入範例參數，讓我可以直接測試。

快速得到可用的測試集，省去手動建立的時間。

ʕ •ᴥ•ʔ：我們可以在串接前先理解 API 的簽章規則，
一旦打通，後面 coding 的工作就變簡單了。

---

V2 的整合流程

V2 定義了一個更清晰的 AI 協作 SOP：

1. 取得平台 API 文件
           ↓
2. 用 AI 驗證文件內容，整理出關鍵資訊
   （有疑問的地方列入 Question_to_{Platform}.md）
           ↓
3. 確認後存入 {Platform}DataDocs.md
           ↓
4. 建立相關的 Postman Collection 測試 Platform APIs
           ↓
5. 執行整合 prompt：
   Follow @platform-integration.md
   Use @{Platform}DataDocs.md to complete the listing flow
           ↓
6. 與 AI 或團隊做 Retro
   - 更新 platform-integration.md
   - 補充範例與說明
   - 記錄這個平台的特殊規則

ʕ •ᴥ•ʔ：Question_to_{Platform}.md 的機制特別實用，
在串接前，先讓 AI 整理出「這份文件中有哪些不確定的地方」，
我們再去向平台技術支援確認，避免串接到一半才發現無法串接。

---

V1 vs V2：

V1：人帶著 AI 一起寫程式

開發者主導，遇到每個細節都跟 AI 討論。

AI 是 pair programming 的一員。

V2：人設計流程，AI 執行，最後再由人 code review

開發者專注在設計整合 SOP 和驗證結果。
AI 負責把文件轉換成程式碼，人作最後的 code review。

AI 是團隊的一員。

---

成效比較

階段	串接人數	時間
導入前	5 位開發者	每個平台約 4~5 天
V1 之後	2~3 位開發者	每個平台約 2~3 天
V2 之後	2 位開發者	每個平台約 1 天完成

---

結論與心得

1. Context 與 Accuracy 的平衡

給 AI 的 context 並非越多越好，也不是越少越好。
拆分任務、提供夠用的資訊、逐步驗證，是提升準確度的關鍵。

2. 高層次文件的重要性

有了 arc42 等架構文件，AI 能夠理解「這個系統的長相」，
而不是每次都從零開始解讀程式碼。

讓 AI 的輸出更符合整體設計，而不是隨機地參考。

3. 建立自己專案或團隊的文件

AI 模型的進步速度很快，但你必須建立好對應的 knowledge base，
才能讓 AI 發揮的更好，也可以幫助到新進的團隊成員。

---

ʕ •ᴥ•ʔ：這個做法就類似於 2025 年底 Anthropic 推出的 Agent Skills，
兩者的核心都是：把可重複使用的知識與規則整理成結構化文件，
讓 AI 每次執行時都有一致的參考基準。

目前 research mode 已演變成官方的 plan mode，
Claude Sonnet 也出到 4.6 了！