準備工作：確認 API 連線設定
在正式開始排查之前，先把以下項目檢查一次：
- Endpoint：確定你要呼叫的 URL 正確無誤（例如
https://api.crm.com/v1/contacts）。
- API Key / Token：確認 token 是否已過期或被吊銷。常見錯誤是把測試環境的 key 放進正式環境，導致 401 Unauthorized。
- HTTP 方法：GET、POST、PUT、DELETE 必須對應 API 文件說明；不要隨意改成其他方法。
以下是一個簡易 cURL 範例（測試連線）：
curl -X GET
https://api.crm.com/v1/contacts?limit=5
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-H "Accept: application/json"
如果得到 200 OK 並且能看到 JSON 數據，就表示基本連線沒問題。否則，先把錯誤訊息記下，再往後排查。
常見連線與授權錯誤
- 401 Unauthorized：Token 過期或不在正確的環境中使用。解決方式是重新產生 token 或確認是否貼上了測試環境的 key。
- 403 Forbidden：目前帳號沒有對應的 API 權限，請到 CRM 後台檢查角色設定。
- 429 Too Many Requests：已達到速率限制。可在請求中加上
Retry-After 或使用分批處理（batch）。
- 500 Internal Server Error / 502 Bad Gateway：通常是後端服務暫時不可用，建議等幾分鐘再重試；若長期持續，聯絡 CRM 支援。
CRM 與行銷工具字段對應表
| CRM 字段 |
行銷工具欄位 |
轉換規則 |
備註 |
| full_name |
name |
直接複製 |
需先拆分為 first_name & last_name |
| email |
email |
直接複製 |
- |
| phone_number |
contact_number |
轉換成 E.164 格式 |
若有區域碼缺失，預設 +886 |
| tags |
segment_list |
每個 tag 加入陣列 |
避免重複 tag |
同步流程檢查清單（可直接貼進 Excel 或 Google Sheet）
- 資料來源：確認 CRM 版本與 API 版本相容。
- 同步頻率：如每 15 分鐘一次，確保排程不會重疊。
- 錯誤紀錄檔：設定 log 檔案並加入時間戳，以便日後回溯。
- 資料完整性驗證：同步完成後，用
GET /contacts/{id} 重新抓取，確認數據一致。
實戰範例：Node.js + Express 整合 CRM 與 Mailchimp
下面的程式碼示範了如何從 CRM 取得聯絡人，再將其推送到 Mailchimp 的成員列表。你可以直接貼進 index.js，並自行替換 API key、list ID 等參數。
// 需要安裝 axios：npm install axios
const axios = require('axios');
// CRM 端點與授權
const crmApi = 'https://api.crm.com/v1/contacts';
const crmToken = process.env.CRM_TOKEN;
// Mailchimp 端點與授權
const mailchimpBase = 'https://usX.api.mailchimp.com/3.0'; // 把 X 換成實際區域碼
const mailchimpApiKey = process.env.MC_API_KEY;
const listId = process.env.MC_LIST_ID;
// 取得 CRM 聯絡人
async function fetchContacts() {
const res = await axios.get(crmApi, {
headers: { Authorization: Bearer ${crmToken} }
});
return res.data.contacts;
}
// 推送到 Mailchimp
async function pushToMailchimp(contact) {
const payload = {
email_address: contact.email,
status_if_new: 'subscribed',
merge_fields: {
FNAME: contact.first_name || '',
LNAME: contact.last_name || ''
}
};
await axios.post(${mailchimpBase}/lists/${listId}/members, payload, {
auth: { username: 'anystring', password: mailchimpApiKey }
});
}
// 主流程
(async () => {
const contacts = await fetchContacts();
for (const c of contacts) {
try {
await pushToMailchimp(c);
console.log(成功推送 ${c.email});
} catch (err) {
console.error(錯誤：${c.email} -, err.response?.data || err.message);
}
}
}());
常見排錯小技巧
- 使用 Postman 或 Insomnia 測試單一 API：先確定每個 API 呼叫都能正常回傳，再整合。
- 比對返回 JSON 結構：若字段名稱變動，請務必更新映射表；不要直接假設兩邊字段完全相同。
- 使用環境變數隔離測試與正式：避免把正式 token 用在測試腳本裡，造成不必要的授權錯誤。
- 留意時間區差：API 可能以 UTC 回傳時間戳，若你在東八區顯示，請自行轉換；否則會出現「資料日期錯亂」問題。
小結
- 先確定連線與授權：每個環節都要先單獨測試。<br/>2. 建立清晰的字段對應表，避免同步時出現「資料遺失」。<br/>3. 寫好錯誤處理機制，並把錯誤資訊記錄到檔案或監控平台。<br/>4. 循序漸進地擴充功能：先完成基本同步，再加入批次、重試等進階特性。
只要按步驟確認，每個環節都正常，API、CRM 與行銷工具的協同就能順利運作。祝你整合愉快！
