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

資源與欄位

對外 API 開放的路徑:公司、聯絡人、商機、活動紀錄、待辦的讀寫,以及銷售流程、自訂欄位、標籤與成員的讀取。

這一頁列出 API Key 可以呼叫的全部路徑。網址、認證、分頁與錯誤格式見開發者 API。「範圍」欄是 key 需要的範圍:唯讀的 key 只能呼叫「唯讀」的路徑。

公司

方法路徑範圍說明
GET/api/v1/companies唯讀列表
POST/api/v1/companies讀寫新增
GET/api/v1/companies/{id}唯讀讀取一筆
PATCH/api/v1/companies/{id}讀寫修改
DELETE/api/v1/companies/{id}讀寫刪除
PUT/api/v1/companies/{id}/tags讀寫整組取代標籤,見標籤

列表另外的參數:tagId(有這個標籤的)。

欄位類型說明
name文字公司名稱,必填,最多 200 字
taxId文字統一編號,8 碼數字
representative文字代表人,最多 100 字
industry文字產業,最多 100 字
website文字網站,省略 https:// 時會自動補上
address文字地址,最多 300 字
phone文字電話,最多 50 字
ownerIdid我方負責人(成員的 id);新增時沒傳就是 key 的建立者
custom物件自訂欄位,見自訂欄位的值

回應另外有 owner({ id, name })、contactCount(聯絡人數)、tags、createdAt、updatedAt。

聯絡人

方法路徑範圍說明
GET/api/v1/contacts唯讀列表
POST/api/v1/contacts讀寫新增
GET/api/v1/contacts/{id}唯讀讀取一筆
PATCH/api/v1/contacts/{id}讀寫修改
DELETE/api/v1/contacts/{id}讀寫刪除
PUT/api/v1/contacts/{id}/tags讀寫整組取代標籤

列表另外的參數:companyId(這家公司的聯絡人)、tagId。

欄位類型說明
name文字姓名,必填,最多 200 字
title文字職稱,最多 100 字
email文字Email
phone文字電話,最多 50 字
lineId文字LINE ID,最多 100 字
companyIdid所屬公司
ownerIdid我方負責人;新增時沒傳就是 key 的建立者
custom物件自訂欄位

回應的 company 是 { id, name },另外有 owner、tags、createdAt、updatedAt。

商機

方法路徑範圍說明
GET/api/v1/deals唯讀列表
POST/api/v1/deals讀寫新增
GET/api/v1/deals/{id}唯讀讀取一筆,含關聯的聯絡人
PATCH/api/v1/deals/{id}讀寫修改
DELETE/api/v1/deals/{id}讀寫刪除
POST/api/v1/deals/{id}/move讀寫移動階段
POST/api/v1/deals/{id}/contacts讀寫關聯聯絡人
DELETE/api/v1/deals/{id}/contacts/{contactId}讀寫移除關聯的聯絡人
PUT/api/v1/deals/{id}/tags讀寫整組取代標籤

列表另外的參數:pipelineId、stageId、companyId、contactId、tagId、status(open 進行中、won 成交、lost 失敗)。

欄位類型說明
name文字商機名稱,必填,最多 200 字
amount數字金額,0 以上、最多兩位小數
currency文字幣別:TWD(預設)、USD、JPY、CNY、HKD、EUR、SGD
stageIdid階段;新增時沒傳就放在第一條銷售流程的第一個階段
expectedCloseDate日期預計結案日
companyIdid客戶公司
ownerIdid我方負責人;新增時沒傳就是 key 的建立者
contactIdsid 陣列只有新增時可以傳,一併關聯的聯絡人,最多 50 位
custom物件自訂欄位

回應另外有 pipeline、stage({ id, name, kind, probability },kind 是 open、won 或 lost)、closedAt、company、owner、tags;讀取一筆時另有 contacts。

  • 移動階段:{ "stageId": "…", "afterId": null }。afterId 是放在哪一張商機的下面,null 表示該階段的最上面。也可以用 PATCH 改 stageId,會放在新階段的最上面。移到成交或失敗的階段會記下 closedAt。
  • 關聯聯絡人:{ "contactId": "…" },回傳更新後的商機。

活動紀錄

方法路徑範圍說明
GET/api/v1/activities唯讀列表
POST/api/v1/activities讀寫新增
PATCH/api/v1/activities/{id}讀寫修改
DELETE/api/v1/activities/{id}讀寫刪除

列表必須帶 subjectType(company、contact 或 deal)與 subjectId,列出那筆資料的活動紀錄,由新到舊;includeRelated=true 時公司一併列出旗下聯絡人與商機的活動。

欄位類型說明
type文字note 筆記(預設)、call 電話、meeting 會議、email Email、line LINE
body文字內容,必填,最多 10,000 字
occurredAt時間發生時間(ISO 8601,含時區);沒傳就是現在
subject物件關聯的資料,必填:{ "type": "contact", "id": "…" };建立後不能更改

待辦

方法路徑範圍說明
GET/api/v1/tasks唯讀列表
POST/api/v1/tasks讀寫新增
PATCH/api/v1/tasks/{id}讀寫修改
DELETE/api/v1/tasks/{id}讀寫刪除

列表的參數:status(open、done)、assignee(me 或成員的 id)、subjectType 與 subjectId(要一起帶)、includeRelated、dueBefore(截止日在這天以前,含當天)、sort(dueDate 預設、-completedAt、-createdAt)。

欄位類型說明
title文字標題,必填,最多 200 字
notes文字備註,最多 5,000 字
dueDate日期截止日
assigneeIdid指派給誰;新增時沒傳就是 key 的建立者,null 表示不指派
status文字open 或 done;改成 done 就是完成
subject物件關聯的資料(選填),格式同活動紀錄;建立後不能更改

標籤

方法路徑範圍說明
GET/api/v1/tags唯讀工作區的全部標籤(id、name、color、usageCount)

公司、聯絡人、商機的 PUT …/{id}/tags 整組取代那筆資料的標籤:{ "tagIds": ["…", "…"] },最多 20 個,回傳新的標籤;傳空陣列表示拿掉全部標籤。API Key 不能新增標籤,請先在客脈建立好。

銷售流程、自訂欄位、成員

方法路徑範圍說明
GET/api/v1/pipelines唯讀銷售流程與階段(stages 依順序排列)
GET/api/v1/fields唯讀自訂欄位的定義;objectType=company、contact 或 deal 只列一種
GET/api/v1/members唯讀工作區的成員(id、name、email、role),用來指定負責人

這三個路徑和標籤列表都不分頁,一次回傳全部。API Key 不能修改它們。

自訂欄位的值

custom 是「欄位代碼 → 值」的物件,欄位代碼是 /api/v1/fields 回傳的 key:

{ "name": "宏達科技", "custom": { "source": "opt_web", "employees": 120 } }
欄位類型(type)值
text、url文字
number、currency數字(currency 最多兩位小數)
dateYYYY-MM-DD
booleantrue 或 false
select選項的 id(在欄位定義的 options.choices)
multi_select選項 id 的陣列
user成員的 id

新增時必填的自訂欄位一定要有值;修改時只更新有傳的欄位,傳 null 表示清除。

相關文件