POS、電商、CRM 串接時，API 規格應該先確認哪些事？

很多品牌在規劃 POS、電商、CRM 整合時，第一步就是問：「你們有 API 文件嗎？」

這個問題沒錯，但 API 文件只是起點。

真正讓專案卡住的，往往不是沒有 API，而是文件裡沒寫、或一開始沒人想到要談的那些細節。等開發做了一半才發現，改起來就很痛。

舉個真實會發生的場景：門市完成交易、電商訂單也進來了，但 CRM 裡的會員消費紀錄沒有更新。隔天行銷要發回購券，才發現有些人的點數還沒入帳。IT 往回查，問題不在 API 壞掉，而是同步頻率、欄位格式、錯誤處理一開始就沒有定義清楚。

以下幾個面向，建議在正式開發前就先對齊。

API 文件要先看什麼？

API 文件不是只有工程師才需要看。CRM 主管、數位轉型窗口、SI，其實都應該早點參與，因為有些問題不是技術問題，是業務流程問題。

看文件時至少要確認：這支 API 是查資料還是寫資料？回傳哪些欄位？有沒有分頁？有沒有限流？錯誤訊息夠不夠清楚？資料更新後能不能查到異動時間？

很多串接卡住，是因為 API 的設計邏輯和品牌實際的營運流程對不上。比如 POS 可以查會員，但不能回寫點數；電商有訂單資料，但取消跟退貨沒有獨立狀態；CRM 可以發券，但核銷結果無法即時回來。這些都會直接影響到會員權益有沒有算對。

認證方式跟權限，不要等最後才談

API 要怎麼認證——API Key、OAuth、JWT、還是 IP 白名單——這件事要在前期就確認，不只是資安問題，還會影響測試和上線的流程。

幾個常見的坑：正式環境需要申請 IP 白名單，測試環境也需要嗎？Token 過期怎麼更新？不同品牌、不同通路共用同一組權限嗎？如果有 SI 或外部開發商協助，有沒有辦法做分層授權、留下操作紀錄？

大型企業的資安審查、權限申請、測試帳號開通都需要時間。等功能做完再來處理，很容易卡上線。

同步頻率會影響前台體驗，不只是後端設定

POS、電商、CRM 之間的資料同步，大概會用到三種方式：即時 API、排程同步、批次匯入。

不是每種資料都需要即時。會員登入、點數查詢、優惠券核銷，通常要接近即時；消費紀錄彙整、報表資料、歷史訂單，批次處理就夠了。

問題是品牌要先想清楚：哪些資料影響前台顯示？哪些只是後台分析用？

如果門市消費後點數要隔天才入帳，前台文案就要說清楚。如果優惠券核銷需要即時驗證，POS 跟 CRM 之間就不能只靠每日批次。

這不只是工程設定，它會影響客服怎麼解釋、會員期待怎麼管理、行銷活動怎麼設計。

欄位格式要比功能更早對齊

這是最常被低估、但最後最多問題的地方。

手機號碼要不要含國碼？生日用西元年還是民國年？訂單金額含稅嗎？點數是整數還是可以有小數？門市代碼跟 CRM 後台一致嗎？

欄位沒有先對齊，資料進來就會變成整理成本。最常見的狀況是：CRM 有一套會員等級，POS 有另一套代碼，電商顯示又不一樣。表面上都叫「VIP」，但條件不同，最後行銷分眾就會跑掉。

建議在開發前先做一份欄位對照表，把資料來源、格式、必填條件、更新規則、例外狀況都列清楚。不需要寫得很厚，但要讓業務規則、營運流程、系統欄位三件事對得起來。

錯誤重送和紀錄查詢，一開始就要設計進去

API 一定會失敗。網路中斷、系統維護、欄位異常、Token 過期、第三方服務延遲，都會讓資料送不出去。

比較成熟的做法是事先定義：失敗後自動重試幾次？多久試一次？重試還是失敗，誰會收到通知？後台能查到錯誤原因嗎？有沒有 audit log 可以回溯？

對點數、優惠券、訂單、退貨來說，這件事特別重要——因為這些牽涉會員權益，也可能牽涉對帳。只看當下的餘額或狀態，沒有異動紀錄，出問題要查就很痛苦。

決定好資料主從，才不會互相覆蓋

POS、電商、CRM 都可能存著會員資料，但不能每個系統都說自己是主要來源。

比較清楚的分法是：會員手機由 CRM 維護，消費紀錄由 POS 和電商提供，點數餘額由 Loyalty 系統計算，核銷結果由各通路回傳。這個主從關係要先講定，不然同步的時候很容易蓋掉資料。

一個真實會發生的狀況：會員在電商更新了姓名，隔天 POS 批次同步把舊資料推回來，新資料就這樣被蓋掉了。這不是技術 bug，是主從規則一開始沒有談清楚。

Webhook 跟批次匯入，搭配著用才穩

Webhook 適合處理「事件」：訂單成立、付款完成、退貨、優惠券核銷、會員綁定，這些發生當下就要通知另一個系統的情境。

但 Webhook 不是萬能。補歷史資料、重新同步失敗紀錄、定期校正——這些還是需要批次處理或查詢 API 配合。

比較穩的架構是：事件用 Webhook，批量或低即時性的資料用批次，再定期做一次資料校驗。不只靠單一路徑，上線後比較不容易出問題。

測試環境和上線切換，要比你想的更早規劃

測試環境不是有個網址就夠。還要確認測試資料怎麼建、測試會員可不可以綁定、測試訂單能不能取消、點數和優惠券能不能模擬核銷跟退回。

正式上線前也要確認切換流程：正式 API Key 什麼時候給？Callback URL 要不要換？Webhook 有沒有可能同時打到測試跟正式環境？歷史資料要不要先匯進去？上線第一天誰負責盯資料同步？

很多專案不是敗在開發，是敗在上線切換時沒有清楚的檢查表。當 POS、電商、CRM 同時動的時候，上線當天一定要有明確的回報窗口和異常處理 SOP。

沃提利觀點

POS、電商、CRM 串 API，目的不是完成技術整合，而是讓會員資料、消費紀錄、點數、優惠券這些東西，真的能被品牌日常使用。

API 規格確認得越早，後面補洞的機率就越低。好的整合夥伴，不只是把端點接起來，而是能一起把資料主從、同步節奏、錯誤處理、上線維運這些事情想清楚。

因為系統最後不是交給 API 文件用，是交給行銷、CRM、客服、門市、IT 長期維護。