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 تطبيق 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 يومًا)

توجد طريقتان للاتصال:

  1. الاتصال بواسطة مفتاح — لمنصتي Zapier وMake. يختار المستخدم نظام CRM في التطبيق وينسخ المفتاح؛ وتُشترك المنصة في عنصر webhook الخاص بها عبر POST /crm/key/hooks. تصف هذه الصفحة هذه الطريقة.
  2. الاتصال بواسطة رابط 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.

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"
}
الحقلالنوعالوصف
معرّف الاتصالسلسلة نصيةمعرّف الاتصال
الاسمسلسلة نصيةاسم الاتصال من التطبيق، حتى 24 حرفًا
النظامسلسلة نصيةhubspot أو pipedrive أو bitrix24 أو salesforce أو sheets

الأخطاء: 401 crm_key_invalid. لمعرفة الأخطاء الأخرى: انظر قسم الأخطاء أدناه.

POST /crm/key/hooks

يحدد رابط 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يحتوي الرابط على اسم مستخدم أو كلمة سر
422crm_url_forbiddenيشير الرابط إلى شبكة خاصة أو محلية

الأخطاء الأخرى: انظر قسم الأخطاء أدناه.

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
نوع المحتوىapplication/json
نص الطلبسجل مشروع واحد
X-HomePlanner-Deliveryمعرّف التسليم. يبقى ثابتًا عبر محاولات الإعادة: يُستخدم لاكتشاف التكرارات.
X-HomePlanner-Signaturet=<الوقت بالتوقيت العالمي بالثواني>، 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، وتظهر باسم معرّف الإرسال.

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"
}
الحقلالنوعالوصف
معرّف مرجع العميلسلسلة نصيةالمعرّف الفريد لعملية الإرسال هذه
رقم المخططسلسلة نصيةمعرّف المشروع
اسم المخططسلسلة نصيةاسم المشروع
رابط المراجعةسلسلة نصيةالرابط العام للمشروع
رقم المراجعةسلسلة نصيةمراجعة المشروع
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 طلب في اليوم
الطلبات بمفتاح غير صالح، لكل عنوان IP300 طلب في الدقيقة، 5000 طلب في اليوم

عند تجاوز الحد، تعيد واجهة برمجة التطبيقات الرمز 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مشكلة مؤقتة في الخادم؛ يُرجى إعادة المحاولة لاحقًا

الدعم

للأسئلة المتعلقة بواجهة برمجة التطبيقات: [email protected].

إشعار العلامات التجارية. إن Zapier وMake وHubSpot وPipedrive وBitrix24 وSalesforce وGoogle Sheets هي علامات تجارية لمالكيها. تُعد Home Planner جهة مستقلة عن هذه الشركات ولا تخضع لرعايتها أو تأييدها أو التبعية لها.

Home Planner

تجربته في مشروعك الخاص

تطبيق مجاني للتخطيط المكتبي وتصميم الديكور الداخلي

العلاماتCRMAPIZapierWebhookPRO++