Salesforce 整合幾乎從來不是敗在通訊協定上。驗證是已經解決的問題，寫入一筆記錄也是已經解決的問題。真正把專案拖垮的，是每天的請求配額和資料模型的形狀，而這兩件事通常要等到上線大約三週之後才被發現，那時夜間作業開始回傳錯誤，卻沒有人說得清它在測試環境裡為什麼是好的。

這個模式一致到可以預測。開發者對著一個 Developer Edition 組織開發，一切通過，客戶簽字驗收。接著這套程式碼遇上的，是一個已經住著行銷連接器、資料倉儲擷取作業，以及一個 2019 年就在跑的 Apex 觸發程序的正式組織，而那份看起來很寬裕的請求預算，其實是別人早就在花的一口共用的鍋。

這篇文章把意外提前攤開來談：你應該用哪一個 API、配額是怎麼算的、當你的寫入啟動了不是你寫的程式碼會發生什麼、驗證方式有了什麼變化，以及哪些資料模型決定一旦做錯就很難回頭。

決定一個 Salesforce 整合成敗的是什麼？ 是配額和資料模型，不是通訊協定。每天的 API 請求配額是組織層級的，由版本與授權數量推導而來，所以一個規矩的整合完全可能被同一個組織裡另一個寫得很糟的整合餓死。從第一行程式碼起就照批次來設計，在寫入任何東西之前先把外部 ID 與 upsert 談定，並且預設你送出的每一筆記錄都會啟動別人的 Apex。

Salesforce 整合必須做對的事

有四件，而且分量並不相同。

第一件是配額。你的程式碼發出的每一次同步呼叫，都從一份組織層級、每天只有一份的配額裡扣除，而這份配額與該組織的所有其他使用方共享。

第二件是底下的平台。Salesforce 不是一個附帶 HTTP 介面的資料庫。它是一個應用程式平台，你的寫入會執行由管理員設定的觸發程序、流程、驗證規則、重複規則與彙總欄位，而那些管理員從來沒聽過你的專案。

第三件是資料模型。Lead、Contact、Account 與 Opportunity 並不能互換，它們之間的轉換是單向的而且帶有副作用，選錯了就不是改程式碼，而是做資料移轉。

第四件是身分：你的系統與 Salesforce 如何就「哪一筆記錄是哪一筆」達成一致。這一點錯了，重複資料會以機器的速度長出來。後面所有內容，都是從這四件中的某一件延伸出來的。

API 全貌，以及你真正需要哪一個

Salesforce 公開了一個龐大的 API 家族。權威清單是 Salesforce API 索引，下面這些名稱來自它，而不是來自記憶。

REST API 與 SOAP API

REST API 是所有記錄形狀工作的預設選擇：建立、讀取、更新、刪除、查詢、describe。網頁表單寫入一筆 Lead、入口網站讀取某個客戶尚未結案的案件，以及任何流量不高的互動路徑，用它都是對的。

SOAP API 透過 WSDL 做同樣的事，它至今仍然存活，因為大量企業中介軟體天生就說這門話，也因為它給你一份可以據以產生用戶端的強型別合約。人們常犯的錯誤，是認定 SOAP 是舊時代而 REST 是現代。兩者都是現行的，而且 SOAP 的 create() 與 update() 每次各接受最多 200 筆記錄，這件事比傳輸格式重要得多。

Bulk API 2.0

Bulk API 2.0 是處理量的非同步作業式通道。你上傳一個 CSV，Salesforce 在背景把它切塊並處理，你再輪詢結果。Salesforce 的 Bulk API 限制允許滾動的 24 小時內最多 15,000 個批次、同一個區間內最多匯入 1.5 億筆記錄，作業檔案上限為 150 MB。

人們常犯的錯誤，是把 Bulk 當成之後再調校的一步。它是另一種程式設計模型：結果非同步回傳、逐筆回傳，你的程式碼從一開始就必須照那種方式消化它們。

Composite 與 sObject Collections

這兩者是 REST API 裡價值最高、也最少被使用的部分。一個 composite 請求在單次呼叫中最多可以帶 25 個子請求，其中最多 5 個可以是查詢或 sObject Collections 操作，而且靠後的子請求可以引用靠前的子請求回傳的 ID。sObject Collections 在一次請求裡最多處理同一個物件的 200 筆記錄。兩者對每日配額都只算 一次呼叫，這正是它們的意義所在。

人們常犯的錯誤，是根本不知道它們存在。先建 Account、再建 Contact、再建 Opportunity 這樣三次循序呼叫，花掉的配額是一次 composite 請求的三倍，延遲也是三倍。

Streaming、變更資料擷取與 Pub/Sub

Streaming API 是以 CometD 為基礎的訂閱通道，服務於 PushTopic、一般事件、平台事件與變更事件。變更資料擷取會在記錄被建立、更新、刪除或還原時發布近乎即時的通知，讓外部儲存不必輪詢就能跟上 Salesforce。Platform Events 則是你自己定義的事件。

Pub/Sub API 是更新的 gRPC 與 HTTP/2 介面，把發布、訂閱、結構描述取得與主題探索合併進一個 API，承載內容用 Avro 而不是 JSON。如果是全新的事件驅動實作，就從它開始。

人們常犯的錯誤，是把事件當成有保證的資料流。它們並不能取代對帳，原因在下一節。

API 請求限制才是真正的限制

這一節決定你的架構，而它通常是在設計完成之後才被讀到的那一節。

每日配額是怎麼算出來的

Salesforce 的 API 請求限制文件按版本與授權數量設定配額，而不是按使用者或按應用程式。含 API 存取權的 Enterprise 與 Professional 版本取得 100,000 次呼叫，外加每一個 Salesforce 或 Salesforce Platform 授權 1,000 次。Unlimited 與 Performance 版本取得 100,000 次，外加每一個授權 5,000 次。Developer Edition 一律 15,000 次，而一個 Full 沙箱是 5,000,000 次。

由此得出兩點。一個 60 位使用者的 Enterprise 組織每天大約有 160,000 次呼叫，不是無限供應。而既然配額是由授權推導而來，要提高它就只有兩個辦法：買更多使用者授權，或是買額外的 API 呼叫，兩者都透過 Salesforce 的 Your Account 應用程式購買。

什麼會被計入，用完之後會怎樣

配額是以 24 小時內對該組織的所有呼叫總量來衡量，把 REST API、SOAP API、Bulk API、Bulk API 2.0 以及大多數 Connect REST API 呼叫一併計入。來自某些 Salesforce 連線應用程式的呼叫，例如行動應用程式，則被排除在外。

正是這種加總把人絆住。你的整合沒有自己的預算。它和報表連接器、行銷平台以及這個組織裡的每一個其他整合共用同一份預算，而一個每三十秒輪詢一次的糟糕使用方，就足以把它抽乾，餓死那些表現完全正常的程式碼。

當組織超出配額時，請求會以 403 與 REQUEST_LIMIT_EXCEEDED 失敗。Salesforce 會讓付費的正式組織有一定程度的超額，然後才硬性執行，但試用組織與 Developer Edition 沒有這種寬限。請照沒有寬限來設計。

在定下設計之前先量測

在寫程式碼之前，先從管理員那裡拿到該組織的配額與目前每日消耗量，REST API 有一個組織限制資源可以查。如果既有的使用方已經用掉 70%，那麼逐筆記錄的同步整合就不可行，調校也救不回來。

批次是設計決定，不是最佳化項目

一旦你接受配額是有限而且共享的，設計就會自己長出來。

不要用迴圈去做單筆記錄的呼叫。一個逐筆建立 5,000 筆 Contact 的作業會花掉 5,000 次呼叫。同樣這 5,000 筆，走 sObject Collections、每次請求 200 筆，只花 25 次。這個 200 倍的係數，就是一個整合塞得進中型組織配額與塞不進的分界線。

當工作是一張圖而不是一份清單時，用 Composite。在一次請求裡建立父記錄與它的子記錄，既省掉來回，也省掉你的程式碼在等待 ID 時不得不保留的中間狀態。

任何比較像載入或匯出、而不像交易的工作，用 Bulk API 2.0。它不適合互動路徑，因為它照設計就是非同步的，不會給使用者一個同步的答案。

把參考資料快取起來。選項清單值、記錄類型 ID 與 describe 結果很少變動，卻在每次執行時被毫無理由地重新取得。光是這一項改動，往往就能砍掉一個天真實作四分之一的呼叫量。

調控器限制：你的寫入會執行別人的程式碼

Salesforce 在嚴格的單一交易上限內執行客戶撰寫的 Apex。對整合真正有影響的 Apex 調控器限制是：每一個同步交易 100 個 SOQL 查詢、SOQL 取回 50,000 筆記錄、150 個 DML 陳述式、DML 處理 10,000 筆記錄、10 秒同步 CPU 時間，以及 6 MB 堆積記憶體。

那些 Apex 不是你寫的。你照樣會撞上這些限制，因為你入站的寫入會開啟一個交易，執行該物件上存在的任何觸發程序。

不寫 Apex 也要懂的批量化

即使你從來不打開一個 Apex 檔案，這個概念也值得理解。

Salesforce 交給觸發程序的是一組記錄，而不是一筆。寫得正確的觸發程序用一次查詢和一次更新處理整組記錄。照著「每次只會收到一筆記錄」來寫的觸發程序，則是每一筆記錄各跑一次查詢和一次更新。

第二種觸發程序會完美運作很多年，因為使用者是透過介面一筆一筆儲存記錄的。然後你的整合在一次請求裡送來 200 筆，觸發程序把它的查詢跑了 200 遍，衝破 100 個查詢的上限，整個批次失敗。

Bulk API 2.0 以 200 筆記錄為一塊來處理匯入資料，每一塊是一個獨立交易，所以這不是紙上談兵。它就是首次對一個有歷史的組織做大量載入時的標準樣貌。

該怎麼應對

在答應交付日期之前，先稽核你將要寫入的每一個物件上的觸發程序與流程。如果某個觸發程序沒有做批量化，就得有人去修，而那個人需要 Apex 能力和一個部署時段。把它列成一個預算項目。

如果修正超出範圍，就把批次調小。每次請求 200 筆是上限而不是要求，降到 50 筆有時能擠出足夠餘裕先上線，同時排期去做觸發程序的改造。這會吃配額，所以要把它當成暫時措施。

明年還能用的驗證方式

這個領域發生了實質變化，很多已發布的指南現在是錯的。

OAuth 2.0 的使用者名稱與密碼流程是要避開的那一個。它把憑證直接暴露在請求裡，Salesforce 在較新的組織中預設封鎖它，而且它在連線應用程式上的退場也已經排定。任何還在用它的整合，都需要一份帶日期的移轉計畫。

對於沒有人參與其中的伺服器對伺服器工作，目前的兩個答案是：用憑證為宣告簽章的 JWT 持有者流程，以及用取用者金鑰與密鑰換取權杖的用戶端憑證流程。Salesforce 關於用整合使用者與用戶端憑證呼叫 REST API的說明明確指出，這個流程不會核發更新權杖，所以舊權杖到期後由用戶端去請求一個新的存取權杖。

連線應用程式與外部用戶端應用程式

承載這一切的容器過去是連線應用程式。現在是外部用戶端應用程式。Salesforce 明確表示自 Spring ‘26 起連線應用程式的建立受到限制，並建議改用外部用戶端應用程式，把它描述為為了提升安全性、解決封裝問題而設計的新一代。

如果你的整合文件寫著「建立一個連線應用程式」，那它描述的是一條新組織可能不再提供的路徑。在確定工作範圍之前，先確認目標組織適用哪一種。

用專屬整合使用者執行，並為輪替做計畫

給整合一個自己的使用者，配最小存取權限、僅限 API 的設定檔。不要用某位在職員工的身分執行它。當那位員工離職、帳號被停用時，整合就停了，而且是在最糟的時刻停的，回報的錯誤還指不到任何有用的地方。

憑證會到期，密鑰會輪替。兩者在出事那天之前都是安靜的，而且兩者都會讓整合整個下線，而不是部分下線。把到期日放進由某個人負責的行事曆裡，把憑證放進金鑰管理工具裡，並且在真正需要之前先在沙箱裡演練一次輪替。

資料模型的陷阱

這些是會花掉三週的陷阱，因為撤銷它們意味著搬資料，而不是改程式碼。

Lead、Contact、Account 與 Person Account

Lead 是尚未與公司記錄連結的未驗證潛在客戶。Contact 是掛在 Account 底下的人。Account 是一個組織。轉換會把一筆 Lead 變成一筆 Account 與一筆 Contact，也可以再加一筆 Opportunity，而 SOAP 的 convertLead 呼叫明確說明只有目標上為空的欄位才會被覆寫，所以你細心填好的 Lead 欄位未必會落到你以為的位置。

Person Account 讓事情更複雜。面向消費者的組織會啟用它，讓一個個人同時以 Account 與 Contact 的合體形式存在，於是照企業 Account 模型寫的整合，在啟用它的組織裡不做修改就跑不動。這一點被發現得晚，規律得令人喪氣。

某一筆入站記錄該變成哪一個物件，要和業務端以書面形式定下來。這不是一個技術決定。

外部 ID 與 upsert

這是 Salesforce 給你的唯一一個講道理的冪等機制，應該當成沒有商量餘地的東西。在物件上建一個標記為外部 ID 的自訂欄位，把你自己系統的主索引鍵存進去。之後你就可以用 upsert 作業，也就是對 /sobjects/{Object}/{ExternalIdField}/{Value} 發出的 PATCH：沒有相符時建立記錄，剛好相符一筆時更新它。零相符回傳 201，一筆相符回傳 200，多筆相符則以 300 失敗，而不是去猜。

後果值得直說。有了 upsert，重試一個失敗的請求是安全的。沒有它，每一次重試都是一筆潛在的重複記錄，而夜間作業中一次短暫的網路抖動，就會變成以天計的清理工作。

會在你寫入時觸發的規則

重複規則可以攔截或提醒你的整合所建立的記錄。驗證規則會拒絕不符合管理員所設定條件的記錄。必填欄位可能在你上線好幾個月之後才被加上，從那一刻起，一個本來正常的整合開始在每一筆記錄上失敗。

這些都不是錯誤，它們是這個組織照設定運作的樣子。錯誤在於把一次被拒絕的寫入當成傳輸錯誤並永遠重試，而正確的反應是把它連同欄位層級的原因一起呈現給人。我們關於第三方 API 整合的成本與失效模式的指南，在別處討論了同一類問題。

錯誤處理、冪等性與重播

一個沒有重播機制的整合，會變成人工資料修復工作。這不是預言，這就是會發生的事。

部分成功是常態。sObject Collections 的 allOrNone 預設為 false，所以一個 200 筆記錄的請求可能回傳 187 筆成功與 13 筆失敗，各自帶著原因，Bulk API 2.0 同樣逐筆回傳結果。只檢查外層 HTTP 狀態碼的程式碼，會一邊悄悄丟掉記錄一邊回報成功。

在重試之前先幫失敗分類。列鎖定、逾時與配額耗盡這類暫時性狀況值得指數退避。驗證錯誤與缺少必填欄位這類確定性失敗會永遠以同樣的方式失敗，重試它們只是在燒你本來就不寬裕的配額。

每一筆無法復原的記錄都要連同它的承載內容與錯誤進入死信儲存區，供人檢查並重新送出。因為你的寫入是以外部 ID 為鍵，重新送出是安全的。把你的識別碼與 Salesforce ID 的對應關係在兩邊都記錄下來；六個月後，那份記錄檔會是唯一能解釋某個客戶的記錄為什麼不對的東西。

還要對帳。平台事件與變更事件在事件匯流排上保留 72 小時，而 Salesforce 的平台事件配額把每日投遞上限定為 Enterprise 25,000 個事件、Unlimited 與 Performance 50,000 個。一個定期比對記錄數量與修改時間的作業，能抓住資料流漏掉的東西。

中介軟體還是直連

點對點是對的次數，比平台廠商願意承認的要多。一個來源、一個目標、一個方向、適中的量、一份穩定的合約：直接做，省掉那份授權。

中介軟體賺回它成本的時刻，是拓撲不再是一條線的時候。多個系統交換資料、業務人員需要不經部署就改動轉換邏輯、需要跨越幾個各自獨立故障的系統做協調、真的需要集中的監控與重試。

說句老實話：中介軟體是把成本挪走，而不是消除。你仍然要為對應、錯誤處理與維運知識付錢，然後又加上一份授權、第二條管線，以及需要另外找人的第二套技能。API 配額並不會因此改變，因為中介軟體呼叫的就是你的程式碼原本要呼叫的那些 API。

選它是因為你的拓撲需要它，而不是因為它看起來能少寫程式碼。我們的自建還是採購決策指南對底層系統討論了同樣的取捨，而CRM 與 ERP 整合指南涵蓋了多系統的情形。如果你希望有人來評估而不是爭論，那正是我們的軟體開發服務開始的地方。

沙箱、部署與 API 版本

在沙箱裡開發。不要對著正式環境，也不要對著一個不共享正式設定的 Developer Edition 組織，因為真正會弄壞你的正是設定。

要理解重新整理做了什麼。它用一份來自正式環境的新副本取代沙箱，所以只存在於沙箱裡的測試資料會消失。任何必須活過重新整理的東西，都得寫成腳本而且可以重複執行。團隊通常是丟掉一週的測試資料之後才學會這一點。

在每一條請求路徑上明確固定你的 API 版本，並了解退場政策。Salesforce 的 API 終止支援政策承諾每個版本至少支援三年，並在支援結束前至少一年通知客戶。版本 21.0 到 30.0 已在 Summer ‘25 退場，對已退場版本發出的請求會回傳 410 Gone。

那是一個硬性中止而不是效能下降，這正是版本固定屬於你維護計畫的原因。同樣的紀律也適用於你自己對外發布的 API，我們在 API 版本管理一文中討論過。

英國資料保護與 CRM 資料

CRM 幾乎全部是個人資料：姓名、雇主、電話號碼、電子郵件地址、關於對話的備註。把它在系統之間搬動，就是英國 GDPR 意義下的處理。

第一個問題是誰是控制者。英國資訊委員辦公室關於控制者與處理者的指引把控制者定義為決定處理目的與方式的一方，把處理者定義為代表控制者進行處理的一方。當一家代理商為你建置並營運整合時，那家代理商通常是處理者，而一份滿足第 28 條要求的書面合約是強制的，不是可選的。

第二個問題是跨境傳輸。Salesforce 組織與任何中介軟體都可能位於英國境外，而資訊委員辦公室的國際傳輸指引列出了可用的機制以及何時需要做傳輸風險評估。在簽約之前先確定資料會落在哪裡。

由此得出三個後果。不要複製你並不需要的欄位，因為最小化既是法律要求，也代表更少的對應工作。不要在沒有認真判斷的情況下把正式環境的個人資料放進沙箱。還要確保刪除會傳播，因為一個在 Salesforce 裡被抹掉、卻在你的資料倉儲裡原封不動的聯絡人，就是一個活著的法遵問題，而當 AI 代理也能觸及這些記錄時同樣如此。

Salesforce 整合的成本

Salesforce 在自己的定價頁面上公布版本與授權價格，我們在這裡不引用任何數字，因為決定整合設計的是這些授權產生的 API 配額，而不是牌價。

下面的數字是 Mecanik 自己的英國專業服務估算，不是廠商定價，而且假設組織已經存在、也有一位能回答問題的管理員。

一個簡單的單向整合，也就是網頁表單建立一筆帶外部 ID 的 Lead 並配上合理的錯誤處理，通常是 GBP 3,000 到 GBP 7,000。一到兩個物件的雙向同步，加上衝突解決與一個對帳作業，一般是 GBP 15,000 到 GBP 40,000。一個以 Pub/Sub 為基礎、帶重播、死信處理與監控的事件驅動整合，通常落在 GBP 30,000 到 GBP 80,000 之間。

交付物裡應該有什麼

一份與業務端達成一致、而不是靠推斷得來的欄位層級對應文件。每一個同步物件上的外部 ID。帶死信儲存區與書面重新送出流程的錯誤處理。一個對帳作業。針對組織配額的 API 消耗監控，並在遠低於上限處告警。用於權杖輪替、憑證到期與重播的操作手冊。寫成腳本、能活過重新整理的沙箱設定。沒有這些的整合，無論發票上怎麼寫，都是一個原型。

持續成本

為監控、每年三次的 Salesforce 版本更新、憑證輪替，以及管理員不打招呼就會做的欄位變更，預留每月 GBP 400 到 GBP 1,500。願意為這一項付錢的組織，就是那些整合一直能用的組織。

把它做出來

這裡的失效模式一致得有點無聊：配額發現得太晚、一個沒人稽核過的觸發程序、一筆本該是 Contact 的 Lead、沒有辦法重播一個失敗的批次。這四件在設計階段防起來都很便宜，等到真實記錄已經存在再去修就很貴。

Mecanik 把建置與維護 Salesforce 整合當成軟體開發工作的一部分，而且在寫任何程式碼之前，先從稽核該組織的配額、觸發程序與資料模型開始。如果你要的是一件範圍明確的整合工作而不是一份完整的合作，也可以直接聘請一位網頁開發者。

常見問題

一個 Salesforce 整合每天可以用多少次 API 呼叫？ 這取決於版本與授權數量，而且配額是組織層級的，不是按整合分配的。含 API 存取權的 Enterprise 與 Professional 版本取得 100,000 次呼叫，外加每一個 Salesforce 或 Salesforce Platform 授權 1,000 次；Unlimited 與 Performance 取得 100,000 次，外加每一個授權 5,000 次；Developer Edition 在滾動的 24 小時內一律 15,000 次。

Salesforce 應該用 REST API 還是 Bulk API？ 互動式、流量低、記錄形狀的工作用 REST API，量大而且可以接受非同步答案的載入與匯出用 Bulk API 2.0。介於兩者之間的情況，每次請求 200 筆記錄的 sObject Collections 與每次請求 25 個子請求的 Composite 對配額都只算一次呼叫，能消除大部分壓力。

伺服器對伺服器的 Salesforce 整合該用哪一種 OAuth 流程？ 用 JWT 持有者流程或用戶端憑證流程，並以一個僅限 API 的專屬整合使用者身分執行。使用者名稱與密碼流程在較新的組織中預設被封鎖，而且已排定退場，所以不應該用於新的工作。另外要注意，自 Spring ‘26 起連線應用程式的建立受到限制，Salesforce 現在建議使用外部用戶端應用程式。

為什麼我的 Salesforce 整合只在大批次時失敗？ 幾乎總是因為某個沒有做批量化的 Apex 觸發程序。Salesforce 交給觸發程序的是一組記錄，而照著每次只收到一筆記錄來寫的觸發程序會對每一筆記錄各跑一次查詢，在你的批次抵達時超出 100 個 SOQL 查詢的限制。它對介面上一筆一筆儲存記錄的使用者完全正常，所以才一直沒被發現。

要和 Salesforce 整合一定需要中介軟體嗎？ 單一來源、單一目標、單向而且量適中的整合並不需要，直接做更便宜也更單純。中介軟體賺回成本的時刻，是多個系統開始交換資料、業務人員需要不經部署就改對應，或者你需要集中協調與重試的時候。它是把成本挪走而不是消除，也不會增加你的 API 配額。