Home Planner
กลับไปที่ศูนย์ช่วยเหลือคู่มือการใช้งาน

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

Home Planner
Home Plannerทีมงานแอป · October 28, 2026

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

แอป Home Planner ส่งโปรเจกต์การออกแบบห้องผ่าน Zapier ไปยัง HubSpot, Salesforce, Google Sheets และ Pipedrive

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 วิธีดังนี้:

  1. การเชื่อมต่อด้วยคีย์ — สำหรับ Zapier และ Make ผู้ใช้จะเลือกระบบ CRM ภายในแอป แล้วคัดลอกคีย์ จากนั้นแพลตฟอร์มจะลงทะเบียน Webhook ของตนด้วย POST /crm/key/hooks หน้าเว็บนี้จะอธิบายถึงวิธีนี้เป็นหลัก
  2. การเชื่อมต่อด้วย 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 โดยเด็ดขาด

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"
}
ฟิลด์ชนิดข้อมูลคำอธิบาย
connectionIdstringรหัสการเชื่อมต่อ
namestringชื่อการเชื่อมต่อจากแอป ความยาวไม่เกิน 24 ตัวอักษร
systemstringhubspot, pipedrive, bitrix24, salesforce หรือ sheets

ข้อผิดพลาด: 401 crm_key_invalid ส่วนข้อผิดพลาดอื่นๆ โปรดดูที่หัวข้อข้อผิดพลาดด้านล่าง

POST /crm/key/hooks

กำหนด Webhook 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 ที่ชี้ไปยังเครือข่ายส่วนตัวหรือเครือข่ายท้องถิ่น (Local Network) รวมถึงชื่อโฮสต์ที่แปลงค่าไปยังเครือข่ายดังกล่าว ได้แก่ localhost, 127.*, 10.*, 172.16–31.*, 192.168.* และ 169.254.*
สถานะรหัสความหมาย
401crm_key_invalidคีย์สูญหาย ไม่ถูกต้อง หรือถูกทดแทนแล้ว
422crm_url_invalidไม่ใช่ URL แบบ https:// หรือมีความยาวเกิน 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 โดยไม่มีข้อมูลในส่วน body นอกจากนี้ระบบจะส่งค่าตอบกลับเป็น 204 เช่นกัน หากรหัส ID ไม่ตรงกับการสมัครรับข้อมูลปัจจุบัน คีย์ถูกเปลี่ยนใหม่ หรือการเชื่อมต่อถูกลบไปแล้ว เนื่องจากไม่มีข้อมูลใดเหลือให้ลบอีกต่อไป

ข้อผิดพลาด: 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 ส่วนข้อผิดพลาดอื่นๆ โปรดดูที่หัวข้อข้อผิดพลาดด้านล่าง

การส่งข้อมูลผ่าน Webhook

เมื่อผู้ใช้เลือก แชร์ → ส่งไปยัง … ภายในแอป Home Planner จะทำการส่งข้อมูลโปรเจกต์แบบ POST ไปยัง URL ที่ลงทะเบียนไว้

ส่วนประกอบค่า
เมธอดPOST
Content-Typeapplication/json
เนื้อหาชุดข้อมูลโปรเจกต์ 1 รายการ
X-HomePlanner-Deliveryรหัสการส่งข้อมูล รหัสนี้จะไม่เปลี่ยนแปลงแม้จะมีการลองส่งใหม่ ให้ใช้รหัสนี้ในการตรวจจับรายการที่ซ้ำกัน
X-HomePlanner-Signaturet=<เวลา 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

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รหัสเฉพาะของการส่งข้อมูลรายการนี้
planNumberstringรหัสโปรเจกต์
planNamestringชื่อโปรเจกต์
revisionUrlstringลิงก์สาธารณะสำหรับเข้าชมโปรเจกต์
revisionNumberstringเวอร์ชันปรับปรุงของโปรเจกต์
สร้างแล้ว, อัปเดตแล้วstring, ISO 8601เวลาที่สร้างโปรเจกต์และเวลาที่บันทึกครั้งล่าสุด
rooms[]arrayroomNumber, roomName, roomType, area (ตร.ม.), height, width, depth (เมตร), items
rooms[].items[]arrayitemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (บันทึกของผู้ใช้เกี่ยวกับรายการนั้นๆ หรือ null), area (ตร.ม. สำหรับวัสดุ), components[] (ส่วนประกอบของรายการสินค้า: มีฟิลด์เหมือนกัน โดย quantity จะเป็นจำนวนรวมของสินค้าทุกชิ้นรายการนั้น พร้อมฟิลด์ quantityPerItem ซึ่งเป็นจำนวนต่อสินค้า 1 ชิ้น ทั้งนี้ข้อมูลตัวอย่างจะไม่แสดงฟิลด์ 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)

ขอบเขตขีดจำกัด
คีย์การเชื่อมต่อ 1 ชุด30 คำขอต่อนาที, 500 คำขอต่อวัน
คำขอที่ใช้คีย์ไม่ถูกต้อง ต่อหมายเลข IP300 คำขอต่อนาที, 5000 คำขอต่อวัน

เมื่อมีการส่งคำขอเกินขีดจำกัด API จะ คืนค่า 429 พร้อมกับ {"code": "crm_throttled"}

ข้อผิดพลาด

ข้อผิดพลาดทุกรายการจะอยู่ในรูปแบบ JSON ที่มีฟิลด์ code ตัวอย่างเช่น {"code": "crm_key_invalid"}

สถานะรหัสความหมาย
401crm_key_invalidคีย์สูญหาย ไม่ถูกต้อง หรือถูกทดแทนแล้ว
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenWebhook URL ถูกปฏิเสธ
429crm_throttledเกินขีดจำกัดอัตราคำขอแล้ว
503crm_unavailableเซิร์ฟเวอร์ขัดข้องชั่วคราว โปรดลองใหม่อีกครั้งในภายหลัง

ฝ่ายสนับสนุน

หากมีข้อสงสัยเกี่ยวกับ API โปรดติดต่อ: [email protected]

เครื่องหมายการค้า Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce และ Google Sheets เป็นเครื่องหมายการค้าของเจ้าของแต่ละราย ทั้งนี้ Home Planner เป็นอิสระจากบริษัทเหล่านี้และไม่ได้รับการรับรอง ไม่ได้รับการสนับสนุน หรือไม่ได้มีความเกี่ยวข้องใดๆ กับบริษัทดังกล่าว

Home Planner

ทดลองใช้กับโปรเจกต์ของคุณ

แอปวางผังห้องและออกแบบตกแต่งภายในฟรี