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 hook): 전송된 프로젝트당 POST 1회
필수 플랜PRO++(또는 14일 무료 체험)

연결 방식은 두 가지가 있습니다.

  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. 키 복사를 선택합니다.

사용자가 새 키를 선택하거나 연결을 삭제하면 기존 키는 작동을 중지합니다. 키가 누락되었거나 유효하지 않거나 교체된 경우 모든 요청은 {"code": "crm_key_invalid"} 메시지와 함께 401을 반환합니다(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"
}
필드유형설명
connectionIdstring연결 ID
namestring앱에 설정된 연결 이름(최대 24자)
systemstringhubspot, 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 값을 저장하세요. 구독을 해제할 때 필요합니다.

  • 연결당 구독은 하나만 가능합니다. 새 구독을 등록하면 이전 URL이 대체됩니다.
  • URL은 반드시 https://로 시작해야 하며, 길이는 최대 2048자 이하이어야 하고 사용자 이름이나 비밀번호를 포함할 수 없습니다.
  • 비공개 또는 로컬 네트워크를 가리키는 URL(해당 네트워크로 확인되는 호스트 이름 포함)은 거부됩니다: localhost, 127.*, 10.*, 172.16–31.*, 192.168.*, 169.254.*.
상태code의미
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시간이 지나도 프로젝트가 전달되지 않으면 재시도를 중단하고 앱에서 해당 연결 상태를 Error로 표시합니다.
410 Gone키 연결: 구독을 제거합니다. 다시 구독하려면 Zap을 재활성화하세요. URL 연결: 다른 4xx 응답과 동일하게 처리됩니다.
기타 모든 4xx, 리디렉션 또는 인증서 오류재시도하지 않으며, 앱에서 연결 상태를 Error로 표시합니다.

모든 전달 데이터는 서명됩니다. 앱은 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_idstring이번 전송의 고유 ID
planNumberstring프로젝트 ID
planNamestring프로젝트 이름
revisionUrlstring프로젝트 공개 링크
revisionNumberstring프로젝트 리비전
생성됨, 업데이트됨string, ISO 8601프로젝트가 생성된 시간 및 마지막으로 저장된 시간
rooms[]arrayroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]arrayitemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (상품에 대한 사용자 메모, 없으면 null), area (재료용 m²), components[] (상품의 부품: 동일한 필드를 공유하며 quantity는 상품 전체 단위에 대한 수량, quantityPerItem은 단위당 수량; 샘플에서는 quantityPerItem 생략)
price_sourcestringcompany (회사 카탈로그의 가격) 또는 estimate (Home Planner 추정 견적)
sourcestringcompany (회사 카탈로그의 제품) 또는 homeplanner (Home Planner 카탈로그)
totalsobjectitems: 최상위 품목 수(부품 제외), sum: 부품을 포함한 추정 견적 총액, currency: 통화 코드
pdfUrlstring 또는 null평면도 PDF 링크(파일은 7일간 유지됨)
productsTextstring일반 텍스트 형식의 전체 견적서
warningstring 또는 null예: "2 item(s) without SKU were sent with a Home Planner code"
integrationstring항상 "custom"

요청 제한(Rate limits)

범위제한
단일 연결 키당분당 30회 요청, 일당 500회
유효하지 않은 키를 사용한 요청(IP 주소당)분당 300회, 일당 5000회

제한을 초과하면 API가 {"code": "crm_throttled"} 메시지와 함께 429를 반환합니다.

오류

모든 오류는 code 필드가 포함된 JSON 형식으로 반환됩니다. (예: {"code": "crm_key_invalid"})

상태code의미
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

나만의 프로젝트에서 직접 시도해 보세요

무료 방 계획 및 인테리어 디자인 앱