مرجع Home Planner CRM API

نقاط النهاية والمصادقة وتسليم webhook وسجل المشروع لـ Home Planner CRM API المستخدمة بواسطة Zapier وMake وخادمك الخاص.

يربط واجهة برمجة تطبيقات Home Planner CRM تطبيق Home Planner بـ Zapier وMake وخادمك الخاص. وهي تتضمن أربع نقاط نهاية، تُصادق جميعها باستخدام مفتاح اتصال، بالإضافة إلى عنصر webhook واحد يرسل كل مشروع يشاركه المستخدم.
تستهدف هذه الصفحة المطورين ومنصات التكامل. لإعداد إرسال المشاريع داخل التطبيق، يرجى الاطلاع على كيفية إرسال المشاريع من Home Planner إلى نظام إدارة علاقات العملاء (CRM).
نظرة عامة
| العنصر | القيمة |
|---|---|
| الرابط الأساسي | 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 — لخادمك الخاص. يختار المستخدم نظام آخر (رابطك الخاص) في التطبيق ويدخل الرابط هناك. لا يلزم استخدام مفتاح أو نقاط نهاية، ويظهر التطبيق سر التوقيع.
| الطريقة | نقطة النهاية | الغرض |
|---|---|---|
| GET | /crm/key/me | التحقق من صحة المفتاح وإعادة اسم الاتصال |
| POST | /crm/key/hooks | الاشتراك في رابط 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"
}| الحقل | النوع | الوصف |
|---|---|---|
| معرّف الاتصال | سلسلة نصية | معرّف الاتصال |
| الاسم | سلسلة نصية | اسم الاتصال من التطبيق، حتى 24 حرفًا |
| النظام | سلسلة نصية | hubspot أو pipedrive أو bitrix24 أو salesforce أو sheets |
الأخطاء: 401 crm_key_invalid. لمعرفة الأخطاء الأخرى: انظر قسم الأخطاء أدناه.
POST /crm/key/hooks
يحدد رابط 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 | يحتوي الرابط على اسم مستخدم أو كلمة سر |
| 422 | crm_url_forbidden | يشير الرابط إلى شبكة خاصة أو محلية |
الأخطاء الأخرى: انظر قسم الأخطاء أدناه.
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 |
| نوع المحتوى | application/json |
| نص الطلب | سجل مشروع واحد |
| X-HomePlanner-Delivery | معرّف التسليم. يبقى ثابتًا عبر محاولات الإعادة: يُستخدم لاكتشاف التكرارات. |
| X-HomePlanner-Signature | t=<الوقت بالتوقيت العالمي بالثواني>، v1=<نص ست عشري بحروف صغيرة>، حيث v1 = HMAC-SHA256(سر التوقيع، t + "." + نص الطلب الخام) |
| استجابتك | ما يفعله Home Planner |
|---|---|
| أي استجابة 2xx خلال 15 ثانية | تم التسليم |
| عدم وجود استجابة خلال 15 ثانية، أو 5xx، أو 408، أو 429 | إعادة المحاولة بعد دقيقة واحدة، و10 دقائق، وساعة واحدة. إذا لم يتم تسليم المشروع بعد مرور ساعتين من المحاولة الأولى، تتوقف المحاولات وتتم تعليم حالة الاتصال بـ "خطأ" في التطبيق. |
| 410 غير متاح | الاتصال بواسطة مفتاح: يزيل الاشتراك؛ يلزم تشغيل مهمة Zap مجددًا لإعادة الاشتراك. الاتصال بواسطة رابط URL: يعامل كأي رمز 4xx آخر |
| أي رمز 4xx آخر، أو إعادة توجيه، أو خطأ في شهادة الأمان | لا تتم إعادة المحاولة؛ ويعلم التطبيق حالة الاتصال بـ "خطأ" |
يتم توقيع كل عملية تسليم. يعرض التطبيق سر التوقيع فقط عند استخدام الاتصال بواسطة رابط URL. لمعرفة خطوات التحقق من التوقيع، يرجى الاطلاع على كيفية إرسال المشاريع من Home Planner إلى نظام إدارة علاقات العملاء (CRM).
عند انتهاء اشتراك PRO++ الخاص بالمستخدم أو فترة التجربة المجانية، يتوقف التطبيق عن إرسال المشاريع. تستمر نقاط النهاية في الاستجابة، فتظل مهمة Zap نشطة ولكنها لا تتلقى مشاريع جديدة حتى يجدد المستخدم اشتراكه.
سجل المشروع
يستخدم كل تسليم ونقطة نهاية العينة هذا التنسيق. تطابق الأسعار والإجماليات مقايسة المشروع في التطبيق. في Zapier، يحتوي السجل أيضًا على حقل id: نسخة من client_reference_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"
}| الحقل | النوع | الوصف |
|---|---|---|
| معرّف مرجع العميل | سلسلة نصية | المعرّف الفريد لعملية الإرسال هذه |
| رقم المخطط | سلسلة نصية | معرّف المشروع |
| اسم المخطط | سلسلة نصية | اسم المشروع |
| رابط المراجعة | سلسلة نصية | الرابط العام للمشروع |
| رقم المراجعة | سلسلة نصية | مراجعة المشروع |
| created، updated | سلسلة نصية، ISO 8601 | تاريخ إنشاء المشروع وتاريخ آخر حفظ له |
| rooms[] | مصفوفة | roomNumber، roomName، roomType، area (م²)، height، width، depth (م)، items |
| rooms[].items[] | مصفوفة | itemNumber (رمز وحدة التخزين التعريفي SKU)، name، quantity، price، currency، total، price_source، source، imageURL، note (ملاحظة المستخدم على العنصر، أو null)، area (م²، للمواد)، components[] (أجزاء العنصر: الحقول نفسها، حيث تمثل quantity العدد الكلي لجميع وحدات العنصر، بالإضافة إلى quantityPerItem، وهو العدد لكل وحدة؛ وتغفل العينة الحقل quantityPerItem) |
| مصدر السعر | سلسلة نصية | company (السعر من كتالوج الشركة) أو estimate (مقايسة Home Planner) |
| المصدر | سلسلة نصية | company (منتج من كتالوج الشركة) أو homeplanner (كتالوج Home Planner) |
| الإجماليات | كائن | items: عدد عناصر البنود الرئيسية (دون احتساب المكونات)؛ sum: إجمالي المقايسة، شاملاً المكونات؛ currency: رمز العملة |
| رابط PDF | سلسلة نصية أو null | رابط ملف PDF لمخطط الطابق؛ يظل الملف متاحًا لمدة 7 أيام |
| نص المنتجات | سلسلة نصية | المقايسة الكاملة كنص عادي |
| تحذير | سلسلة نصية أو null | على سبيل المثال: "تم إرسال عنصر (عناصر) بدون SKU باستخدام رمز Home Planner" |
| التكامل | سلسلة نصية | دائمًا "custom" |
حدود معدل الاستخدام
| النطاق | الحد |
|---|---|
| مفتاح اتصال واحد | 30 طلبًا في الدقيقة، 500 طلب في اليوم |
| الطلبات بمفتاح غير صالح، لكل عنوان IP | 300 طلب في الدقيقة، 5000 طلب في اليوم |
عند تجاوز الحد، تعيد واجهة برمجة التطبيقات الرمز 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 | مشكلة مؤقتة في الخادم؛ يُرجى إعادة المحاولة لاحقًا |
الدعم
للأسئلة المتعلقة بواجهة برمجة التطبيقات: [email protected].
إشعار العلامات التجارية. إن Zapier وMake وHubSpot وPipedrive وBitrix24 وSalesforce وGoogle Sheets هي علامات تجارية لمالكيها. تُعد Home Planner جهة مستقلة عن هذه الشركات ولا تخضع لرعايتها أو تأييدها أو التبعية لها.
تجربته في مشروعك الخاص
تطبيق مجاني للتخطيط المكتبي وتصميم الديكور الداخلي


