資源與欄位
對外 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 字 |
ownerId | id | 我方負責人(成員的 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 | 文字 | |
phone | 文字 | 電話,最多 50 字 |
lineId | 文字 | LINE ID,最多 100 字 |
companyId | id | 所屬公司 |
ownerId | id | 我方負責人;新增時沒傳就是 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 |
stageId | id | 階段;新增時沒傳就放在第一條銷售流程的第一個階段 |
expectedCloseDate | 日期 | 預計結案日 |
companyId | id | 客戶公司 |
ownerId | id | 我方負責人;新增時沒傳就是 key 的建立者 |
contactIds | id 陣列 | 只有新增時可以傳,一併關聯的聯絡人,最多 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 | 日期 | 截止日 |
assigneeId | id | 指派給誰;新增時沒傳就是 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 最多兩位小數) |
date | YYYY-MM-DD |
boolean | true 或 false |
select | 選項的 id(在欄位定義的 options.choices) |
multi_select | 選項 id 的陣列 |
user | 成員的 id |
新增時必填的自訂欄位一定要有值;修改時只更新有傳的欄位,傳 null 表示清除。