電商接入指南

本指南面向電商平台的開發者，幫助你讓用戶在 Webnav.ai 聊天助手中直接下單、查單、查物流、申請退款。

Webnav.ai 是編排層：理解用戶、抽取參數、呼叫你的工具。業務邏輯、資料與資金完全由你掌控，Webnav.ai 從不儲存你的訂單或客戶。

接入模型： Webnav.ai 透過 JSON-RPC 2.0 over HTTP 連接你的 MCP（Model Context Protocol） 工具伺服器。Webnav.ai 是 MCP 用戶端，你是 MCP 伺服器。
你需實作： 一個 HTTP 端點，處理 initialize、tools/list、tools/call。
你需設定： 在 Dashboard → AI Actions 配置 MCP 端點（與可選的鑑權標頭）。

本頁為高層概覽。完整通訊協議、工具欄位規格與後台步驟，請見 MCP 接入指南。接入清單與需交付給 Webnav.ai 的內容，請見 MCP 接入交付包。

1. 架構

┌─────────┐   提問     ┌───────────────┐  JSON-RPC 2.0   ┌──────────────┐
│  訪客   │ ────────► │  Webnav.ai    │ ──────────────► │  你的 MCP     │
│ (widget)│ ◄──────── │  (MCP 用戶端) │ ◄────────────── │  伺服器       │
└─────────┘  回覆      └───────────────┘   工具結果        └──────────────┘

訪客發送訊息。
Webnav.ai 發現你的工具（tools/list），選定其一並抽取參數。
透過 tools/call 對你的 MCP 端點呼叫該工具。
你的伺服器執行操作並回傳結果。
LLM 把結果轉成自然語言（並可附 UI 卡片）。

寫工具（create_order、create_refund）在第 3 步前會加入確認步驟——訪客必須點確認才會執行任何操作。

2. 五個 canonical 電商工具

以下是 Webnav.ai 原生識別的工具。建議全部實作以獲得完整支援，也可只做子集。

工具	類型	需確認	用途
`list_products`	讀	否	回傳商品目錄（用於 SKU 校驗）
`query_order`	讀	否	查訂單狀態／詳情
`query_logistics`	讀	否	查物流軌跡
`create_order`	寫	是	下新訂單——所有商品放進一個 `items[]` 一次提交
`create_refund`	寫	是	發起退款申請

list_products 在顯示寫操作確認卡片前由 Webnav.ai 內部使用：若訪客要求的 SKU 不在你的商品目錄中，助手會提示其選擇真實商品，而不是為無效 SKU 顯示確認卡片。

create_order 接受多商品 items[] 陣列——訪客可在一次對話中購買多件商品，Webnav.ai 會一次性呼叫 create_order 並帶入所有商品，只彈一張確認卡片。

回傳格式——回傳 canonical { ok, data, display }（卡片更豐富）或標準 MCP { content, isError } 區塊。業務錯誤用 { ok: false, error_code, message }，採用描述性碼（ORDER_NOT_FOUND、OUT_OF_STOCK、SKU_NOT_FOUND）。完整欄位規格與 JSON 範例見 MCP 接入指南 → 工具規格。

3. 確認流程（寫工具）

LLM 收集參數 → Webnav.ai 建立待確認動作 → widget 顯示 確認／取消
   → 訪客點確認 → Webnav.ai 僅呼叫工具一次 → 結果卡片

Webnav.ai 以三個訊號 OR 判定某工具為寫操作——寫工具絕不會被意外略過：

你的 tools/list 回應中 annotations.destructiveHint: true，或
工具名匹配 create_*、refund_*、cancel_*、pay_*，或
該工具在商家於後台配置的 確認工具 清單中。

讀工具（readOnlyHint: true）直接呼叫、不彈卡。

待確認動作為單次使用、限時，且綁定該訪客——無法被重放或被他人確認。仍請將寫工具設計為冪等（用冪等鍵），確保網路重試絕不會建立第二筆訂單或退款。

4. 安全

要求	原因
於公網主機使用 HTTPS	Webnav.ai 綁定解析 IP 並拒絕私網／環回／元數據位址（SSRF 防護）。
驗證鑑權標頭	以鑑權標頭傳遞 bearer token 或 API key，並在每次請求時驗證。
寫工具冪等	Webnav.ai 只發一次已確認的呼叫，但網路重試可能發生。
`list_products` 回傳真實商品目錄	在彈確認卡前會以它校驗每個 SKU。

MCP 模式下，後台「測試連接」探測一律透過 Webnav.ai 後端代理發出——你的端點不會被瀏覽器直接訪問。

5. 下一步

MCP 接入指南——完整通訊協議（initialize / tools/list / tools/call）、逐工具欄位規格、annotations、錯誤歸一化、後台配置與 demo MCP 伺服器。
MCP 接入交付包——接入清單、硬性要求與上線驗收清單。
AI Actions——面向商家的動作、確認與呼叫日誌概覽。

電商接入指南 ​

1. 架構 ​

2. 五個 canonical 電商工具 ​

3. 確認流程（寫工具） ​