GoHighLevel API وWebhooks: عمليات التكامل المخصصة

تغطي عمليات التكامل الأصلية وموصلات Zapier الخاصة بـ GoHighLevel معظم حالات الاستخدام القياسية، ولكن الشركات التي لديها مسارات عمل محددة أو أنظمة خاصة أو كميات كبيرة من البيانات تحتاج في النهاية إلى العمل مباشرة مع واجهة برمجة تطبيقات GHL. تمنح واجهة برمجة تطبيقات GHL REST ونظام webhook للمطورين وصولاً برمجيًا كاملاً إلى جهات الاتصال وخطوط الأنابيب والحملات والمواعيد والمزيد - مما يتيح عمليات التكامل التي لا تستطيع الأدوات التي لا تحتاج إلى تعليمات برمجية تكرارها.

تم إعداد هذا الدليل للفرق الفنية التي تعمل على إنشاء عمليات تكامل مخصصة مع GoHighLevel. ويغطي بنية واجهة برمجة التطبيقات (API)، والمصادقة، ونقاط النهاية الرئيسية، وإعداد خطاف الويب والأمان، وأنماط التكامل العملية لحالات الاستخدام الشائعة.

الوجبات الرئيسية

• تستخدم واجهة REST API (الإصدار 2) الخاصة بـ GHL OAuth 2.0 للمصادقة وتدعم جميع كائنات CRM الرئيسية
• تسمح خطافات الويب الواردة في سير عمل GHL للأنظمة الخارجية بتشغيل عمليات أتمتة GHL في الوقت الفعلي
• تقوم خطافات الويب الصادرة من GHL بإعلام الأنظمة الخارجية عند حدوث أحداث GHL (إنشاء جهة اتصال، وتحديث خط الأنابيب، وما إلى ذلك)
• حدود المعدل هي 100 طلب/10 ثوانٍ لكل موقع - تعتبر العمليات المجمعة والتخزين المؤقت مهمة على نطاق واسع
• يتيح لك GHL Marketplace نشر عمليات التكامل كتطبيقات GHL الأصلية لتثبيتها بواسطة العميل
• القيم المخصصة والحقول المخصصة هي نقاط امتداد البيانات الأساسية لتخزين حالة التكامل
• التحقق من حمولة Webhook باستخدام رأس توقيع GHL يمنع الطلبات المخادعة
• تتبع معظم عمليات تكامل GHL أربعة أنماط: مزامنة جهات الاتصال، أو التشغيل الآلي للأحداث، أو سد خطوط الأنابيب، أو تجميع التقارير

---

نظرة عامة على بنية GHL API

واجهة برمجة تطبيقات GoHighLevel (الإصدار 2 اعتبارًا من عام 2026) هي واجهة برمجة تطبيقات REST قياسية مع أجسام طلب واستجابة JSON. عنوان URL الأساسي هو:

https://services.leadconnectorhq.com

تنظم واجهة برمجة التطبيقات (API) الموارد في مساحات الأسماء الأساسية هذه:

وثائق API الكاملة متاحة على https://highlevel.stoplight.io/docs/integrations/.

---

المصادقة: إعداد OAuth 2.0

تستخدم واجهة برمجة تطبيقات GHL OAuth 2.0 لجميع عمليات المصادقة. هناك سياقان للمصادقة:

1. مفتاح واجهة برمجة التطبيقات على مستوى الوكالة (لإدارة الحساب الفرعي)

بالنسبة لعمليات التكامل من خادم إلى خادم التي تدير حسابات فرعية متعددة، استخدم مفتاح واجهة برمجة تطبيقات الوكالة:

• تم إنشاؤها في إعدادات الوكالة > مفاتيح واجهة برمجة التطبيقات
• نطاق العمليات على مستوى الوكالة (إنشاء/إدارة الحسابات الفرعية)

2. OAuth للحساب الفرعي (لعمليات التكامل لكل موقع)

بالنسبة لعمليات التكامل التي تعمل ضمن حساب فرعي واحد (الحالة الأكثر شيوعًا):

Authorization Flow:
1. Register your app in GHL Marketplace (or use a private integration key)
2. Redirect user to GHL OAuth consent page:
   https://marketplace.gohighlevel.com/oauth/chooselocation?response_type=code
     &redirect_uri=YOUR_CALLBACK_URL
     &client_id=YOUR_CLIENT_ID
     &scope=contacts.readonly+contacts.write+opportunities.write+...
3. User approves → GHL redirects to your callback with ?code=AUTH_CODE
4. Exchange auth code for access + refresh tokens:
   POST https://services.leadconnectorhq.com/oauth/token
   Body: {
     client_id, client_secret, grant_type: "authorization_code",
     code: AUTH_CODE, redirect_uri: YOUR_CALLBACK_URL
   }
5. Use access token in Authorization header: Bearer ACCESS_TOKEN
6. Refresh access token when expired (typically every 24 hours) using refresh token

النطاقات المطلوبة للعمليات المشتركة:

اطلب النطاقات التي تحتاجها فقط — الحد الأدنى من النطاق هو أفضل ممارسات الأمان.

---

عمليات واجهة برمجة التطبيقات الأساسية: جهات الاتصال

تعد واجهة برمجة تطبيقات جهات الاتصال هي نقطة النهاية الأكثر استخدامًا في عمليات تكامل GHL.

إنشاء أو تحديث جهة اتصال:

POST https://services.leadconnectorhq.com/contacts/
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+14155551234",
  "locationId": "YOUR_LOCATION_ID",
  "source": "shopify-integration",
  "tags": ["new-customer", "shopify"],
  "customFields": [
    {
      "id": "CUSTOM_FIELD_ID_FOR_ORDER_COUNT",
      "field_value": "1"
    }
  ]
}

الرد (201 تم الإنشاء):

{
  "contact": {
    "id": "abc123xyz",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+14155551234",
    "locationId": "YOUR_LOCATION_ID",
    "tags": ["new-customer", "shopify"],
    "createdAt": "2026-03-19T10:30:00.000Z"
  }
}

البحث عن جهة اتصال عبر البريد الإلكتروني (لإلغاء البيانات المكررة):

GET https://services.leadconnectorhq.com/contacts/search
  ?locationId=YOUR_LOCATION_ID
  &[email protected]
Authorization: Bearer ACCESS_TOKEN

ابحث دائمًا قبل الإنشاء لتجنب سجلات الاتصال المكررة.

إضافة علامة إلى جهة اتصال:

POST https://services.leadconnectorhq.com/contacts/abc123xyz/tags
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "tags": ["vip-customer", "order-placed"]
}

العمليات المجمعة:

يدعم GHL إنشاء جهات الاتصال المجمعة عبر نقطة النهاية POST /contacts/bulk (تحقق من ذلك في مستندات API الحالية لإصدار GHL الخاص بك). بالنسبة لعمليات استيراد أكثر من 500 جهة اتصال، استخدم نقطة النهاية المجمعة مع دفعات مكونة من 100 جهة اتصال لكل طلب للبقاء ضمن حدود المعدل.

---

API لخط الأنابيب والفرصة

اصنع الفرصة:

POST https://services.leadconnectorhq.com/opportunities/
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "pipelineId": "YOUR_PIPELINE_ID",
  "pipelineStageId": "YOUR_STAGE_ID",
  "contactId": "abc123xyz",
  "name": "Jane Smith - HVAC Service",
  "monetaryValue": 450,
  "status": "open",
  "assignedTo": "USER_ID"
}

نقل الفرصة إلى مرحلة جديدة:

PUT https://services.leadconnectorhq.com/opportunities/OPPORTUNITY_ID
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "pipelineStageId": "NEW_STAGE_ID"
}

نمط التكامل المشترك: إدارة علاقات العملاء الخارجية → GHL Pipeline Sync

عند إنشاء صفقة في نظام خارجي (على سبيل المثال، Salesforce)، رمز التكامل الخاص بك:

1. يبحث في GHL عن جهة الاتصال عبر البريد الإلكتروني
2. يقوم بإنشاء جهة الاتصال إذا لم يتم العثور عليها
3. إنشاء فرصة GHL مرتبطة بجهة الاتصال
4. يقوم بتخزين معرف فرصة GHL كحقل مخصص في Salesforce للمزامنة ثنائية الاتجاه

---

خطافات الويب الواردة: تشغيل GHL من الأنظمة الخارجية

تسمح خطافات الويب الواردة للأنظمة الخارجية بإطلاق مهام سير عمل GHL. هذه هي الآلية الأساسية للتكامل القائم على الأحداث.

إنشاء مشغل Webhook وارد في GHL:

1. انتقل إلى الأتمتة > سير العمل > سير العمل الجديد
2. حدد "Inbound Webhook" كنوع المشغل
3. تقوم GHL بإنشاء عنوان URL فريد: الكود0
4. قم بتكوين البيانات التي يستخدمها سير العمل من حمولة خطاف الويب

إرسال البيانات إلى خطاف الويب الوارد:

POST https://services.leadconnectorhq.com/hooks/YOUR_UNIQUE_HOOK_ID/webhook-trigger
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+14155559876",
  "customData": {
    "order_id": "ORD-12345",
    "product_name": "AC Tune-Up Service",
    "order_value": "299.00"
  }
}

يقوم GHL بإنشاء جهة اتصال أو تحديثها من حقول الحمولة التي يتعرف عليها (الاسم الأول واسم العائلة والبريد الإلكتروني والهاتف) ويجعل حقول customData متاحة كمتغيرات في سير العمل.

حالات الاستخدام لخطافات الويب الواردة:

• تم تقديم طلب التجارة الإلكترونية → تشغيل تسلسل ما بعد الشراء
• تم إنشاء تذكرة الدعم → قم بإضافة علامة "الدعم النشط"، وإيقاف تسلسلات التسويق مؤقتًا
• تم استلام الدفعة → انقل خط الأنابيب إلى "الفوز"، وقم بتشغيل سير العمل على متن الطائرة
• الاشتراك التجريبي → بدء تسلسل تأهيل SaaS
• تم تقديم النموذج على موقع الطرف الثالث → قم بالتقاط العميل المحتمل في GHL CRM

---

خطافات الويب الصادرة: إخطار الأنظمة الخارجية بواسطة GHL

تقوم خطافات الويب الصادرة بإرسال البيانات من GHL إلى الأنظمة الخارجية عند حدوث أحداث GHL.

تكوين خطافات الويب الصادرة في GHL:

انتقل إلى الإعدادات > عمليات التكامل > Webhooks (مستوى الحساب الفرعي) أو قم بإضافة إجراء webhook داخل سير العمل.

أحداث GHL الأصلية الصادرة (متوفرة في الإعدادات > Webhooks):

• تم إنشاء جهة الاتصال
• تم تحديث الاتصال
• تم حذف جهة الاتصال
• الفرصة التي تم إنشاؤها / تحديثها / حذفها
• النموذج المقدم
• تم حجز الموعد / إلغاؤه / عدم الحضور
• رسالة المحادثة (الواردة)
• بدأت / انتهت المكالمة

إجراء Webhook لسير عمل GHL:

لمزيد من التحكم الدقيق، قم بإضافة إجراء "إرسال Webhook" داخل سير العمل. يتم تفعيل هذا فقط عندما يصل سير العمل إلى تلك الخطوة، مما يسمح لك بالتحكم الدقيق في الأحداث التي تُخطر الأنظمة الخارجية والحمولة التي تتلقاها.

// Example workflow webhook payload to your system
{
  "event": "appointment_booked",
  "contact": {
    "id": "{{contact.id}}",
    "name": "{{contact.full_name}}",
    "email": "{{contact.email}}",
    "phone": "{{contact.phone}}"
  },
  "appointment": {
    "calendar_id": "{{appointment.calendar_id}}",
    "start_time": "{{appointment.start_time}}",
    "service": "{{appointment.title}}"
  },
  "custom_fields": {
    "order_id": "{{contact.order_id}}"
  }
}

استخدم بناء جملة القيمة المخصصة لـ GHL ({{variable.path}}) لتضمين بيانات الاتصال والأحداث الديناميكية في الحمولة.

---

أمان Webhook: التحقق من التوقيع

تقوم GHL بتوقيع خطافات الويب الصادرة بتوقيع HMAC-SHA256. يجب أن تتحقق نقطة النهاية المتلقية من هذا التوقيع لمنع الطلبات المخادعة.

عملية التحقق:

يتضمن GHL رأس توقيع مع كل طلب خطاف ويب:

X-GHL-Signature: sha256=COMPUTED_HMAC

يتحقق الخادم الخاص بك من:

const crypto = require('crypto');

function verifyGHLWebhook(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload) // raw request body as Buffer
    .digest('hex');

  const expectedSignature = `sha256=${computedSignature}`;

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signature)
  );
}

استخدم دائمًا crypto.timingSafeEqual للمقارنة، فمساواة السلسلة عرضة لهجمات التوقيت.

يتم تعيين سر خطاف الويب الخاص بك عندما تقوم بإنشاء خطاف الويب في إعدادات GHL.

---

تحديد المعدل وأفضل الممارسات

تفرض GHL حدودًا للمعدلات على الوصول إلى واجهة برمجة التطبيقات (API). اعتبارًا من عام 2026، يبلغ الحد القياسي حوالي 100 طلب لكل 10 ثوانٍ لكل موقع. يؤدي تجاوز هذا إلى إرجاع استجابة 429 Too Many Requests.

استراتيجيات البقاء ضمن حدود الأسعار:

1. تنفيذ التراجع الأسي:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(r => setTimeout(r, delay));
      } else {
        throw error;
      }
    }
  }
}

2. عمليات البحث عن جهات الاتصال في ذاكرة التخزين المؤقت: لا تبحث عن GHL عبر البريد الإلكتروني في كل حدث وارد. قم بتخزين عمليات البحث عن معرف جهة الاتصال مؤقتًا في Redis أو قاعدة البيانات الخاصة بك باستخدام TTL لمدة 15 دقيقة. تتضمن معظم تدفقات التكامل نفس جهات الاتصال بشكل متكرر.

3. تحديثات جهات الاتصال المجمعة: إذا كنت تقوم بتحديث الحقول المخصصة لـ 500 جهة اتصال بعد معالجة بيانات مجمعة، فقم بتجميع التحديثات في مجموعات مكونة من 10 مع تأخير قدره 100 مللي ثانية بين الدُفعات بدلاً من إطلاق جميع الـ 500 في وقت واحد.

4. استخدم خطافات الويب بدلاً من الاقتراع: لا تقم مطلقًا باستطلاع واجهة برمجة تطبيقات GHL لمعرفة التغييرات (على سبيل المثال، التحقق كل دقيقة من إنشاء جهات اتصال جديدة). استخدم خطافات الويب الصادرة من GHL لتلقي الإشعارات عند وقوع الأحداث. وهذا يلغي استهلاك الحد الأقصى للمعدل المتعلق بالاقتراع.

---

إنشاء تطبيق GHL Marketplace

إذا كنت تقوم بإنشاء تكامل للعديد من عملاء GHL، ففكر في نشره كتطبيق GHL Marketplace. يتيح ذلك لمستخدمي GHL تثبيت التكامل الخاص بك بنقرة واحدة، باستخدام OAuth للمصادقة - لا يلزم مشاركة مفتاح واجهة برمجة التطبيقات يدويًا.

متطلبات الإدراج في السوق:

• تنفيذ OAuth 2.0
• سياسة الخصوصية وعناوين URL لشروط الخدمة
• أيقونة التطبيق ووصفه
• التعامل مع Webhook للأحداث التي يشترك فيها تطبيقك
• عملية مراجعة GHL والموافقة عليها (عادةً من أسبوع إلى أسبوعين)

فوائد توزيع السوق:

• التثبيت بنقرة واحدة لمستخدمي GHL
• يعالج OAuth المصادقة (لا توجد إدارة مفاتيح API)
• زيادة قابلية الاكتشاف من خلال سوق GHL
• القدرة على فرض رسوم على التكامل عبر البنية التحتية لفواتير GHL

يستحق هذا المسار المتابعة إذا كنت تقوم ببناء تكامل قد تستخدمه العديد من وكالات أو شركات GHL - فتأثير التوزيع كبير.

---

أنماط التكامل الشائعة

النمط 1: مزامنة طلبات التجارة الإلكترونية

• خطاف الويب للطلب من Shopify → برنامجك الوسيط → تحديث جهة اتصال GHL + العلامة + تسجيل سير العمل
• تقوم البرامج الوسيطة بالتحقق من صحة الحمولة، وإلغاء تكرار جهات الاتصال، وتعيين بيانات الطلب إلى حقول GHL المخصصة

النمط 2: ERP إلى CRM Bridge

• تم إنشاء فاتورة ERP (Odoo وQuickBooks) ← خطاف الويب إلى البرامج الوسيطة ← تم وضع علامة على فرصة GHL بالفوز + نقل خط الأنابيب
• المزامنة ثنائية الاتجاه: تغيير خط أنابيب GHL → تحديث حالة طلب ERP

النمط 3: موعد + مزامنة الخدمة الميدانية

• تم حجز موعد GHL ← خطاف الويب الصادر ← أداة FSM تنشئ الوظيفة
• اكتملت مهمة FSM ← خطاف الويب إلى GHL ← انقل خط الأنابيب إلى تسلسل المراجعة المكتمل + المشغل

النمط 4: إعداد تقارير عن مستودع البيانات

• يوميًا: تقوم GHL API بسحب جهات الاتصال والفرص وأحداث الاتصال الخاصة باليوم السابق
• البيانات المخزنة في مستودع البيانات الخاص بك (BigQuery، Snowflake)
• يتصل Power BI أو Looker بمستودع البيانات لإجراء تحليلات متقدمة عبر الأنظمة الأساسية

---

الأسئلة المتداولة

ما الفرق بين الإصدارين v1 وv2 API من GHL؟

تستخدم واجهة برمجة التطبيقات v2 API الخاصة بـ GHL (التي تم تقديمها في الفترة ما بين 2022-2023) OAuth 2.0 وتصميم REST أكثر نظافة مقارنةً بمصادقة مفتاح API الخاصة بالإصدار 1. تتمتع واجهة برمجة التطبيقات v2 بتغطية أكثر شمولاً لنقطة النهاية ووثائق أفضل. يجب أن يتم بناء عمليات التكامل الجديدة على الإصدار 2. أعلنت شركة GHL عن نيتها لإيقاف الإصدار 1 ولكنها لم تضع جدولًا زمنيًا ثابتًا بعد — تحقق من إعلانات مطوري GHL لمعرفة الوضع الحالي.

هل يمكنني استخدام واجهة برمجة تطبيقات GHL لإرسال رسائل SMS برمجيًا؟

نعم. استخدم نقطة النهاية POST /conversations/messages لإرسال رسائل SMS إلى جهة اتصال. أنت بحاجة إلى معرف المحادثة (الذي تم إنشاؤه بواسطة POST /conversations/) ورقم هاتف جهة الاتصال. تأكد من أن جهة الاتصال تتمتع بحالة الاشتراك في الرسائل القصيرة SMS قبل الإرسال — يفرض GHL ذلك، وسيفشل الإرسال إلى جهات الاتصال التي تم إلغاء اشتراكها. قم بتضمين المعلمة type: "SMS" المطلوبة ورقم Twilio لموقع GHL الخاص بك باعتباره المرسل.

كيف أتعامل مع صفحات GHL API لمجموعات البيانات الكبيرة؟

تعرض نقاط نهاية قائمة GHL نتائج مرقّمة. تتضمن الاستجابة كائن meta مع total وcurrentPage وnextPage (أو startAfterId المستند إلى المؤشر). قم بتنفيذ ترقيم الصفحات من خلال التكرار عبر الصفحات حتى يصبح nextPage فارغًا أو تقوم بجمع كافة السجلات. بالنسبة لصادرات جهات الاتصال الكبيرة (أكثر من 100000 جهة اتصال)، استخدم ميزة التصدير المجمع لـ GHL أو اتصل بدعم GHL لطلب تصدير البيانات - يعد ترقيم الصفحات عبر واجهة برمجة التطبيقات لمجموعات البيانات الكبيرة جدًا بطيئًا ومكثفًا للسعر.

هل توجد بيئة اختبار معزولة لاختبار عمليات تكامل GHL API؟

ليس لدى GHL بيئة رمل مخصصة. استخدم حسابًا تجريبيًا منفصلاً لـ GHL أو حسابًا فرعيًا للتطوير للاختبار. قم بإنشاء جهات اتصال اختبارية تحتوي على رسائل بريد إلكتروني ذات علامات واضحة (على سبيل المثال، [email protected]) لتمييز بيانات الاختبار عن جهات الاتصال الحقيقية. قم بتنظيف بيانات الاختبار بانتظام للحفاظ على تنظيم حساب التطوير الخاص بك.

ما هي أفضل طريقة لتخزين معرفات جهات اتصال GHL في نظامي الخارجي؟

قم بتخزين GHL contact.id (سلسلة فريدة) كحقل مخصص في نظامك الخارجي (على سبيل المثال، عمود ghl_contact_id في قاعدة البيانات الخاصة بك). يؤدي ذلك إلى تمكين مكالمات API المباشرة إلى جهة الاتصال الصحيحة دون خطوة بحث. عند إنشاء جهات اتصال في GHL، قم بتخزين المعرف الذي تم إرجاعه على الفور. بالنسبة للمزامنة ثنائية الاتجاه، قم أيضًا بتخزين المعرف الفريد لنظامك كحقل GHL مخصص (على سبيل المثال، external_user_id) للبحث العكسي.

---

الخطوات التالية

تجعل واجهة برمجة التطبيقات (API) ونظام الويب هوك الخاص بـ GoHighLevel منصة قابلة للتوسيع بشكل حقيقي - ليست مجرد أداة تسويق بدون تعليمات برمجية، ولكنها محرك اتصالات قابل للبرمجة مع العملاء يمكنه التكامل مع أي نظام أعمال تقريبًا. المفتاح هو بناء عمليات تكامل نظيفة ومختبرة جيدًا مع معالجة الأخطاء بشكل صحيح والتحقق من التوقيع من البداية.

خدمات GoHighLevel من ECOSIRE تتضمن تطوير تكامل API مخصص. يقوم فريقنا الفني ببناء تكاملات GHL لمنصات التجارة الإلكترونية وأنظمة تخطيط موارد المؤسسات (ERP) وأدوات إدارة الخدمة الميدانية وتطبيقات الأعمال الخاصة. نقوم بتصميم عمليات تكامل مع معالجة الأخطاء بشكل مناسب وإدارة حدود المعدل والمراقبة.

اتصل بفريقنا لمناقشة متطلبات التكامل المخصصة الخاصة بك والحصول على نطاق فني لمشروع تكامل GHL المحدد الخاص بك.