ConnectWiz + API & Webhooks
已上線的整合我們賣的 API，就是我們自己在用的 API
整個平台由同一份 OpenAPI 合約定義，我們自己的後台和行動 App 都是從它產生的——沒有影子端點，文件也不會和實作分岔。在這之上：有範圍限制的 Commerce API 金鑰、加了防護的 Webhook 觸發器，以及會去呼叫您系統的 Flows。
開發者
它到底能做什麼
唯一具權威性的合約
單一份 OpenAPI 3 文件定義了整個平台；我們自己的 TypeScript 用戶端就是從它產生的——文件不可能和現實分岔，因為現實是照文件蓋的。
Commerce API 金鑰
由租戶自行核發、權限範圍明確的金鑰——商品目錄讀取、訂單讀取、訂單寫入——讓您自己的商店前台或 App 跑在同一套訂單引擎上，價格一律在伺服器端解析。
入站 Webhook，已加固
每一個 flow 的 Webhook 觸發器都有自己的網址和密鑰，對原始內容做 HMAC 驗證，並具備重放保護。內容可以指名某個人；但永遠無法操控 flow 的內部運作。
出站走 Flows
REST 步驟會在您於畫布上畫定的那個時間點呼叫您的系統——訂單成立、取得同意、預約完成。
技術細節
API 的設計立場，寫清楚
價格永遠不從用戶端來
一筆訂單請求只說買什麼、買幾個——名稱和價格是當下在伺服器端從商品目錄讀出來，再以快照寫到品項上。被竄改的請求變不出折扣。
先問能力，再發請求
每一個整合介面都會公布一份能力合約——它能不能用電話比對？能不能列出訪客訂單？能不能建立訂單？——明說「不行」還硬呼叫，會立刻拋出錯誤，而不是在很深的地方才失敗。
有意義的錯誤
傳輸層會分辨「未授權」和「服務掛了」——所以「這家店連不上」永遠不會被畫成「這位客戶從來沒買過東西」。有名字的錯誤，就是 API 和猜謎遊戲的差別。
防重放的 Webhook
每一筆入站事件在處理之前，都會先到冪等帳本裡認領一把唯一的鍵——重試或重放送來的請求會死在資料庫層，而不是死在您的自動化裡。
金鑰做雜湊，密鑰有範圍
API 金鑰以雜湊形式存放，進門時只解析得出雜湊值和權限範圍——外洩的一列資料指不出任何工作區，也解不開權限範圍以外的東西。
草稿和確認都是明寫的
建立訂單時要帶一個明確的 confirm 參數——公開 API 預設為已確認，後台流程則可以先留草稿——所以「這張是不是真的？」是一個欄位，不是一個默契。
設定方式
串接方式
核發金鑰
在後台建立一把有範圍限制的 Commerce API 金鑰；要撤銷也一樣容易。
接上 Webhook
建立一個帶 Webhook 觸發器的 flow，再用它的密鑰簽署請求。
再呼叫出去
在您的系統需要知道的地方，加上 REST 步驟。
搭配起來更好用
能和什麼搭配
安全與保證
無聊但管用的保證
對原始內容做 HMAC
Webhook 驗證會用每個觸發器專屬的密鑰簽署原始請求內容，並以定時方式比對——證明成立之後才開始解析。
內容是資料，永遠不是命令
一份 Webhook 內容可以指涉某個人；但它永遠無法操控 flow 的內部運作、改寫提示詞或呼叫工具。資料和指令之間的界線寫在架構裡，不是靠行為自律。
每一道門都有流量限制
公開端點都走標準節流，讀取筆數也在伺服器端夾住——行為不良的用戶端只會拖垮自己，拖不垮平台。
不加修飾的細則
邊界，寫清楚
還沒有全量事件流
那種「訂閱全部」的通用 Webhook 事件流還沒做——目前的出站事件都走 flow 步驟。寫在這裡，這樣就不必靠業務電話去暗示別的。
讀取有上限，這是設計
讀取最多回傳 100 筆並提供游標——這個 API 是為營運整合而做，不是為大量匯出。大量的需求請直接談，不是拿來鑽的漏洞。