開發者 API
客脈對外 API 的網址、認證、請求與回應格式、分頁與篩選、限流與錯誤碼,給要串接的工程師。
這一區寫給要把自己的系統接上客脈的工程師。工作區要先開通對外 API 加購模組,並由擁有者或管理員建立 API Key。
網址
每個工作區用自己的網域呼叫 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 | 說明 |
|---|---|---|
401 | UNAUTHENTICATED | key 錯誤、已撤銷、已過期,或建立者已不在工作區 |
402 | MODULE_NOT_ENABLED | 工作區沒有開通對外 API 模組 |
403 | FORBIDDEN | key 的範圍或建立者的角色不能做這件事,或這個路徑沒有開放給 API Key |
404 | NOT_FOUND | 資料不存在或已刪除 |
409 | CONFLICT | 和現有資料衝突 |
422 | VALIDATION_FAILED | 欄位不正確;details.issues 列出每個欄位(path)與原因(code) |
429 | RATE_LIMITED | 超過限流 |
500 | INTERNAL_ERROR | 客脈這邊發生錯誤,請稍後再試;一直發生時請聯絡我們 |
使用規範
- 只開放這份文件寫到的路徑與欄位;其他路徑是客脈畫面專用,可能隨時調整,API Key 呼叫會回
403。 - 我們會盡量維持
/api/v1相容:新增欄位或新的事件類型不另行通知,請讓你的程式忽略不認得的欄位。移除或改變既有欄位前會在更新紀錄公告。 - API Key 的保管與經由 key 做的變更由工作區負責,詳見服務條款(另開新視窗)。