Home Planner CRM APIリファレンス

Zapier、Make、独自サーバーで使用されるHome Planner CRM APIのエンドポイント、認証、ウェブフック配信、プロジェクトレコードについて説明します。

Home Planner CRM APIは、Home PlannerアプリをZapier、Make、独自サーバーに接続します。エンドポイントは4つあり、すべて接続キーで認証されます。また、ユーザーが送信した各プロジェクトを届けるウェブフックが1つ用意されています。
このページは開発者および連携プラットフォーム向けの内容です。アプリでプロジェクトの送信を設定する方法については、Home PlannerからCRMへプロジェクトを送信する方法をご覧ください。
概要
| 項目 | 値 |
|---|---|
| ベースURL | https://icandesignapp.com (こちらのホストを使用してください。homeplannerapp.comからのリダイレクトではPOSTデータが失われる可能性があります) |
| フォーマット | HTTPS経由のJSON |
| 認証 | X-Api-Keyヘッダーに含まれる接続キー |
| 配信 | ウェブフック(RESTフック):送信されたプロジェクト1件につき1つのPOST |
| 必要なプラン | PRO++(または14日間の無料トライアル) |
接続方法には以下の2つがあります。
- キー接続 — ZapierおよびMake用。ユーザーがアプリでCRMを選択してキーをコピーし、プラットフォーム側がPOST /crm/key/hooksでウェブフックを登録します。このページでは、この方法について説明します。
- URL接続 — 独自サーバー用。ユーザーがアプリでその他のシステム(独自URL)を選択し、そこにURLを入力します。キーやエンドポイントは不要で、アプリに署名シークレットが表示されます。
| メソッド | エンドポイント | 目的 |
|---|---|---|
| GET | /crm/key/me | キーを検証し、接続名を返します |
| POST | /crm/key/hooks | ウェブフックURLを登録します |
| DELETE | /crm/key/hooks/{id} | ウェブフックの登録を解除します |
| 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 |
| name | 文字列 | アプリからの接続名(最大24文字) |
| system | 文字列 | hubspot、pipedrive、bitrix24、salesforce、sheetsのいずれか |
エラー:401 crm_key_invalid。その他のエラー:下記のエラー項目を参照してください。
POST /crm/key/hooks
この接続経由で送信されるすべてのプロジェクトを受信するウェブフックURLを設定します。ZapierはZapがオンにされた際にこれを呼び出します。
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を保存してください。登録解除時に必要となります。
- 1つの接続につき1つの登録となります。新しく登録すると、以前の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の登録を削除します。ZapierはZapがオフにされた際、または削除された際にこれを呼び出します。
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
実際の配信と同じフォーマットで、サンプルプロジェクトのレコードを1件含む配列を返します。Zapierはこのフィールドを表示し、ユーザーがCRMのフィールドにマッピングできるようにします。
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'レスポンス 200:1つのプロジェクトレコードを含む配列(下記参照)。
エラー:401 crm_key_invalid。その他のエラー:下記のエラー項目を参照してください。
ウェブフック配信
ユーザーがアプリで共有 → …へ送信を選択すると、Home Plannerは登録されているURLにプロジェクトを送信(POST)します。
| 要素 | 値 |
|---|---|
| メソッド | POST |
| Content-Type | application/json |
| ボディ | プロジェクトレコード1件 |
| X-HomePlanner-Delivery | 配信ID。再試行されても変更されません。重複検出に使用します。 |
| X-HomePlanner-Signature | t=<UNIX秒数>,v1=<小文字の16進数>。ここで v1 = HMAC-SHA256(署名シークレット, t + "." + 生ボディ) |
| サーバーのレスポンス | Home Plannerの動作 |
|---|---|
| 15秒以内の任意の2xx | 配信完了 |
| 15秒以内にレスポンスなし、5xx、408、または429 | 1分後、10分後、1時間後に再試行します。初回試行から2時間経過しても配信されない場合、再試行を停止し、アプリ上で接続ステータスをエラーとマークします。 |
| 410 Gone | キー接続:登録を削除します。再登録するにはZapを再度オンにしてください。URL接続:他の4xxエラーと同様に処理されます。 |
| その他の4xx、リダイレクト、または証明書エラー | 再試行は行われません。アプリは接続ステータスをエラーとマークします。 |
すべての配信には署名が付与されます。アプリにはURL接続の場合にのみ署名シークレットが表示されます。署名の検証手順については、Home PlannerからCRMへプロジェクトを送信する方法をご覧ください。
ユーザーのPRO++サブスクリプションまたは無料トライアルが終了すると、アプリからのプロジェクト送信が停止します。エンドポイントはレスポンスを返し続けるため、Zapはオンのまま維持されますが、ユーザーが更新するまで新しいプロジェクトは届きません。
プロジェクトレコード
すべての配信およびサンプルエンドポイントでは、このフォーマットが使用されます。価格および合計金額は、アプリ内のプロジェクト見積もりと一致します。Zapierでは、このレコードに送信IDとして表示されるclient_reference_idのコピーである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 | 文字列 | プロジェクトのリビジョン |
| created、updated | 文字列、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は商品のすべてのユニットに対する総数、さらに1ユニットあたりの数量を表すquantityPerItemを含みます。サンプルではquantityPerItemは省略されます) |
| price_source | 文字列 | company(自社カタログの価格)またはestimate(Home Plannerの見積もり) |
| source | 文字列 | company(自社カタログの商品)またはhomeplanner(Home Plannerカタログ) |
| totals | オブジェクト | items:トップレベルの品目数(コンポーネントはカウントされません)、sum:見積もり合計(コンポーネントを含む)、currency:通貨コード |
| pdfUrl | 文字列またはnull | 間取り図PDFへのリンク。ファイルは7日間有効です。 |
| productsText | 文字列 | プレーンテキスト形式の完全な見積もり |
| warning | 文字列またはnull | 例:「SKUのない商品2件がHome Plannerコードで送信されました」 |
| integration | 文字列 | 常に"custom" |
レート制限
| スコープ | 制限 |
|---|---|
| 接続キー1つにつき | 1分あたり30リクエスト、1日あたり500リクエスト |
| 無効なキーでのリクエスト(IPアドレスごと) | 1分あたり300リクエスト、1日あたり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 | ウェブフックURLが拒否されました |
| 429 | crm_throttled | レート制限に達しました |
| 503 | crm_unavailable | 一時的なサーバーの問題です。後で再試行してください。 |
サポート
APIに関する質問:[email protected]
商標に関する記述。 Zapier、Make、HubSpot、Pipedrive、Bitrix24、Salesforce、Google Sheetsは各所有者の商標です。Home Plannerはこれらの企業とは独立しており、承認、スポンサーシップ、提携関係はありません。
ご自身のプロジェクトで試す
無料で使えるルームプランナー&インテリアデザインアプリ


