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 hook): 전송된 프로젝트당 POST 1회 |
| 필수 플랜 | PRO++(또는 14일 무료 체험) |
연결 방식은 두 가지가 있습니다.
- 키 연결 — 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 중 하나를 선택합니다.
- 키 복사를 선택합니다.
사용자가 새 키를 선택하거나 연결을 삭제하면 기존 키는 작동을 중지합니다. 키가 누락되었거나 유효하지 않거나 교체된 경우 모든 요청은 {"code": "crm_key_invalid"} 메시지와 함께 401을 반환합니다(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 | string | 연결 ID |
| name | string | 앱에 설정된 연결 이름(최대 24자) |
| system | string | 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 값을 저장하세요. 구독을 해제할 때 필요합니다.
- 연결당 구독은 하나만 가능합니다. 새 구독을 등록하면 이전 URL이 대체됩니다.
- URL은 반드시 https://로 시작해야 하며, 길이는 최대 2048자 이하이어야 하고 사용자 이름이나 비밀번호를 포함할 수 없습니다.
- 비공개 또는 로컬 네트워크를 가리키는 URL(해당 네트워크로 확인되는 호스트 이름 포함)은 거부됩니다: localhost, 127.*, 10.*, 172.16–31.*, 192.168.*, 169.254.*.
| 상태 | code | 의미 |
|---|---|---|
| 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시간이 지나도 프로젝트가 전달되지 않으면 재시도를 중단하고 앱에서 해당 연결 상태를 Error로 표시합니다. |
| 410 Gone | 키 연결: 구독을 제거합니다. 다시 구독하려면 Zap을 재활성화하세요. URL 연결: 다른 4xx 응답과 동일하게 처리됩니다. |
| 기타 모든 4xx, 리디렉션 또는 인증서 오류 | 재시도하지 않으며, 앱에서 연결 상태를 Error로 표시합니다. |
모든 전달 데이터는 서명됩니다. 앱은 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 | string | 이번 전송의 고유 ID |
| planNumber | string | 프로젝트 ID |
| planName | string | 프로젝트 이름 |
| revisionUrl | string | 프로젝트 공개 링크 |
| revisionNumber | string | 프로젝트 리비전 |
| 생성됨, 업데이트됨 | string, ISO 8601 | 프로젝트가 생성된 시간 및 마지막으로 저장된 시간 |
| rooms[] | array | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | array | itemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (상품에 대한 사용자 메모, 없으면 null), area (재료용 m²), components[] (상품의 부품: 동일한 필드를 공유하며 quantity는 상품 전체 단위에 대한 수량, quantityPerItem은 단위당 수량; 샘플에서는 quantityPerItem 생략) |
| price_source | string | company (회사 카탈로그의 가격) 또는 estimate (Home Planner 추정 견적) |
| source | string | company (회사 카탈로그의 제품) 또는 homeplanner (Home Planner 카탈로그) |
| totals | object | items: 최상위 품목 수(부품 제외), sum: 부품을 포함한 추정 견적 총액, currency: 통화 코드 |
| pdfUrl | string 또는 null | 평면도 PDF 링크(파일은 7일간 유지됨) |
| productsText | string | 일반 텍스트 형식의 전체 견적서 |
| warning | string 또는 null | 예: "2 item(s) without SKU were sent with a Home Planner code" |
| integration | string | 항상 "custom" |
요청 제한(Rate limits)
| 범위 | 제한 |
|---|---|
| 단일 연결 키당 | 분당 30회 요청, 일당 500회 |
| 유효하지 않은 키를 사용한 요청(IP 주소당) | 분당 300회, 일당 5000회 |
제한을 초과하면 API가 {"code": "crm_throttled"} 메시지와 함께 429를 반환합니다.
오류
모든 오류는 code 필드가 포함된 JSON 형식으로 반환됩니다. (예: {"code": "crm_key_invalid"})
| 상태 | code | 의미 |
|---|---|---|
| 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는 이들 회사와 무관하며, 어떠한 제휴, 보증 또는 후원 관계도 맺고 있지 않습니다.
나만의 프로젝트에서 직접 시도해 보세요
무료 방 계획 및 인테리어 디자인 앱


