Home Planner
返回說明中心操作指南

Home Planner CRM API 參考指南

Home Planner
Home Planner應用程式團隊 · October 28, 2026

Zapier、Make 與你自己的伺服器所使用的 Home Planner CRM API 端點、驗證、Webhook 傳送及專案紀錄。

Home Planner 應用程式透過 Zapier 將房間設計專案傳送至 HubSpot、Salesforce、Google Sheets 和 Pipedrive

Home Planner CRM API 將 Home Planner 應用程式連接至 Zapier、Make 和你自己的伺服器。此 API 包含四個端點(皆透過金鑰驗證)以及一個傳送使用者每個專案的 Webhook。

本頁面供開發人員與整合平台參考。要在應用程式中設定專案傳送,請參閱如何將 Home Planner 的專案傳送到你的 CRM。

總覽

項目數值
基礎網址https://icandesignapp.com(請使用此主機名稱:從 homeplannerapp.com 重定向可能會遺失 POST 主體)
格式透過 HTTPS 傳送 JSON
驗證在 X-Api-Key 標頭帶入連線金鑰
傳送方式Webhook (REST hook):每傳送一個專案發送一次 POST
方案要求PRO++(或其 14 天免費試用版)

有兩種連線方式:

  1. 金鑰連線 — 適用於 Zapier 與 Make。使用者在應用程式中選擇 CRM 並複製金鑰;平台則透過 POST /crm/key/hooks 訂閱其 Webhook。本頁面將介紹此方式。
  2. URL 連線 — 適用於你自己的伺服器。使用者在應用程式中選擇其他系統 (你的 URL)並輸入 URL。此方式不需要金鑰和端點,應用程式會顯示簽署密鑰。
方法端點用途
GET/crm/key/me驗證金鑰並回傳連線名稱
POST/crm/key/hooks訂閱 Webhook URL
DELETE/crm/key/hooks/{id}取消訂閱 Webhook
GET/crm/key/sample取得範例專案紀錄

驗證

每個請求都必須在 X-Api-Key 標頭中帶入連線金鑰。每組金鑰對應單一 Home Planner 帳號中的單一 CRM 連線。切勿將金鑰放在 URL 中。

yamlyaml
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>

使用者可以在 Home Planner 應用程式中取得金鑰:

  1. 開啟設定並選擇專案傳送位置。
  2. 選擇新增連線,然後選擇 HubSpot、Pipedrive、Bitrix24、Salesforce 或 Google Sheets。
  3. 選擇複製金鑰。

當使用者選擇新金鑰或刪除連線時,原金鑰即失效。使用遺失、無效或已被替換的金鑰進行請求都會回傳 401 與 {"code": "crm_key_invalid"}(DELETE 例外,詳情如下)。

GET /crm/key/me

回傳該金鑰所屬的連線。Zapier 會呼叫此端點來測試新連線並為其命名標籤。

bashbash
curl https://icandesignapp.com/crm/key/me \
  -H 'X-Api-Key: hp_live_…'

回應 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
欄位型別說明
connectionId字串連線 ID
名稱字串來自應用程式的連線名稱,最多 24 個字元
系統字串hubspot、pipedrive、bitrix24、salesforce 或 sheets

錯誤:401 crm_key_invalid。其他錯誤請參閱下方「錯誤」。

POST /crm/key/hooks

設定接收透過此連線傳送之每個專案的 Webhook URL。Zapier 會在開啟 Zap 時呼叫此端點。

bashbash
curl -X POST https://icandesignapp.com/crm/key/hooks \
  -H 'X-Api-Key: hp_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://hooks.zapier.com/hooks/standard/123456/abcdef/"}'

回應 201:

jsonjson
{
  "id": "3f2b9c0d1e4a5b6c7d8e9f01"
}

請儲存 id:取消訂閱時需要用到它。

  • 每個連線僅限一個訂閱:新的訂閱將會覆蓋先前的 URL。
  • URL 開頭必須為 https://,長度不得超過 2048 個字元,且不能包含使用者名稱或密碼。
  • 指向私人或區域網路的 URL(包含解析至這些網路的主機名稱)將被拒絕:localhost、127.*、10.*、172.16–31.*、192.168.* 以及 169.254.*。
狀態代碼意義
401crm_key_invalid金鑰遺失、無效或已被替換
422crm_url_invalid非 https:// URL,或長度超過 2048 個字元
422crm_url_credentialsURL 包含使用者名稱或密碼
422crm_url_forbiddenURL 指向私人或區域網路

其他錯誤請參閱下方「錯誤」。

DELETE /crm/key/hooks/{id}

移除具有此 id 的訂閱。Zapier 會在關閉或刪除 Zap 時呼叫此端點。

bashbash
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
  -H 'X-Api-Key: hp_live_…'

回應 204 且無主體內容。若 ID 與目前的訂閱不符、金鑰已被替換或連線已被刪除,回應同樣為 204。在這些情況下,皆代表已無可移除的項目。

錯誤:針對遺失的金鑰或從未有效的金鑰回傳 401 crm_key_invalid。其他錯誤請參閱下方「錯誤」。

GET /crm/key/sample

回傳包含一個範例專案紀錄的陣列,格式與實際發送的資料相同。Zapier 會顯示其欄位,以便使用者將其對映至 CRM 欄位。

bashbash
curl https://icandesignapp.com/crm/key/sample \
  -H 'X-Api-Key: hp_live_…'

回應 200:包含一個專案紀錄的陣列(詳見下方)。

錯誤:401 crm_key_invalid。其他錯誤請參閱下方「錯誤」。

Webhook 傳送

當使用者在應用程式中選擇「分享」→「傳送至…」時,Home Planner 會將專案發送至已訂閱的 URL。

部分數值
方法POST
Content-Typeapplication/json
主體一個專案紀錄
X-HomePlanner-Delivery傳送 ID。重試時保持不變:可用於偵測重複傳送。
X-HomePlanner-Signaturet=<以秒為單位的 Unix 時間>,v1=<小寫十六進位>,其中 v1 = HMAC-SHA256(簽署密鑰, t + "." + 原始主體)
你的回應Home Planner 的處理方式
15 秒內回傳任何 2xx已成功傳送
15 秒內無回應、5xx、408 或 429會在 1 分鐘、10 分鐘和 1 小時後重試。若首次嘗試 2 小時後專案仍未成功傳送,將停止重試並在應用程式中將此連線標示為「錯誤」。
410 已移除金鑰連線:移除訂閱;請重新開啟 Zap 以再次訂閱。URL 連線:與任何其他 4xx 相同
任何其他 4xx、重定向或憑證錯誤不重試;應用程式會將連線標示為「錯誤」

每一次傳送皆經過簽署。應用程式僅針對 URL 連線顯示簽署密鑰。有關簽署驗證步驟,請參閱如何將 Home Planner 的專案傳送到你的 CRM。

當使用者的 PRO++ 訂閱或免費試用結束時,應用程式會停止傳送專案。端點仍會繼續回應,因此 Zap 會保持開啟狀態,但直到使用者續訂前都不會收到新專案。

專案紀錄

每一次傳送與範例端點皆使用此格式。價格與總計與應用程式中的專案估算相符。在 Zapier 中,該紀錄還有一個 id 欄位:為 client_reference_id 的副本,顯示為 Send ID。

project-record.jsonjson
{
  "client_reference_id": "sample_0d4f1c2b9e7a",
  "planNumber": "000000000000000000000000",
  "planName": "Sample project",
  "revisionUrl": "https://share.roomplannerapp.com/all/project/000000000000000000000000",
  "revisionNumber": "1",
  "updated": "2026-10-01T12:00:00.000Z",
  "created": "2026-09-28T09:30:00.000Z",
  "rooms": [
    {
      "roomNumber": "6f1d2c3b4a5e6f708192a3b4c5d6e7f8",
      "roomName": "Living room",
      "items": [
        {
          "itemNumber": "SOFA-1042",
          "quantity": 1,
          "imageURL": "https://files.icandesignapp.com/sample/sofa.jpg",
          "components": [
            {
              "itemNumber": "CUSH-17",
              "quantity": 2,
              "imageURL": "",
              "name": "Cushion",
              "price": 25,
              "currency": "USD",
              "total": 50,
              "price_source": "estimate",
              "source": "homeplanner"
            }
          ],
          "name": "Sofa Oslo",
          "price": 899,
          "currency": "USD",
          "total": 899,
          "price_source": "company",
          "source": "company",
          "note": null
        },
        {
          "itemNumber": "Floor_Oak_01",
          "quantity": 1,
          "imageURL": "",
          "name": "Oak flooring",
          "price": 540,
          "currency": "USD",
          "total": 540,
          "price_source": "estimate",
          "source": "homeplanner",
          "note": null,
          "area": 18
        }
      ],
      "roomType": "LivingRoom",
      "area": 18,
      "height": 2.7,
      "width": 4,
      "depth": 4.5
    }
  ],
  "integration": "custom",
  "totals": {
    "items": 2,
    "sum": 1489,
    "currency": "USD"
  },
  "warning": null,
  "pdfUrl": "https://files.icandesignapp.com/sample/plan.crm.pdf",
  "productsText": "Living room:\n- Sofa Oslo (SOFA-1042): 1 × 899.00 = 899.00 USD\n  - Cushion (CUSH-17): 2 × 25.00 = 50.00 USD\n- Oak flooring (Floor_Oak_01): 1 × 540.00 = 540.00 USD\n\nTotal: 1489.00 USD"
}
欄位型別說明
client_reference_id字串本次傳送的唯一 ID
planNumber字串專案 ID
planName字串專案名稱
revisionUrl字串專案的公開連結
revisionNumber字串專案修訂版本
已建立、已更新字串,ISO 8601專案建立與上次儲存的時間
rooms[]陣列roomNumber、roomName、roomType、area (m²)、height、width、depth (m)、items
rooms[].items[]陣列itemNumber (SKU)、name、quantity、price、currency、total、price_source、source、imageURL、note(使用者對該項目的備註,或為 null)、area(m²,用於材料)、components[](項目的組件:相同欄位,其中 quantity 為該項目所有單位的數量,加上 quantityPerItem,即每個單位的數量;範例中會省略 quantityPerItem)
價格來源字串company(來自公司目錄的價格)或 estimate(Home Planner 估算金額)
來源字串company(來自公司目錄的商品)或 homeplanner(Home Planner 目錄)
總計物件items:頂層明細項目數量(不含組件);sum:估算總額(含組件);currency:貨幣代碼
pdfUrl字串或 null平面圖 PDF 連結;檔案保留 7 天
productsText字串純文字格式的完整估算表
警告字串或 null例如:"2 item(s) without SKU were sent with a Home Planner code"
整合字串固定為 "custom"

速率限制

範圍限制
單一連線金鑰每分鐘 30 次請求,每天 500 次
使用無效金鑰的請求(每個 IP 位址)每分鐘 300 次請求,每天 5000 次

超出速率限制時,API 會回傳 429 與 {"code": "crm_throttled"}。

錯誤

每個錯誤皆為帶有 code 欄位的 JSON,例如 {"code": "crm_key_invalid"}。

狀態代碼意義
401crm_key_invalid金鑰遺失、無效或已被替換
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenWebhook URL 被拒絕
429crm_throttled已達速率限制
503crm_unavailable伺服器暫時性問題;請稍後重試

支援

有關 API 的疑問請洽:[email protected]。

商標聲明。 Zapier、Make、HubSpot、Pipedrive、Bitrix24、Salesforce 及 Google Sheets 為其各自所有者的商標。Home Planner 獨立於這些公司之外,且未獲得其背書、贊助或與其有任何隸屬關係。

Home Planner

親自試用你的專案

免費的房間規劃與室內設計 App