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

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

ה-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 ימים) |
קיימות שתי דרכים להתחברות:
- חיבור באמצעות מפתח — עבור Zapier ו-Make. המשתמש בוחר מערכת CRM באפליקציה ומעתיק את המפתח; הפלטפורמה רושמת את ה-Webhook שלה באמצעות POST /crm/key/hooks. דף זה מתאר דרך זו.
- חיבור באמצעות כתובת 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.
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 | מחרוזת | מזהה חיבור |
| name | מחרוזת | שם החיבור כפי שהוגדר באפליקציה, עד 24 תווים |
| system | מחרוזת | hubspot, pipedrive, bitrix24, salesforce או sheets |
שגיאות: 401 crm_key_invalid. שגיאות נוספות מפורטות בסעיף "שגיאות" להלן.
POST /crm/key/hooks
מגדירה את כתובת ה-URL של ה-Webhook שמקבלת כל פרויקט שנשלח דרך חיבור זה. 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.*.
| סטטוס | קוד | משמעות |
|---|---|---|
| 401 | crm_key_invalid | מפתח חסר, לא תקין או מוחלף |
| 422 | crm_url_invalid | הכתובת אינה מתחילה ב-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 ללא גוף תגובה. התגובה תהיה 204 גם אם המזהה אינו תואם לרישום הנוכחי, אם המפתח הוחלף, או אם החיבור נמחק. בכל המקרים הללו אין עוד מה להסיר.
שגיאות: 401 crm_key_invalid במקרה של מפתח חסר או מפתח שלא היה תקף מעולם. שגיאות נוספות מפורטות בסעיף "שגיאות" להלן.
GET /crm/key/sample
מחזירה מערך עם רשומת פרויקט לדוגמה אחת, באותו פורמט של מסירה אמיתית. Zapier מציג את השדות של רשומה זו כדי שאפשר יהיה למפות אותם לשדות ב-CRM.
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-Type | application/json |
| גוף הבקשה | רשומת פרויקט אחת |
| X-HomePlanner-Delivery | מזהה המסירה. מזהה זה נשאר קבוע גם בניסיונות חוזרים: יש להשתמש בו כדי לזהות כפילויות. |
| X-HomePlanner-Signature | t=<זמן 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.
{
"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 ליום |
| בקשות עם מפתח לא תקין, לכל כתובת 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 | כתובת ה-URL של ה-Webhook נדחתה |
| 429 | crm_throttled | הגעה למגבלת קצב הבקשות |
| 503 | crm_unavailable | תקלה זמנית בשרת; יש לנסות שוב מאוחר יותר |
תמיכה
לשאלות בנושא ה-API: [email protected].
הודעה בנושא סימנים מסחריים. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce ו-Google Sheets הם סימנים מסחריים של בעליהם. Home Planner פועלת באופן עצמאי ואינה נתמכת, ממומנת או קשורה לחברות אלו.
לנסות על פרויקט אישי
אפליקציה חינמית לתכנון חדרים ולעיצוב פנים


