Home Planner CRM API 参考文档

了解供 Zapier、Make 和你自己服务器使用的 Home Planner CRM API 端点、身份验证、Webhook 推送与项目记录格式。

Home Planner CRM API 可将 Home Planner 应用连接至 Zapier、Make 以及你自己的服务器。它包含 4 个端点(均需使用连接密钥完成身份验证),以及 1 个用于推送用户所发送项目的 Webhook。
本页面面向开发者和集成平台。如需了解如何在应用中配置项目发送功能,请参阅如何将项目从 Home Planner 发送到你的 CRM。
概览
| 项目 | 数值 |
|---|---|
| 基础 URL | https://icandesignapp.com(请使用此主机:从 homeplannerapp.com 进行重定向可能会丢失 POST 请求体) |
| 格式 | 基于 HTTPS 的 JSON |
| 身份验证 | 包含在 X-Api-Key 请求头中的连接密钥 |
| 推送方式 | Webhook (REST hook):每发送一个项目触发一次 POST 请求 |
| 所需订阅计划 | PRO++(或其 14 天免费试用) |
有两种连接方式:
- 密钥连接 — 适用于 Zapier 和 Make。用户在应用中选择 CRM 并复制密钥;平台通过 POST /crm/key/hooks 订阅其 Webhook。本页面将对这种方式展开说明。
- 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 中。
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>用户可以在 Home Planner 应用中获取密钥:
- 打开设置,选择项目发送目的地。
- 选择添加连接,然后选择 HubSpot、Pipedrive、Bitrix24、Salesforce 或 Google Sheets。
- 选择复制密钥。
当用户选择新密钥或删除连接时,原密钥将失效。任何携带缺失、无效或已被替换密钥的请求均会返回 401 及 {"code": "crm_key_invalid"}(DELETE 请求除外,详情见下文)。
GET /crm/key/me
返回密钥所归属的连接。Zapier 会通过调用此端点来测试并命名新连接。
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'响应 200:
{
"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 会调用此端点。
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:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}请保存此 id:取消订阅时需要用到它。
- 每个连接仅限一个订阅:新建订阅将直接替换先前的 URL。
- URL 必须以 https:// 开头,长度不得超过 2048 个字符,且不能包含用户名或密码。
- 指向私有网络或局域网的 URL(包括解析至这些网络的域名)将被拒绝:localhost、127.*、10.*、172.16–31.*、192.168.* 以及 169.254.*。
| 状态 | 代码 | 含义 |
|---|---|---|
| 401 | crm_key_invalid | 密钥缺失、无效或已被替换 |
| 422 | crm_url_invalid | 非 https:// URL,或长度超过 2048 个字符 |
| 422 | crm_url_credentials | URL 中包含了用户名或密码 |
| 422 | crm_url_forbidden | URL 指向了私有网络或局域网 |
其他错误:参阅下方的错误说明。
DELETE /crm/key/hooks/{id}
移除指定 id 的订阅。当 Zap 被关闭或删除时,Zapier 会调用此端点。
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 字段。
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-Type | application/json |
| 请求体 | 一条项目记录 |
| X-HomePlanner-Delivery | 推送 ID。重试期间保持不变:可用于重复请求检测。 |
| X-HomePlanner-Signature | t=<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。
{
"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"}。
| 状态 | 代码 | 含义 |
|---|---|---|
| 401 | crm_key_invalid | 密钥缺失、无效或已被替换 |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | Webhook URL 被拒绝 |
| 429 | crm_throttled | 已达到速率限制 |
| 503 | crm_unavailable | 服务器临时故障;请稍后重试 |
技术支持
如对 API 有任何疑问,请发送邮件至:[email protected]。
商标声明。Zapier、Make、HubSpot、Pipedrive、Bitrix24、Salesforce 和 Google Sheets 均为其各自所有者的商标。Home Planner 独立于这些公司,未获得其认可、赞助,亦与其无关联关系。
在你的专属项目中试用
免费的房间规划与室内设计应用


