4.3 現代商業的通用語言:API、RESTful、Webhooks 與 JSON
🏆 CRM 旗艦專案・Lead-to-Cash:從商機到訂單 本節產出:一套 Google 試算表 CRM(客戶、商機漏斗、拜訪日誌、儀表板),業務按下「贏單」時自動把訂單送進第 4.2 節的 ERP,庫存不夠就拒單並說明原因。
學完本節,你能夠:
- 讀懂一段 JSON,說出
{}、[]、鍵與值各代表什麼。 - 用 HTTP 動詞與狀態碼,判斷一次系統對接「做了什麼、成功了沒、錯在哪一方」。
- 把「贏單就自動下單」寫成含例外的規格,讓 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 負責。
💡 兩個系統若在不同檔案? 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. 安裝與執行
- 打開第 4.2 節的 ERP 試算表,先執行一次【⚙️ 0. 一鍵初始化】,讓庫存回到 A款 50 台、B款 8 台、C款 5 台。
- 【擴充功能】→【Apps Script】→ 新增指令碼檔案
CRM_Full_System,貼上 CRM 完整程式;再新增 HTML 檔案CRM_Sales_Portal,貼上入口網頁網頁。 - 對照第 4 點,確認 CRM 檔案裡的
syncDealToERP_與講義一致(完整版已內建,不用另外貼)。 - 選單不用手動處理:同一個專案只能有一個
onOpen()。CRM 的選單函式本來就叫onOpenCRM(),而 ERP 的onOpen()最後已經寫好「若專案裡有onOpenCRM就一併建立 CRM 選單」,所以不需要再手動呼叫onOpenCRM(),也不要在 CRM 檔案裡另外加一個onOpen()。(只有在「專案裡只有 CRM、沒有 ERP」時,才需要自己加上function onOpen() { onOpenCRM(); }。)存檔。 - 重新整理試算表,上方會同時出現 ERP 選單與【🤝 跨國商務 CRM】選單。執行【⚙️ 0. 一鍵初始化/重置全新 CRM 系統】,第一次需要授權。
- 核對:多出四張 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 欄,再按一次會怎樣? |
實驗④示範了兩個設計:
- 重複執行不會重複建單。每筆贏單轉單成功後,I 欄記下 ERP 訂單編號;補轉時只處理「5-Won 且 I 欄空白」的商機。不論按幾次、網路逾時後重送幾次,結果都一樣,這個性質稱為冪等性(Idempotency),第 3.3 節已介紹過支付 API 為什麼必須具備它。入口網頁的「🔁 重新轉 ERP」按鈕也一樣:已有訂單編號的商機會回覆「此商機已轉單,不再重送」。
- 成功筆數來自對方的回覆。「新建 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 章 權限隔離 |
本節小結
- API 是窗口、JSON 是表格、REST 是辦事規則;看得懂 JSON 與狀態碼,就能判斷對接出錯時該找誰。
- Webhook 的精神是「事件發生就主動通知」,Lead-to-Cash 把「贏單」這個事件直接接到 ERP 建單。
- 對接的關鍵在資料形狀一致:欄位名稱差一個字,對方收到的就是空值。
- 看不懂的輸入要停下來並說明原因,不要用預設值硬做;回報的「成功」必須來自對方真正的回覆。
柒、練習
- 改數字(5 分鐘):公司認為「3-方案報價」階段的成單機率太樂觀,要從 60% 降為 50%。請在 CRM 程式最上方的常數
STAGE_PROBABILITY改一處就好:入口網頁的下拉選單、登錄商機、重算漏斗、儀表板都從這裡讀。改完執行【📈 3. 重算商機漏斗加權期望營收】,DEAL-2026-002 的加權營收應變成 NT$ 153,000。如果同一組機率在程式裡寫了兩份,會發生什麼事?這是第 3.4 節的哪個原則? - 加功能(20 分鐘):ERP 因庫存不足拒單時,自動寄一封 Gmail 給採購(收件人用最上方常數
CRM_ALERT_EMAIL),列出商機編號、客戶、品項與欠缺的數量。注意兩種「未建單」要分開:品項或數量看不懂(實驗③)是業務要修正,不寄給採購;只有 ERP 拒單才寄。先在第參段規格表加一列,再修改 Prompt 請 AI 產生程式碼;用實驗②驗證收到信、用實驗③驗證沒有收到信。寄出後,訊息才可以寫「已通知採購」。 - 管理反思(討論):實驗②中,商機已記為贏單,但 ERP 拒單。有人主張「ERP 拒單時,CRM 應該把商機退回 4-商務談判」,也有人主張「客戶已經答應就是贏單,缺貨是後勤的問題」。請從銷售績效計算、對客戶的承諾、跨部門責任三個角度,討論哪一種設計比較好。延伸:若公司每 30 秒輪詢一次銀行入帳而被限流(429),你會建議改成什麼架構?為什麼 Webhook 通知要驗證數位簽章?