# CRM REST API 與簽署 Webhook | AiCrm

> 具備公開 REST API 的 CRM：用 X-Api-Key 標頭建立與查詢聯絡人，每個整合最多 20 組金鑰，並提供以 HMAC-SHA256 簽署的對外 Webhook。從網站新增潛在客戶，不會重複。

- **來源 (source):** https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- **平台 (platform):** AIstoHire
- **語言 (language):** zh

## 重點摘要

- 公開 REST API：支援多組 API key 與簽署的 Webhook
- 透過一次 HTTP 呼叫，就能從你的網站、表單或後端新增客戶，並在你的伺服器收到以 HMAC-SHA256 簽署的每一項變更。
- 一次呼叫就能新增聯絡人：對 `/api/apps/public/crm/customers` 發送一個 POST，附上電子郵件與你想要的標籤，潛在客戶就已分類好存在你的 CRM 中。
- 設計上不會重複：如果電子郵件已存在，就會更新該筆資料，並在其時間軸記錄這次新的送出，而不是另外建立第二筆。
- 最多可建立 20 組具名金鑰：每個整合各用一組，可分別撤銷。若某組金鑰外洩，只要刪除那一組，其他功能完全不受影響。

## 公開 REST API：支援多組 API key 與簽署的 Webhook

AiCrm 是 AIsToHire 的 CRM 應用程式，針對你自己的聯絡人提供公開的 REST API。只要在 `X-Api-Key` 標頭帶上金鑰，就能從你的網站表單、聊天機器人、Zap、Python 指令碼或你自己的後端，建立、列出、查詢、更新與刪除聯絡人，並為其中任何一位新增活動。回應為 `{ success, data }` 格式的 JSON，限制為每組金鑰每分鐘 100 次請求。

透過 API 新增不會產生重複：如果你送出的電子郵件已存在於資料庫，AiCrm 會更新你原有的資料（補上缺少的電話、姓名或公司，並合併標籤），並在其時間軸記錄一次新的送出，回傳 HTTP 200；若是新的聯絡人，則建立並回傳 201。每位透過 API 進來的聯絡人都會自動標上 `api-lead`，保留你傳送的標籤，並記錄來源的 `subId`，以及來訪的國家、IP 與瀏覽器。

你最多可以擁有 20 組自訂名稱的 API key，另外還有應用程式的內部金鑰。這樣就能為每個整合各發一組不同的金鑰——網站、五月活動的表單、實習生、供應商——並在該整合結束時單獨撤銷，不影響其他的。金鑰的完整值只會在建立時顯示一次，之後在清單中僅以遮罩顯示。

反方向則由 Webhook 通知你的系統。你最多可設定 10 個目的地，選擇每個目的地訂閱哪些事件（`customer.created`、`customer.updated`、`customer.deleted`、`activity.created`），AiCrm 會對你的網址發出 POST，並帶上 `X-AiCrm-Event` 與 `X-AiCrm-Signature: sha256=…` 標頭——也就是以該 Webhook 的密鑰對內容計算的 HMAC-SHA256 簽章——讓你驗證通知是否合法。儲存網址時，SSRF 防護會拒絕 localhost、127.0.0.0/8、10.x、192.168.x、172.16-31.x、::1、0.0.0.0，以及 `.local` 與 `.internal` 網域。

## 包含內容

- 一次呼叫就能新增聯絡人：對 `/api/apps/public/crm/customers` 發送一個 POST，附上電子郵件與你想要的標籤，潛在客戶就已分類好存在你的 CRM 中。
- 設計上不會重複：如果電子郵件已存在，就會更新該筆資料，並在其時間軸記錄這次新的送出，而不是另外建立第二筆。
- 最多可建立 20 組具名金鑰：每個整合各用一組，可分別撤銷。若某組金鑰外洩，只要刪除那一組，其他功能完全不受影響。
- 以 HMAC-SHA256 簽署的 Webhook：用你的密鑰驗證 `X-AiCrm-Signature` 標頭，就能確認通知來自你的 CRM，而非第三方。
- 內建 SSRF 防護：應用程式會拒絕將 Webhook 送往 localhost 或私有網段，因此你的 CRM 不會被拿來探測內部網路。
- 完整的 CRUD，不只是新增：可分頁並依搜尋、狀態、標籤、國家篩選列出聯絡人，查詢單一聯絡人及其活動、更新、刪除，並為其登錄活動。
- 自動追蹤來源：每筆透過 API 新增的資料都會記錄你傳送的 `subId`，以及國家、IP 與瀏覽器，並標上 `api-lead` 標籤，方便之後在應用程式中篩選。
- 測試不必猜：應用程式內附端點文件，提供可複製的 `curl` 範例，以及可對每個 Webhook 發送測試通知的按鈕，並顯示最近一次嘗試的狀態與時間。

## 常見問題

### 如何從我的網站在 CRM 中建立聯絡人？

對 `/api/apps/public/crm/customers` 發送 POST，標頭帶上 `X-Api-Key`，內容為 JSON，且至少包含電子郵件或電話。你也可以一併傳送姓名、電話、公司、國家、狀態、備註、標籤，以及用來識別來源活動或表單的 `subId`。AiCrm 在建立新聯絡人時回傳 201，若該聯絡人已存在則回傳 200。

### 如果同一個電子郵件透過 API 送入兩次，會怎麼樣？

不會重複。AiCrm 會搜尋電子郵件（若沒傳電子郵件，則搜尋電話），找到時就更新現有資料，補上空白的欄位，把新標籤與原有標籤合併，並在其活動時間軸中記錄這次新的送出。回應中會說明該聯絡人已存在，並回傳其 id。

### 我可以有幾組 API key？能只撤銷其中一組嗎？

你最多可建立 20 組自訂名稱的金鑰，另外還有應用程式的內部金鑰（無法刪除）。每組金鑰可獨立刪除，因此你能為每個整合各發一組，撤銷時不影響其他整合。完整金鑰值只會在建立當下顯示一次，之後在清單中會以遮罩顯示。所有金鑰的限制皆為每組每分鐘 100 次請求。

### 如何確認 Webhook 真的來自我的 CRM？

每次送出的通知都帶有標頭 `X-AiCrm-Signature: sha256=<簽章>`，這是以應用程式在你建立 Webhook 時顯示的密鑰，對請求的完整內容計算出的 HMAC-SHA256。請在你的伺服器上針對收到的內容計算同樣的 HMAC，並進行比對。此外還會附帶 `X-AiCrm-Event` 標頭，內含事件名稱：`customer.created`、`customer.updated`、`customer.deleted` 或 `activity.created`。

### 如果我的 Webhook 端點當機，會怎麼樣？

通知採盡力而為（best-effort）的方式：AiCrm 最多等待 5 秒，若失敗，會在 1.5 秒後重試一次。沒有持久化的重試佇列，因此如果你的伺服器長時間當機，可能會遺失通知；這種情況下，請以 GET 呼叫 `/api/apps/public/crm/customers` 進行對帳。應用程式會顯示每個 Webhook 最近一次嘗試的狀態與時間，你也可以隨時發送測試通知。

- [AiCrm — 具備 API 的輕量 CRM，可從任何系統新增客戶](https://aistohire.com/zh/ai-crm-rest-api-webhooks-109)

## 關於平台

**AiCrm — 具備 API 的輕量 CRM，可從任何系統新增客戶** — 應用程式，來自 AIstoHire. 可在以下網址使用: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook

### 其他語言

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `it`: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- `pt`: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `ar`: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
