CRM External API

用 API 將客戶、聯絡人與商機資料接入 WEMS CRM。

CRM 對外 API 聚焦安全的外部資料建立與查詢。每個 API key 對應租戶與可用範圍，外部系統不需要直接存取 CRM 內部資料庫。

租戶範圍

API key 會綁定租戶、使用者與可選分支，查詢與寫入都限制在該範圍內。

資料淨化

建立客戶、聯絡人與商機時，服務端會清理可疑輸入並限制 tag 數量。

公開合約

Status 與 Catalog 不需 key，正式資料 API 需要 X-Api-Key。

Endpoint 清單

方法	路徑	用途	驗證
GET	`/status`	服務狀態、文件連結、驗證標頭名稱。	不需 key
GET	`/catalog`	對外 API 資源目錄與可用端點摘要。	不需 key
GET	`/customers?keyword=&status=&source=&page=&page_size=`	依租戶範圍查詢客戶。	X-Api-Key
POST	`/customers`	建立客戶，支援 name、email、phone、company、industry、source、tags。	X-Api-Key
GET	`/contacts?keyword=&customer_id=&page=&page_size=`	查詢聯絡人，可依客戶篩選。	X-Api-Key
POST	`/contacts`	建立聯絡人，支援 customerId、title、department、isPrimary。	X-Api-Key
GET	`/opportunities?keyword=&customer_id=&status=&page=&page_size=`	查詢銷售商機與狀態。	X-Api-Key
POST	`/opportunities`	建立商機，支援 customerId、amount、currency、stageId、probability。	X-Api-Key

快速測試

curl -sS "https://crm.sun-bd.com/api/public/v1/status"

curl -sS "https://crm.sun-bd.com/api/public/v1/customers?page=1&page_size=20" \
  -H "X-Api-Key: YOUR_API_KEY"

建立客戶

curl -sS -X POST "https://crm.sun-bd.com/api/public/v1/customers" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"name":"Acme Taiwan","email":"ops@example.com","source":"partner"}'

JavaScript 串接範例

const response = await fetch("https://crm.sun-bd.com/api/public/v1/opportunities?page=1&page_size=20", {
  headers: { "X-Api-Key": process.env.WEMS_CRM_API_KEY }
});

const result = await response.json();
if (!result.success) throw new Error(result.message || "CRM API error");
console.log(result.data.items);

安全注意事項

API key 只能放在服務端或受控後端，不要放在瀏覽器 JavaScript、App 靜態檔或公開 Git。
正式寫入前先用 /status 與 /catalog 確認服務與合約版本。
若要使用集中會員登入，請參考會員登入 API 教學；付款與點數請參考 Payment Points API。