Home Planner
返回帮助中心操作指南

Home Planner CRM API 参考文档

Home Planner
Home PlannerApp 团队 · 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 以及你自己的服务器。它包含 4 个端点(均需使用连接密钥完成身份验证),以及 1 个用于推送用户所发送项目的 Webhook。

本页面面向开发者和集成平台。如需了解如何在应用中配置项目发送功能,请参阅如何将项目从 Home Planner 发送到你的 CRM。

概览

项目数值
基础 URLhttps://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。开启 Zap 时,Zapier 会调用此端点。

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 的订阅。当 Zap 被关闭或删除时,Zapier 会调用此端点。

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 会将项目以 POST 请求形式发送至已订阅的 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)
price_source字符串company(来自公司目录的价格)或 estimate(Home Planner 预算)
source字符串company(来自公司目录的产品)或 homeplanner(Home Planner 目录)
totals对象items:顶层明细项数量(不计入组件);sum:预算总计,包含组件;currency:货币代码
pdfUrl字符串或 null平面图 PDF 链接;文件有效期为 7 天
productsText字符串纯文本格式的完整预算
warning字符串或 null例如:"2 item(s) without SKU were sent with a Home Planner code"(有 2 个无 SKU 的物品随 Home Planner 代码一同发送)
integration字符串固定为 "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

在你的专属项目中试用

免费的房间规划与室内设计应用