跳到主要內容
客脈 Kemai文件中心
文件選單 開發者 API

開發者 API

客脈對外 API 的網址、認證、請求與回應格式、分頁與篩選、限流與錯誤碼,給要串接的工程師。

這一區寫給要把自己的系統接上客脈的工程師。工作區要先開通對外 API 加購模組,並由擁有者或管理員建立 API Key。

  • 資源與欄位:公司、聯絡人、商機、活動紀錄、待辦,以及銷售流程、自訂欄位、標籤、成員。
  • Webhook:事件格式、簽章驗證、重試。

網址

每個工作區用自己的網域呼叫 API,所有路徑都以 /api/v1 開頭:

https://<你的工作區>.kemai.campulse.tw/api/v1/contacts

工作區有生效中的自訂網域時,也可以用自訂網域,例如 https://crm.example.com.tw/api/v1/contacts。一把 API Key 只能用在建立它的工作區。

認證

每個請求都在標頭帶上 API Key:

Authorization: Bearer kemai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • 帶了 Authorization: Bearer 的請求只用 API Key 認證,不使用登入的 cookie。
  • API Key 以建立者的身分操作:唯讀的 key 最多等同「檢視者」,讀寫的 key 最多等同「成員」。詳見API Key。
  • 客脈不回傳跨來源(CORS)標頭:不要在瀏覽器裡呼叫,請從你的伺服器呼叫,key 才不會外洩。

範例:建立一位聯絡人

curl -X POST "https://acme.kemai.campulse.tw/api/v1/contacts" \
  -H "Authorization: Bearer $KEMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "王小明", "email": "ming@example.com", "phone": "0912-345-678"}'

請求與回應

  • 請求與回應都是 JSON,編碼 UTF-8;有內容的請求要帶 Content-Type: application/json。
  • id 都是 UUID。時間是 ISO 8601 的 UTC 時間(例如 2026-11-04T02:30:00.000Z),日期是 YYYY-MM-DD。
  • 新增成功回 201 與新的資料;修改成功回 200 與修改後的資料;刪除成功回 204,沒有內容。
  • 修改(PATCH)只更新有傳的欄位;選填欄位傳 null 或空字串表示清空。
  • 文字欄位會去掉頭尾空白;不認得的欄位會被忽略。

分頁

列表回傳一頁資料:

{
  "items": [{ "id": "…", "name": "…" }],
  "nextCursor": "eyJ2IjoiMjAyNi0xMS0wNFQwMjozMDowMC4wMDBaIiwiaWQiOiIuLi4ifQ",
  "total": 128
}
  • limit:每頁筆數,預設 50(活動紀錄 20),最多 200。
  • cursor:把上一頁的 nextCursor 原樣帶回來取下一頁;nextCursor 是 null 表示沒有下一頁。
  • total 是符合條件的總筆數,只有第一頁有。

搜尋、篩選與排序

公司、聯絡人、商機的列表支援:

  • q:關鍵字搜尋,最多 100 字。
  • sort:欄位名稱,前面加 - 表示由大到小,預設 -updatedAt。可以排序的欄位有 name、createdAt、updatedAt 等;自訂欄位用 custom.<欄位代碼>。
  • filter:篩選條件的 JSON 陣列(要做 URL 編碼),最多 20 個,全部符合才會列出:
[
  { "field": "owner", "op": "in", "value": ["me"] },
  { "field": "createdAt", "op": "gte", "value": "2026-10-01" }
]

op 可以是 contains(包含)、eq(等於)、gte(大於等於)、lte(小於等於)、in(是其中之一)、hasAny(有任一個標籤或選項)、empty(空白)、notEmpty(不是空白);能用哪些依欄位種類而定,me 代表 API Key 的建立者。各資源另外的參數見資源與欄位。

限流

每把 API Key 每分鐘最多 120 次請求。每個回應都帶:

標頭說明
X-RateLimit-Limit每分鐘的上限
X-RateLimit-Remaining這一分鐘還剩幾次
X-RateLimit-Reset重新計算的時間(Unix 秒數)

超過時回 429,並帶 Retry-After(秒);請等這麼久再試。同一個來源連續用錯誤的 key 太多次,也會暫時被擋下。

錯誤

錯誤一律回這個格式:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "有欄位的資料不正確,請檢查標示的欄位後再送出一次。",
    "details": { "issues": [{ "path": "email", "code": "invalid_format" }] }
  }
}

message 是給人看的說明,可能調整措辭;程式請判斷 code。

狀態code說明
401UNAUTHENTICATEDkey 錯誤、已撤銷、已過期,或建立者已不在工作區
402MODULE_NOT_ENABLED工作區沒有開通對外 API 模組
403FORBIDDENkey 的範圍或建立者的角色不能做這件事,或這個路徑沒有開放給 API Key
404NOT_FOUND資料不存在或已刪除
409CONFLICT和現有資料衝突
422VALIDATION_FAILED欄位不正確;details.issues 列出每個欄位(path)與原因(code)
429RATE_LIMITED超過限流
500INTERNAL_ERROR客脈這邊發生錯誤,請稍後再試;一直發生時請聯絡我們

使用規範

  • 只開放這份文件寫到的路徑與欄位;其他路徑是客脈畫面專用,可能隨時調整,API Key 呼叫會回 403。
  • 我們會盡量維持 /api/v1 相容:新增欄位或新的事件類型不另行通知,請讓你的程式忽略不認得的欄位。移除或改變既有欄位前會在更新紀錄公告。
  • API Key 的保管與經由 key 做的變更由工作區負責,詳見服務條款(另開新視窗)。

相關文件