Home Planner
חזרה למרכז העזרהמדריכי צעד-אחר-צעד

תיעוד ה-API של Home Planner CRM

Home Planner
Home Plannerצוות האפליקציה · October 28, 2026

נקודות קצה, אימות, מסירת Webhook ורשומת פרויקט ב-API של Home Planner CRM, המשמש את Zapier‏, Make ושרתים פרטיים.

אפליקציית Home Planner שולחת פרויקט עיצוב חדר דרך Zapier אל HubSpot‏, Salesforce‏, Google Sheets ו-Pipedrive

ה-API של Home Planner CRM מחבר בין אפליקציית Home Planner לבין Zapier‏, Make ושרתים פרטיים. ה-API כולל ארבע נקודות קצה, שהגישה אליהן מאומתת באמצעות מפתח חיבור, ו-Webhook אחד שמעביר כל פרויקט שנשלח על ידי המשתמש.

דף זה מיועד למפתחים ולפלטפורמות אינטגרציה. להגדרת שליחת פרויקטים מתוך האפליקציה, מומלץ לעיין במדריך איך לשלוח פרויקטים מ-Home Planner למערכת ה-CRM.

סקירה כללית

פריטערך
כתובת URL בסיסיתhttps://icandesignapp.com (יש להשתמש במארח זה: הפניה מ-homeplannerapp.com עלולה להשמיט את גוף בקשת ה-POST)
פורמטJSON מעל HTTPS
אימותמפתח חיבור בכותרת X-Api-Key
מסירהWebhook‏ (REST hook): בקשת POST אחת לכל פרויקט שנשלח
מנוי נדרשPRO++ (או תקופת ניסיון בחינם ל-14 ימים)

קיימות שתי דרכים להתחברות:

  1. חיבור באמצעות מפתח — עבור Zapier ו-Make. המשתמש בוחר מערכת CRM באפליקציה ומעתיק את המפתח; הפלטפורמה רושמת את ה-Webhook שלה באמצעות POST /crm/key/hooks. דף זה מתאר דרך זו.
  2. חיבור באמצעות כתובת URL — עבור שרת פרטי. המשתמש בוחר באפליקציה באפשרות מערכת אחרת (כתובת ה-URL שלך) ומזין שם את הכתובת. במצב זה אין צורך במפתח או בנקודות קצה, והאפליקציה מציגה את סוד החתימה.
שיטהנקודת קצהמטרה
GET/crm/key/meאימות המפתח והחזרת שם החיבור
POST/crm/key/hooksרישום כתובת URL עבור Webhook
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"
}
שדהסוגתיאור
connectionIdמחרוזתמזהה חיבור
nameמחרוזתשם החיבור כפי שהוגדר באפליקציה, עד 24 תווים
systemמחרוזתhubspot, pipedrive, bitrix24, salesforce או sheets

שגיאות: 401 crm_key_invalid. שגיאות נוספות מפורטות בסעיף "שגיאות" להלן.

POST /crm/key/hooks

מגדירה את כתובת ה-URL של ה-Webhook שמקבלת כל פרויקט שנשלח דרך חיבור זה. 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.*.
סטטוסקודמשמעות
401crm_key_invalidמפתח חסר, לא תקין או מוחלף
422crm_url_invalidהכתובת אינה מתחילה ב-https://, או שהיא ארוכה מ-2048 תווים
422crm_url_credentialsכתובת ה-URL מכילה שם משתמש או סיסמה
422crm_url_forbiddenכתובת ה-URL מפנה לרשת פרטית או מקומית

שגיאות נוספות מפורטות בסעיף "שגיאות" להלן.

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 ללא גוף תגובה. התגובה תהיה 204 גם אם המזהה אינו תואם לרישום הנוכחי, אם המפתח הוחלף, או אם החיבור נמחק. בכל המקרים הללו אין עוד מה להסיר.

שגיאות: 401 crm_key_invalid במקרה של מפתח חסר או מפתח שלא היה תקף מעולם. שגיאות נוספות מפורטות בסעיף "שגיאות" להלן.

GET /crm/key/sample

מחזירה מערך עם רשומת פרויקט לדוגמה אחת, באותו פורמט של מסירה אמיתית. Zapier מציג את השדות של רשומה זו כדי שאפשר יהיה למפות אותם לשדות ב-CRM.

bashbash
curl https://icandesignapp.com/crm/key/sample \
  -H 'X-Api-Key: hp_live_…'

תגובה 200: מערך המכיל רשומת פרויקט אחת (מפורט להלן).

שגיאות: 401 crm_key_invalid. שגיאות נוספות מפורטות בסעיף "שגיאות" להלן.

מסירת Webhook

כאשר בוחרים באפליקציה באפשרות שיתוף ← שליחה אל…, Home Planner שולח את הפרויקט בבקשת POST לכתובת ה-URL שנרשמה.

חלקערך
שיטהPOST
Content-Typeapplication/json
גוף הבקשהרשומת פרויקט אחת
X-HomePlanner-Deliveryמזהה המסירה. מזהה זה נשאר קבוע גם בניסיונות חוזרים: יש להשתמש בו כדי לזהות כפילויות.
X-HomePlanner-Signaturet=<זמן unix בשניות>,v1=<מחרוזת hex באותיות קטנות>, כאשר v1 = HMAC-SHA256(signing secret, t + "." + raw body)
תגובת השרת המקבלכיצד פועל Home Planner
כל קוד 2xx בתוך 15 שניותנמסר בהצלחה
אין תגובה בתוך 15 שניות, קוד 5xx, 408 או 429מבצע ניסיונות חוזרים כעבור דקה, 10 דקות ושעה. אם הפרויקט עדיין לא נמסר בחלוף שעתיים מהניסיון הראשון, הניסיונות ייפסקו והחיבור יסומן באפליקציה בסטטוס שגיאה.
410 Goneבחיבור באמצעות מפתח: מסיר את הרישום; יש להפעיל את ה-Zap מחדש כדי להירשם שוב. בחיבור באמצעות כתובת URL: התנהגות זהה לכל קוד 4xx אחר
כל קוד 4xx אחר, הפניה מחדש או שגיאת אישור אבטחה (Certificate)לא יבוצעו ניסיונות חוזרים; האפליקציה תסמן את החיבור בשגיאה

כל מסירה נחתמת דיגיטלית. האפליקציה מציגה את סוד החתימה רק בחיבור באמצעות כתובת 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_idמחרוזתמזהה ייחודי של שליחה זו
planNumberמחרוזתמזהה הפרויקט
planNameמחרוזתשם הפרויקט
revisionUrlמחרוזתקישור ציבורי לפרויקט
revisionNumberמחרוזתגרסת הפרויקט
created, updatedמחרוזת, ISO 8601זמן יצירת הפרויקט וזמן השמירה האחרונה שלו
rooms[]מערךroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]מערךitemNumber (מק"ט), name, quantity, price, currency, total, price_source, source, imageURL, note (הערת המשתמש על הפריט, או null), area (m², עבור חומרים), components[] (רכיבי הפריט: אותם שדות, כאשר quantity הוא הכמות הכוללת לכל יחידות הפריט, בתוספת quantityPerItem, הכמות ליחידה בודדת; הדוגמה אינה כוללת את quantityPerItem)
price_sourceמחרוזתcompany (מחיר מקטלוג החברה) או estimate (הערכת מחיר של Home Planner)
sourceמחרוזתcompany (מוצר מקטלוג החברה) או homeplanner (קטלוג Home Planner)
totalsאובייקטitems: מספר פריטי השורה ברמה העליונה (ללא רכיבים); sum: סכום ההערכה הכולל, כולל רכיבים; currency: קוד המטבע
pdfUrlמחרוזת או nullקישור לקובץ PDF של תוכנית הדירה; הקובץ זמין למשך 7 ימים
productsTextמחרוזתהערכת המחיר המלאה כטקסט פשוט
warningמחרוזת או nullלדוגמה: "2 item(s) without SKU were sent with a Home Planner code"
integrationמחרוזתתמיד "custom"

מגבלות קצב בקשות

היקףמגבלה
מפתח חיבור יחיד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_forbiddenכתובת ה-URL של ה-Webhook נדחתה
429crm_throttledהגעה למגבלת קצב הבקשות
503crm_unavailableתקלה זמנית בשרת; יש לנסות שוב מאוחר יותר

תמיכה

לשאלות בנושא ה-API: [email protected].

הודעה בנושא סימנים מסחריים. Zapier‏, Make‏, HubSpot‏, Pipedrive‏, Bitrix24‏, Salesforce ו-Google Sheets הם סימנים מסחריים של בעליהם. Home Planner פועלת באופן עצמאי ואינה נתמכת, ממומנת או קשורה לחברות אלו.

Home Planner

לנסות על פרויקט אישי

אפליקציה חינמית לתכנון חדרים ולעיצוב פנים