4.3 現代商業的通用語言:API、RESTful、Webhooks 與 JSON

🏆 CRM 旗艦專案・Lead-to-Cash:從商機到訂單 本節產出:一套 Google 試算表 CRM(客戶、商機漏斗、拜訪日誌、儀表板),業務按下「贏單」時自動把訂單送進第 4.2 節的 ERP,庫存不夠就拒單並說明原因。

學完本節,你能夠:

  1. 讀懂一段 JSON,說出 {}、[]、鍵與值各代表什麼。
  2. 用 HTTP 動詞與狀態碼,判斷一次系統對接「做了什麼、成功了沒、錯在哪一方」。
  3. 把「贏單就自動下單」寫成含例外的規格,讓 CRM 與 ERP 用同一種資料格式對接,並親手驗證它擋得住哪些錯誤。

壹、開場情境:業務贏了,倉庫輸了

📌 以下為教學情境(依外貿實務改編)。

張業務談了兩個月,柏林的經銷商終於點頭:人體工學鍵盤 A款 100 台,金額 NT$ 420,000。他在 CRM 裡把商機改成「贏單」,開心地回覆客戶「兩週內出貨」。

三天後倉管才看到業務手寫的出貨便條:倉庫只有 50 台。

部門 他看到的系統 他知道的事 他不知道的事
業務 CRM(商機漏斗) 客戶要 100 台、願付 NT$ 420,000 倉庫只有 50 台
倉管/會計 ERP(庫存主檔、銷售訂單) 庫存 50 台 有一張 100 台的單已經答應客戶了

兩邊的資料都正確,問題出在兩個系統之間沒有對接,資訊靠人搬,搬的速度永遠趕不上業務對客戶的承諾。

本節要解決的問題: 業務按下「贏單」的那一刻,能不能讓 ERP 立刻建立銷售訂單、檢查庫存;庫存不夠就當場拒單,讓業務在回覆客戶之前就知道?


貳、為什麼會這樣:系統之間需要一種共同語言

台灣和巴西的貿易商談生意,通常用英語溝通。CRM、ERP、物流商、銀行、海關的系統各自用不同語言、在不同年代寫成,要交換資料,也得約定共同的格式與規則:

名詞 白話解釋 類比
API(應用程式介面) 一個系統開放給別的系統呼叫的「窗口」,規定可以送什麼、會拿回什麼 銀行櫃檯:照規定填單,櫃員就照規定辦
JSON 資料長什麼樣子:用「鍵:值」記錄資料的純文字格式 標準化的申請表格
REST(RESTful 架構) 怎麼提出要求:用網址指定對象、用 HTTP 動詞表達動作 「到 3 號櫃檯(網址)辦理開戶(動詞)」

1. JSON:一眼看懂資料包

CRM 要交給 ERP 的訂單資料,寫成 JSON 長這樣:

{
  "customer": "德國柏林跨國經銷 GmbH",
  "item": "人體工學鍵盤 A款",
  "quantity": 100,
  "unitPriceTwd": 4200
}
符號 意思 本例
{ } 一個物件(一筆資料) 一張訂單
"鍵": 值 一個欄位:欄位名稱與內容 "quantity": 100 數量 100
"文字" 與數字 文字要加引號,數字不用 "item" 是文字,4200 是數字
[ ] 清單,可以放多筆資料 若一張訂單有多個品項,就寫成 "items": [ {...}, {...} ]

商管人不必會寫 JSON,但要看得懂:對接出錯時,第一步就是檢查送出去的欄位名稱與數字。

2. REST:用動詞表達商業意圖

HTTP 動詞 商業意圖 外貿範例
GET 查詢(不改任何資料) GET /orders/SO-881 查這張訂單的狀態
POST 新增 POST /orders 建立一張新訂單
PUT/PATCH 修改 PATCH /orders/SO-881 修改送貨地址
DELETE 刪除/取消 DELETE /orders/SO-881 取消尚未付款的訂單

系統處理完會回傳一個三位數的狀態碼,經理人看狀態碼就能判斷問題出在哪一方:

狀態碼 意思 誰要處理
200/201 成功(201 表示已建立新資料) —
400 送來的資料有誤(例如漏填欄位、數量為負) 呼叫方:修正資料
401/403 未登入或沒有權限(401 未驗證身分;403 身分正確但無權限) 呼叫方:檢查金鑰與權限
404 找不到資源(例如訂單編號不存在) 呼叫方:檢查編號
429 請求太頻繁,被對方限流 呼叫方:降低頻率
500 對方系統內部出錯 對方:通知供應商

3. 輪詢 vs. Webhook:誰主動開口?

輪詢(Polling) Webhook(事件通知)
做法 我方定時去問:「貨到了沒?」 事先留下一個網址,事情發生時對方主動送資料過來
類比 每小時打電話問郵局 留手機號碼,包裹到了郵局傳簡訊
延遲 最長等一個詢問間隔(每小時問一次,最多晚約 1 小時才知道) 事件發生後幾乎立即通知
成本 多數詢問的答案是「還沒」,浪費呼叫次數,太頻繁還會被限流(429) 只有事件發生時才傳送;但要驗證通知真的來自對方(如數位簽章)

n8n、Make 常用 Webhook 作為流程起點(第 4.2 節)。本節「贏單 → 建單」是同樣的精神:事件一發生,就主動通知下一個系統。


參、把規則寫下來:「贏單就自動下單」

老闆說:「業務贏單,ERP 就要自動開訂單。」這句話藏了很多沒說清楚的地方:

老闆說的話 需要追問的問題 寫成規格
「贏單」 什麼狀態才算? 商機階段為 「5-Won 贏單成交」 時觸發(直接登錄為贏單,或在入口網頁按「贏單」)
「品項帶過去」 CRM 寫的是自由文字,ERP 要精確品名,怎麼對? 依關鍵字 A款/B款/C款 對應 ERP 庫存主檔的品名;對不到或同時對到兩個 → 不送 ERP,提示業務修正
「數量照業務寫的」 寫在哪裡?寫錯怎麼辦? 從品項說明抓「數字+台」,例如「(100台)」;抓不到 → 不送 ERP,不得自行假設數量
「價格」 CRM 只有商機總額 單價 = 預估金額 ÷ 數量,四捨五入到整數台幣
「庫存不夠再說」 誰判斷?判斷完通知誰? 由 ERP 判斷(沿用第 4.2 節防超賣規則):不夠就拒單、不扣庫存,CRM 當場顯示原因;商機仍記為贏單,由業務與採購協調交期
(老闆沒說) 同一張單被送兩次怎麼辦? 「商機漏斗」I 欄記錄 ERP 回傳的訂單編號;I 欄已有編號的商機不再送 ERP。ERP 拒單時 I 欄留空,補貨後可以再轉一次(見第伍段實驗④)

肆、讓 AI 做出來

1. 系統長這樣:四張 CRM 工作表

CRM 與第 4.2 節的 ERP 放在同一份試算表。ERP 分頁不變,CRM 新增四張:客戶主檔(客戶編號、公司名稱、聯絡人、國家、信箱、評級、負責業務,共 7 欄)、商機漏斗(9 欄,見下表)、拜訪跟進日誌(6 欄,到期自動寄 Gmail 提醒)、銷售總監儀表板(自動產生)。

商機漏斗 初始化後的內容:

A 商機編號 B 客戶名稱 C 採購意向品項 D 預估金額 (TWD) E 商機階段 F 成單機率 G 預估結案日期 H 加權期望營收 (TWD) I ERP 訂單編號
DEAL-2026-001 德國柏林跨國經銷 GmbH 人體工學鍵盤 A款 (100台) 420,000 4-商務談判 80% 2026-10-15 336,000
DEAL-2026-002 荷蘭鹿特丹 3C 集團 B.V. 無線雙模鍵盤 B款 (50台) 306,000 3-方案報價 60% 2026-10-30 183,600
DEAL-2026-003 法國巴黎生活選物 SAS 靜電容旗艦鍵盤 C款 (20台) 170,000 2-需求確認 30% 2026-11-15 51,000

加權期望營收 = 預估金額 × 成單機率。I 欄一開始是空的,贏單並由 ERP 建單成功後,才寫入 ERP 回傳的訂單編號。各階段機率(程式最上方的常數 STAGE_PROBABILITY,全系統只有這一份,入口網頁的下拉選單也從這裡讀):1-初步接洽 10%、2-需求確認 30%、3-方案報價 60%、4-商務談判 80%、5-Won 贏單成交 100%、6-Lost 輸單關閉 0%。

初始化後,儀表板會顯示:

指標 數值 算法
全管線商機總額 NT$ 896,000 420,000 + 306,000 + 170,000
加權預測營收 NT$ 570,600 336,000 + 183,600 + 51,000
贏單率 0.0%(0/3 筆) 贏單筆數 ÷ 全部商機筆數;目前還沒有任何一筆贏單

⚠️ 注意指標的定義:程式的「贏單率」分母是全部商機(含進行中);業界常用「贏單 ÷(贏單 + 輸單)」。「加權預測營收」沒有篩選月份,是全部商機的加權合計,所以儀表板標籤寫成「加權預測營收 (全部商機)」。看儀表板之前,先確認每個數字的分母與範圍。

2. 最小必要概念:同一份試算表裡,資料怎麼「送過去」?

第 4.2 節的 ERP 已經有一個函式 apiSubmitSalesOrder(data),業務入口網頁就是靠它下單。它接收的資料正是第貳段那個 JSON 形狀的物件:{ customer, item, quantity, unitPriceTwd },回傳 { success: true/false, ... }。

所以 Lead-to-Cash 很單純:CRM 把贏單整理成同樣形狀的資料,交給 ERP 的同一個函式;檢查庫存、扣庫存、寫訂單都由 ERP 負責。

sequenceDiagram participant S as 業務(CRM 入口網頁) participant C as CRM:syncDealToERP_ participant E as ERP:apiSubmitSalesOrder S->>C: 按「贏單」(DEAL-2026-001) C->>C: 解析品項與數量,不清楚就停止 C->>E: { customer, item, quantity, unitPriceTwd } E->>E: 檢查庫存(防超賣) alt 庫存足夠 E-->>C: success: true,訂單編號、剩餘庫存 C-->>S: ✅ ERP 已建單(I 欄寫入訂單編號) else 庫存不足 E-->>C: success: false,原因 C-->>S: 🛑 ERP 拒單,未建立訂單(I 欄留空) end

💡 兩個系統若在不同檔案? CRM 就要用 HTTP POST 把同一份 JSON 送到 ERP 的網址;ERP 的 doPost() 就是這個入口,第 8.3 節說明如何把試算表發布成 API。資料形狀不變,變的只是「怎麼送」。

3. 給 AI 的 Prompt

你是熟悉 Google Apps Script 的商業系統工程師。同一個專案中已有 ERP 程式,
其中函式 apiSubmitSalesOrder(data) 接收 { customer, item, quantity, unitPriceTwd },
回傳 { success, orderId, item, quantity, remainingStock } 或 { success: false, error }。

【資料】
「商機漏斗」的「採購意向品項」是自由文字,例如「人體工學鍵盤 A款 (100台)」。
ERP 正式品名:人體工學鍵盤 A款、無線雙模鍵盤 B款、靜電容旗艦鍵盤 C款。

【商業規則】
請寫 syncDealToERP_(customer, itemDescription, amount),回傳 { ok, orderId, message },
讓呼叫端能把訂單編號記到「商機漏斗」I 欄;另保留 autoSyncDealToERP(customer, itemDescription, amount)
(名稱與參數不可變),只回傳 message:
0. 專案中找不到 apiSubmitSalesOrder 時不送,回傳 🛑 訊息。
1. 以關鍵字 A款/B款/C款 對應正式品名;對應表宣告為程式最上方的常數。
2. 從品項文字抓「數字+台」作為數量。
3. 單價 = 金額 ÷ 數量,四捨五入到整數。
4. 組成 { customer, item, quantity, unitPriceTwd } 交給 apiSubmitSalesOrder,不要自己檢查或扣減庫存。

【例外處理】
- 品項對不到、或同時對到兩個:不送 ERP,回傳 🛑 訊息請業務修正。
- 抓不到數量,或數量、金額不是正數:不送 ERP,回傳 🛑 訊息。不得使用預設數量。
- ERP 回傳 success: false:回傳「🛑 ERP 拒單,未建立訂單」加上 ERP 的原因。不得宣稱已通知採購。

【輸出要求】
message 是一段給業務看的文字訊息,只描述真正發生的事;附中文註解。

4. AI 產出的程式碼(已人工驗收)

這段程式碼已經包含在範例程式 CRM_Full_System.js 裡,不需要另外貼上;這裡列出來是為了驗收。apiSubmitDeal(登錄即贏單)、apiCloseDealWon(入口網頁按贏單)、triggerLeadToCashSync(選單 6 補轉)三個入口都呼叫 syncDealToERP_,成功時把 orderId 寫進 I 欄。

// Lead-to-Cash 對照規則:品項關鍵字 → ERP 庫存主檔的正式品名
const ERP_ITEM_MAP = {
  'A款': '人體工學鍵盤 A款',
  'B款': '無線雙模鍵盤 B款',
  'C款': '靜電容旗艦鍵盤 C款'
};

/**
 * 4.3 節的介面:回傳一段給業務看的訊息(函數名稱與參數不可變)
 */
function autoSyncDealToERP(customer, itemDescription, amount) {
  return syncDealToERP_(customer, itemDescription, amount).message;
}

/**
 * 實際轉單邏輯:回傳 { ok, orderId, message },讓呼叫端能記錄 ERP 訂單編號
 */
function syncDealToERP_(customer, itemDescription, amount) {
  const text = String(itemDescription);

  // 0. 同一專案裡要有 ERP 程式,否則不送
  if (typeof apiSubmitSalesOrder !== 'function') {
    return { ok: false, message: '\n🛑【未送 ERP】此專案中找不到 ERP 程式(apiSubmitSalesOrder),請先安裝 ERP_Full_System。' };
  }

  // 1. 品項:必須剛好對到一個 ERP 品名,對不到就不送
  const keys = Object.keys(ERP_ITEM_MAP).filter(k => text.includes(k));
  if (keys.length !== 1) {
    return { ok: false, message: `\n🛑【未送 ERP】無法辨識品項「${text}」,請寫明 A款、B款或 C款其中一種。` };
  }
  const item = ERP_ITEM_MAP[keys[0]];

  // 2. 數量:必須寫成「數字+台」,不准自行假設
  const qtyMatch = text.match(/(\d+)\s*台/);
  const qty = qtyMatch ? Number(qtyMatch[1]) : 0;
  if (!(qty > 0) || !(amount > 0)) {
    return { ok: false, message: `\n🛑【未送 ERP】數量或金額不正確(品項:${text},金額:${amount}),請修正後再按贏單。` };
  }

  // 3. 組成 JSON 形狀的訂單資料(欄位名稱必須與 ERP 的 apiSubmitSalesOrder 一致)
  const payload = {
    customer: customer,
    item: item,
    quantity: qty,
    unitPriceTwd: Math.round(amount / qty)
  };

  // 4. 交給 ERP 建單;庫存夠不夠由 ERP 自己判斷
  const result = apiSubmitSalesOrder(payload);
  if (!result.success) {
    return { ok: false, message: `\n🛑【ERP 拒單,未建立訂單】${result.error}\n請業務與採購協調交期。` };
  }
  return {
    ok: true,
    orderId: result.orderId,
    message: `\n✅【ERP 已建單】${result.orderId}:${result.item} ${result.quantity} 台,剩餘庫存 ${result.remainingStock} 台。`
  };
}

🔍 驗收重點(不懂語法也能檢查) - 看不懂的輸入是停下來,還是猜一個值繼續?舊版程式抓不到數量時會自動當成 10 台、對不到品項時一律當成 A款,這種「好心的預設值」會開出錯誤的訂單。 - 庫存不足時,訊息說的是不是真的發生的事?舊版會寫「已自動向採購部發送補貨請求」,但程式裡根本沒有寄出任何東西。 - 送給 ERP 的欄位名稱(quantity、unitPriceTwd)是否與 ERP 接收端一字不差?名稱對不上,ERP 收到的就是空值。 - 庫存檢查是否只寫在 ERP 一處?兩邊各寫一套,遲早不一致。 - 只有 ok: true(ERP 真的回傳訂單編號)時,I 欄才會寫入編號嗎?

5. 安裝與執行

  1. 打開第 4.2 節的 ERP 試算表,先執行一次【⚙️ 0. 一鍵初始化】,讓庫存回到 A款 50 台、B款 8 台、C款 5 台。
  2. 【擴充功能】→【Apps Script】→ 新增指令碼檔案 CRM_Full_System,貼上 CRM 完整程式;再新增 HTML 檔案 CRM_Sales_Portal,貼上入口網頁網頁。
  3. 對照第 4 點,確認 CRM 檔案裡的 syncDealToERP_ 與講義一致(完整版已內建,不用另外貼)。
  4. 選單不用手動處理:同一個專案只能有一個 onOpen()。CRM 的選單函式本來就叫 onOpenCRM(),而 ERP 的 onOpen() 最後已經寫好「若專案裡有 onOpenCRM 就一併建立 CRM 選單」,所以不需要再手動呼叫 onOpenCRM(),也不要在 CRM 檔案裡另外加一個 onOpen()。(只有在「專案裡只有 CRM、沒有 ERP」時,才需要自己加上 function onOpen() { onOpenCRM(); }。)存檔。
  5. 重新整理試算表,上方會同時出現 ERP 選單與【🤝 跨國商務 CRM】選單。執行【⚙️ 0. 一鍵初始化/重置全新 CRM 系統】,第一次需要授權。
  6. 核對:多出四張 CRM 工作表,儀表板顯示 NT$ 896,000、NT$ 570,600、0.0%。

伍、跑跑看、壞給你看

依序做以下實驗(每一步都接著上一步的結果)。入口網頁從【📱 1. 開啟業務拜訪與商機行動入口網頁】打開。

實驗 操作 預期結果 想想看
① 正常贏單 在入口網頁登錄新商機:品項「人體工學鍵盤 A款 (10台)」、金額 42,000、階段「5-Won 贏單成交」 ✅ ERP 已建單;銷售訂單多一筆 10 台、單價 4,200;A款庫存 50 → 40;這筆商機的 I 欄寫入 ERP 訂單編號 業務沒有離開 CRM,ERP 就已經扣好庫存
② 超賣 在入口網頁的「🏆 商機清單・贏單轉單」對 DEAL-2026-001(100 台)按「🎉 贏單並轉 ERP」 🛑 ERP 拒單:「人體工學鍵盤 A款 目前倉庫僅剩 40 台,客戶欲訂購 100 台」;庫存仍是 40;DEAL-2026-001 已變成 5-Won,但 I 欄留空 業務在回覆客戶前就知道缺 60 台。分批、急採還是延期,該由誰決定?
③ 寫不清楚 登錄品項「A款鍵盤一百台」、金額 420,000、階段 5-Won 🛑 未送 ERP:數量或金額不正確;銷售訂單沒有新增;商機漏斗多一筆 5-Won、I 欄空白的商機 舊版會當成 10 台、單價 42,000 開單。「猜一個值繼續做」比「停下來」危險多少?
④ 重複送單 執行選單【⚡ 6. Lead-to-Cash 聯動:補轉尚未建單的贏單商機】 彈窗:本次新建 ERP 訂單 0 筆、已轉過單略過 1 筆(實驗①)、2 筆未建立(DEAL-2026-001 庫存仍不足;實驗③數量看不懂),並列出各自原因;銷售訂單沒有新增,A款仍是 40 實驗①那筆為什麼沒有被送第二次?如果有人手動清空它的 I 欄,再按一次會怎樣?

實驗④示範了兩個設計:

  1. 重複執行不會重複建單。每筆贏單轉單成功後,I 欄記下 ERP 訂單編號;補轉時只處理「5-Won 且 I 欄空白」的商機。不論按幾次、網路逾時後重送幾次,結果都一樣,這個性質稱為冪等性(Idempotency),第 3.3 節已介紹過支付 API 為什麼必須具備它。入口網頁的「🔁 重新轉 ERP」按鈕也一樣:已有訂單編號的商機會回覆「此商機已轉單,不再重送」。
  2. 成功筆數來自對方的回覆。「新建 0 筆」是依 ERP 實際回傳的 success 計算,不是「送了幾筆」。報表上的「成功」必須來自對方的回覆,不能來自自己的推測。

陸、回到情境

有了這套系統,張業務按下「贏單」的瞬間就會看到「倉庫僅剩 50 台」,可以先跟客戶談分批交貨或確認補貨時程,而不是三天後才由倉管發現。

這個系統還做不到的事:

限制 後果 在哪一節解決
防重複只靠 CRM 的 I 欄(實驗④想想看) I 欄被手動清空或改錯,同一筆商機會再轉一次 第 3.3 節 冪等鍵:讓 ERP 端也記錄商機編號、拒收第二次;第 9 章 權限隔離
庫存不足時只顯示訊息,不會自動通知採購 缺貨仍要靠人跟催 本節練習 2(沿用第 4.2 節的 Gmail 通知)
ERP 的銷售訂單表沒有「客戶」欄 倉管不知道這批貨要出給誰 需修改 ERP 欄位設計,與會計、倉管共同決定
CRM 與 ERP 必須在同一份試算表 權限無法分開,業務也能直接改 ERP 的庫存 第 8.3 節 用 doPost 把 ERP 發布為 API;第 9 章 權限隔離

本節小結

  1. API 是窗口、JSON 是表格、REST 是辦事規則;看得懂 JSON 與狀態碼,就能判斷對接出錯時該找誰。
  2. Webhook 的精神是「事件發生就主動通知」,Lead-to-Cash 把「贏單」這個事件直接接到 ERP 建單。
  3. 對接的關鍵在資料形狀一致:欄位名稱差一個字,對方收到的就是空值。
  4. 看不懂的輸入要停下來並說明原因,不要用預設值硬做;回報的「成功」必須來自對方真正的回覆。

柒、練習

  1. 改數字(5 分鐘):公司認為「3-方案報價」階段的成單機率太樂觀,要從 60% 降為 50%。請在 CRM 程式最上方的常數 STAGE_PROBABILITY 改一處就好:入口網頁的下拉選單、登錄商機、重算漏斗、儀表板都從這裡讀。改完執行【📈 3. 重算商機漏斗加權期望營收】,DEAL-2026-002 的加權營收應變成 NT$ 153,000。如果同一組機率在程式裡寫了兩份,會發生什麼事?這是第 3.4 節的哪個原則?
  2. 加功能(20 分鐘):ERP 因庫存不足拒單時,自動寄一封 Gmail 給採購(收件人用最上方常數 CRM_ALERT_EMAIL),列出商機編號、客戶、品項與欠缺的數量。注意兩種「未建單」要分開:品項或數量看不懂(實驗③)是業務要修正,不寄給採購;只有 ERP 拒單才寄。先在第參段規格表加一列,再修改 Prompt 請 AI 產生程式碼;用實驗②驗證收到信、用實驗③驗證沒有收到信。寄出後,訊息才可以寫「已通知採購」。
  3. 管理反思(討論):實驗②中,商機已記為贏單,但 ERP 拒單。有人主張「ERP 拒單時,CRM 應該把商機退回 4-商務談判」,也有人主張「客戶已經答應就是贏單,缺貨是後勤的問題」。請從銷售績效計算、對客戶的承諾、跨部門責任三個角度,討論哪一種設計比較好。延伸:若公司每 30 秒輪詢一次銀行入帳而被限流(429),你會建議改成什麼架構?為什麼 Webhook 通知要驗證數位簽章?

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。