Home Planner
ヘルプセンターに戻るハウツーガイド

Home Planner CRM APIリファレンス

Home Planner
Home Plannerアプリチーム · October 28, 2026

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

Home PlannerアプリからZapierを経由してHubSpot、Salesforce、Google Sheets、Pipedriveへ部屋のデザインプロジェクトを送信できます。

Home Planner CRM APIは、Home PlannerアプリをZapier、Make、独自サーバーに接続します。エンドポイントは4つあり、すべて接続キーで認証されます。また、ユーザーが送信した各プロジェクトを届けるウェブフックが1つ用意されています。

このページは開発者および連携プラットフォーム向けの内容です。アプリでプロジェクトの送信を設定する方法については、Home PlannerからCRMへプロジェクトを送信する方法をご覧ください。

概要

項目値
ベースURLhttps://icandesignapp.com (こちらのホストを使用してください。homeplannerapp.comからのリダイレクトではPOSTデータが失われる可能性があります)
フォーマットHTTPS経由のJSON
認証X-Api-Keyヘッダーに含まれる接続キー
配信ウェブフック(RESTフック):送信されたプロジェクト1件につき1つのPOST
必要なプランPRO++(または14日間の無料トライアル)

接続方法には以下の2つがあります。

  1. キー接続 — ZapierおよびMake用。ユーザーがアプリでCRMを選択してキーをコピーし、プラットフォーム側がPOST /crm/key/hooksでウェブフックを登録します。このページでは、この方法について説明します。
  2. 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に含めないでください。

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
name文字列アプリからの接続名(最大24文字)
system文字列hubspot、pipedrive、bitrix24、salesforce、sheetsのいずれか

エラー:401 crm_key_invalid。その他のエラー:下記のエラー項目を参照してください。

POST /crm/key/hooks

この接続経由で送信されるすべてのプロジェクトを受信するウェブフック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を保存してください。登録解除時に必要となります。

  • 1つの接続につき1つの登録となります。新しく登録すると、以前のURLが上書きされます。
  • URLはhttps://で始まり、2048文字以内である必要があり、ユーザー名やパスワードを含めることはできません。
  • プライベートネットワークやローカルネットワークを指すURL(それらに解決されるホスト名を含む)は拒否されます:localhost、127.*、10.*、172.16〜31.*、192.168.*、169.254.*。
ステータスコード意味
401crm_key_invalidキーが欠落しているか、無効であるか、または置き換えられています
422crm_url_invalidhttps://で始まる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

実際の配信と同じフォーマットで、サンプルプロジェクトのレコードを1件含む配列を返します。Zapierはこのフィールドを表示し、ユーザーがCRMのフィールドにマッピングできるようにします。

bashbash
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-Typeapplication/json
ボディプロジェクトレコード1件
X-HomePlanner-Delivery配信ID。再試行されても変更されません。重複検出に使用します。
X-HomePlanner-Signaturet=<UNIX秒数>,v1=<小文字の16進数>。ここで v1 = HMAC-SHA256(署名シークレット, t + "." + 生ボディ)
サーバーのレスポンスHome Plannerの動作
15秒以内の任意の2xx配信完了
15秒以内にレスポンスなし、5xx、408、または4291分後、10分後、1時間後に再試行します。初回試行から2時間経過しても配信されない場合、再試行を停止し、アプリ上で接続ステータスをエラーとマークします。
410 Goneキー接続:登録を削除します。再登録するにはZapを再度オンにしてください。URL接続:他の4xxエラーと同様に処理されます。
その他の4xx、リダイレクト、または証明書エラー再試行は行われません。アプリは接続ステータスをエラーとマークします。

すべての配信には署名が付与されます。アプリにはURL接続の場合にのみ署名シークレットが表示されます。署名の検証手順については、Home PlannerからCRMへプロジェクトを送信する方法をご覧ください。

ユーザーのPRO++サブスクリプションまたは無料トライアルが終了すると、アプリからのプロジェクト送信が停止します。エンドポイントはレスポンスを返し続けるため、Zapはオンのまま維持されますが、ユーザーが更新するまで新しいプロジェクトは届きません。

プロジェクトレコード

すべての配信およびサンプルエンドポイントでは、このフォーマットが使用されます。価格および合計金額は、アプリ内のプロジェクト見積もりと一致します。Zapierでは、このレコードに送信IDとして表示されるclient_reference_idのコピーである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文字列プロジェクトのリビジョン
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"}

ステータスコード意味
401crm_key_invalidキーが欠落しているか、無効であるか、または置き換えられています
422crm_url_invalid、crm_url_credentials、crm_url_forbiddenウェブフックURLが拒否されました
429crm_throttledレート制限に達しました
503crm_unavailable一時的なサーバーの問題です。後で再試行してください。

サポート

APIに関する質問:[email protected]

商標に関する記述。 Zapier、Make、HubSpot、Pipedrive、Bitrix24、Salesforce、Google Sheetsは各所有者の商標です。Home Plannerはこれらの企業とは独立しており、承認、スポンサーシップ、提携関係はありません。

Home Planner

ご自身のプロジェクトで試す

無料で使えるルームプランナー&インテリアデザインアプリ