เอกสารอ้างอิง Home Planner CRM API

จุดเชื่อมต่อ การยืนยันตัวตน การส่งข้อมูล Webhook และชุดข้อมูลโปรเจกต์ของ Home Planner CRM API สำหรับใช้งานร่วมกับ Zapier, Make และเซิร์ฟเวอร์ของคุณเอง

Home Planner CRM API จะเชื่อมต่อแอป Home Planner เข้ากับ Zapier, Make และเซิร์ฟเวอร์ของคุณเอง โดยมี 4 จุดเชื่อมต่อ (endpoint) ซึ่งทั้งหมดต้องยืนยันตัวตนด้วยคีย์การเชื่อมต่อ และมี Webhook 1 ตัวที่คอยส่งข้อมูลแต่ละโปรเจกต์ที่ผู้ใช้กดส่ง
หน้านี้จัดทำขึ้นสำหรับนักพัฒนาและแพลตฟอร์มการเชื่อมต่อระบบ หากต้องการตั้งค่าการส่งโปรเจกต์ภายในแอป โปรดดูที่ วิธีส่งโปรเจกต์จาก Home Planner ไปยัง CRM ของคุณ
ภาพรวม
| รายการ | ค่า |
|---|---|
| URL พื้นฐาน | https://icandesignapp.com (ให้ใช้โฮสต์นี้ เนื่องจากการเปลี่ยนเส้นทางจาก homeplannerapp.com อาจทำให้ข้อมูล POST body สูญหายได้) |
| รูปแบบ | JSON ผ่าน HTTPS |
| การยืนยันตัวตน | คีย์การเชื่อมต่อในส่วนหัว X-Api-Key |
| การส่งข้อมูล | Webhook (REST hook): ส่ง POST 1 ครั้งต่อ 1 โปรเจกต์ที่ส่ง |
| แพ็กเกจที่ต้องใช้ | PRO++ (หรือสิทธิ์ทดลองใช้ฟรี 14 วัน) |
การเชื่อมต่อสามารถทำได้ 2 วิธีดังนี้:
- การเชื่อมต่อด้วยคีย์ — สำหรับ Zapier และ Make ผู้ใช้จะเลือกระบบ CRM ภายในแอป แล้วคัดลอกคีย์ จากนั้นแพลตฟอร์มจะลงทะเบียน Webhook ของตนด้วย POST /crm/key/hooks หน้าเว็บนี้จะอธิบายถึงวิธีนี้เป็นหลัก
- การเชื่อมต่อด้วย URL — สำหรับเซิร์ฟเวอร์ของคุณเอง ผู้ใช้จะเลือก ระบบอื่น (URL ของคุณ) ภายในแอปแล้วป้อน URL ลงไป วิธีนี้ไม่จำเป็นต้องใช้คีย์หรือจุดเชื่อมต่อใดๆ และแอปจะแสดงรหัสลับสำหรับลงลายมือชื่อ (signing secret) ให้ทราบ
| เมธอด | จุดเชื่อมต่อ (Endpoint) | วัตถุประสงค์ |
|---|---|---|
| GET | /crm/key/me | ตรวจสอบความถูกต้องของคีย์และคืนค่าชื่อการเชื่อมต่อ |
| POST | /crm/key/hooks | ลงทะเบียนสมัครรับข้อมูล Webhook URL |
| DELETE | /crm/key/hooks/{id} | ยกเลิกการสมัครรับข้อมูล Webhook |
| GET | /crm/key/sample | ดึงข้อมูลโปรเจกต์ตัวอย่าง |
การยืนยันตัวตน
ทุกคำขอจะต้องแนบคีย์การเชื่อมต่อมาในส่วนหัว X-Api-Key เสมอ คีย์แต่ละชุดจะผูกกับบัญชีการเชื่อมต่อ CRM เพียงรายการเดียวในบัญชี Home Planner บัญชีเดียวเท่านั้น ห้ามนำคีย์ไปวางไว้ใน 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 | string | รหัสการเชื่อมต่อ |
| name | string | ชื่อการเชื่อมต่อจากแอป ความยาวไม่เกิน 24 ตัวอักษร |
| system | string | hubspot, pipedrive, bitrix24, salesforce หรือ sheets |
ข้อผิดพลาด: 401 crm_key_invalid ส่วนข้อผิดพลาดอื่นๆ โปรดดูที่หัวข้อข้อผิดพลาดด้านล่าง
POST /crm/key/hooks
กำหนด Webhook 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 ที่ชี้ไปยังเครือข่ายส่วนตัวหรือเครือข่ายท้องถิ่น (Local Network) รวมถึงชื่อโฮสต์ที่แปลงค่าไปยังเครือข่ายดังกล่าว ได้แก่ localhost, 127.*, 10.*, 172.16–31.*, 192.168.* และ 169.254.*
| สถานะ | รหัส | ความหมาย |
|---|---|---|
| 401 | crm_key_invalid | คีย์สูญหาย ไม่ถูกต้อง หรือถูกทดแทนแล้ว |
| 422 | crm_url_invalid | ไม่ใช่ URL แบบ https:// หรือมีความยาวเกิน 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 โดยไม่มีข้อมูลในส่วน body นอกจากนี้ระบบจะส่งค่าตอบกลับเป็น 204 เช่นกัน หากรหัส ID ไม่ตรงกับการสมัครรับข้อมูลปัจจุบัน คีย์ถูกเปลี่ยนใหม่ หรือการเชื่อมต่อถูกลบไปแล้ว เนื่องจากไม่มีข้อมูลใดเหลือให้ลบอีกต่อไป
ข้อผิดพลาด: 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 ส่วนข้อผิดพลาดอื่นๆ โปรดดูที่หัวข้อข้อผิดพลาดด้านล่าง
การส่งข้อมูลผ่าน Webhook
เมื่อผู้ใช้เลือก แชร์ → ส่งไปยัง … ภายในแอป Home Planner จะทำการส่งข้อมูลโปรเจกต์แบบ POST ไปยัง URL ที่ลงทะเบียนไว้
| ส่วนประกอบ | ค่า |
|---|---|
| เมธอด | POST |
| Content-Type | application/json |
| เนื้อหา | ชุดข้อมูลโปรเจกต์ 1 รายการ |
| X-HomePlanner-Delivery | รหัสการส่งข้อมูล รหัสนี้จะไม่เปลี่ยนแปลงแม้จะมีการลองส่งใหม่ ให้ใช้รหัสนี้ในการตรวจจับรายการที่ซ้ำกัน |
| X-HomePlanner-Signature | t=<เวลา Unix เป็นวินาที>,v1=<เลขฐานสิบหกตัวพิมพ์เล็ก> โดยที่ v1 = HMAC-SHA256(signing secret, t + "." + raw body) |
| การตอบกลับของคุณ | สิ่งที่ Home Planner จะดำเนินการ |
|---|---|
| รหัสกลุ่ม 2xx ใดๆ ภายใน 15 วินาที | ส่งข้อมูลสำเร็จ |
| ไม่มีการตอบกลับภายใน 15 วินาที, รหัสกลุ่ม 5xx, 408 หรือ 429 | จะลองส่งใหม่อีกครั้งหลังจากผ่านไป 1 นาที, 10 นาที และ 1 ชั่วโมง หากยังส่งโปรเจกต์ไม่สำเร็จหลังจากพยายามครั้งแรกผ่านไปแล้ว 2 ชั่วโมง ระบบจะหยุดลองใหม่และปรับสถานะการเชื่อมต่อในแอปเป็น เกิดข้อผิดพลาด (Error) |
| 410 Gone | การเชื่อมต่อด้วยคีย์: ระบบจะลบการสมัครรับข้อมูลออก ให้เปิดใช้งาน Zap ใหม่อีกครั้งเพื่อลงทะเบียนรับข้อมูลใหม่ ส่วนการเชื่อมต่อด้วย URL: จะมีผลเหมือนกับรหัสกลุ่ม 4xx อื่นๆ |
| รหัสกลุ่ม 4xx อื่นๆ, การเปลี่ยนเส้นทาง หรือข้อผิดพลาดเกี่ยวกับใบรับรอง (certificate) | ไม่มีการลองส่งใหม่ แอปจะปรับสถานะการเชื่อมต่อเป็น เกิดข้อผิดพลาด (Error) |
การส่งข้อมูลทุกครั้งจะมีการลงลายมือชื่อกำกับ โดยแอปจะแสดงรหัสลับสำหรับลงลายมือชื่อ (signing secret) เฉพาะการเชื่อมต่อด้วย 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 | รหัสเฉพาะของการส่งข้อมูลรายการนี้ |
| planNumber | string | รหัสโปรเจกต์ |
| planName | string | ชื่อโปรเจกต์ |
| revisionUrl | string | ลิงก์สาธารณะสำหรับเข้าชมโปรเจกต์ |
| revisionNumber | string | เวอร์ชันปรับปรุงของโปรเจกต์ |
| สร้างแล้ว, อัปเดตแล้ว | string, ISO 8601 | เวลาที่สร้างโปรเจกต์และเวลาที่บันทึกครั้งล่าสุด |
| rooms[] | array | roomNumber, roomName, roomType, area (ตร.ม.), height, width, depth (เมตร), items |
| rooms[].items[] | array | itemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (บันทึกของผู้ใช้เกี่ยวกับรายการนั้นๆ หรือ null), area (ตร.ม. สำหรับวัสดุ), components[] (ส่วนประกอบของรายการสินค้า: มีฟิลด์เหมือนกัน โดย quantity จะเป็นจำนวนรวมของสินค้าทุกชิ้นรายการนั้น พร้อมฟิลด์ quantityPerItem ซึ่งเป็นจำนวนต่อสินค้า 1 ชิ้น ทั้งนี้ข้อมูลตัวอย่างจะไม่แสดงฟิลด์ 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)
| ขอบเขต | ขีดจำกัด |
|---|---|
| คีย์การเชื่อมต่อ 1 ชุด | 30 คำขอต่อนาที, 500 คำขอต่อวัน |
| คำขอที่ใช้คีย์ไม่ถูกต้อง ต่อหมายเลข IP | 300 คำขอต่อนาที, 5000 คำขอต่อวัน |
เมื่อมีการส่งคำขอเกินขีดจำกัด API จะ คืนค่า 429 พร้อมกับ {"code": "crm_throttled"}
ข้อผิดพลาด
ข้อผิดพลาดทุกรายการจะอยู่ในรูปแบบ JSON ที่มีฟิลด์ code ตัวอย่างเช่น {"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 เป็นอิสระจากบริษัทเหล่านี้และไม่ได้รับการรับรอง ไม่ได้รับการสนับสนุน หรือไม่ได้มีความเกี่ยวข้องใดๆ กับบริษัทดังกล่าว
ทดลองใช้กับโปรเจกต์ของคุณ
แอปวางผังห้องและออกแบบตกแต่งภายในฟรี


