---
title: "موصل HubSpot"
description: "دليل التكامل الكامل لـ HubSpot CRM لمزامنة جهات الاتصال والشركات والصفقات والتذاكر وبيانات التسويق مع Brevo عبر Tajo."
url: https://tajo.io/ar/docs/connectors/crm/hubspot/
markdown: https://tajo.io/ar/docs/connectors/crm/hubspot.md
lang: ar-SA
robots: noindex
---

اطلب الوصول المبكر

أدخل اسمك الأول وعنوان بريدك الإلكتروني للعمل. سنرسل إليك رابطًا لتأكيد طلب الوصول إلى Tajo.

# موصل HubSpot

حالة الموصل: قيد التطوير قيد البناء. لم يتم التحقق منه بعد.

| حقل المصدر | حقل الوجهة | قيمة نموذجية |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

اربط HubSpot CRM الخاص بك بـ Brevo عبر Tajo لمزامنة جهات الاتصال ثنائية الاتجاه، وتتبع الصفقات، وبيانات التفاعل، والأتمتة التسويقية الموحدة عبر كلتا المنصتين.

## نظرة عامة

| الخاصية | القيمة |
| --- | --- |
| **المنصة** | HubSpot |
| **الفئة** | CRM |
| **تعقيد الإعداد** | متوسط |
| **تكامل رسمي** | لا |
| **البيانات المتزامنة** | جهات الاتصال، الشركات، الصفقات، التذاكر، الأحداث |
| **عنوان API الأساسي** | `https://api.hubapi.com` |

## الميزات

- **مزامنة جهات اتصال ثنائية الاتجاه** - حافظ على تزامن جهات الاتصال بين HubSpot و Brevo في الوقت الفعلي
- **تتبع خط الصفقات** - زامن مراحل الصفقات وقيمها لتقسيم قائم على الإيرادات
- **مزامنة بيانات الشركات** - اربط جهات الاتصال بسجلات الشركات والبيانات المؤسسية
- **تكامل التذاكر** - تتبع تذاكر الدعم لتسجيل صحة العملاء
- **تتبع التفاعل** - زامن فتح البريد الإلكتروني، والنقرات، والاجتماعات، والمكالمات، والملاحظات
- **دعم الكائنات المخصصة** - اربط كائنات HubSpot المخصصة بسمات Brevo
- **مشغلات سير العمل** - استخدم تغييرات مرحلة دورة الحياة في HubSpot لتشغيل أتمتة Brevo
- **أحداث Webhook** - إشعارات فورية لتغييرات بيانات CRM

## المتطلبات المسبقة

قبل أن تبدأ، تأكد من توفر ما يلي:

1. حساب HubSpot (Free أو Starter أو Professional أو Enterprise)
2. تطبيق خاص في HubSpot أو تطبيق OAuth مع النطاقات المطلوبة
3. حساب Brevo مع وصول API
4. حساب Tajo

## المصادقة

### رمز وصول التطبيق الخاص (موصى به)

أنشئ تطبيقًا خاصًا في HubSpot للوصول المباشر إلى API مع تحكم دقيق في النطاقات.

1. اذهب إلى HubSpot Settings > Integrations > Private Apps
2. أنشئ تطبيقًا خاصًا جديدًا
3. اضبط النطاقات المطلوبة
4. انسخ رمز الوصول

```bash
curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

### OAuth 2.0

استخدم OAuth 2.0 لعمليات التكامل متعددة الحسابات التي تتطلب تفويض المستخدم.

```bash
# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}
```

#### النطاقات المطلوبة

```
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.schemas.custom.read
```

## الإعداد

### الإعداد الأساسي

```yaml
connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Data sync options
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: true
      engagements: true

    # Sync direction
    direction: bidirectional  # or 'hubspot_to_brevo' | 'brevo_to_hubspot'

    # List assignment in Brevo
    lists:
      all_contacts: 10
      qualified_leads: 11
      customers: 12
```

### ربط الحقول

اربط خصائص HubSpot بسمات جهات اتصال Brevo:

#### التعيينات الافتراضية

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | بريد جهة الاتصال الإلكتروني (المعرف الأساسي) |
| `firstname` optional | string | يُربط بسمة FIRSTNAME في Brevo |
| `lastname` optional | string | يُربط بسمة LASTNAME في Brevo |
| `phone` optional | string | يُربط بسمة SMS للمراسلة عبر WhatsApp/SMS |
| `company` optional | string | اسم الشركة المرتبطة |
| `lifecyclestage` optional | string | مرحلة دورة الحياة في HubSpot (subscriber، lead، MQL، SQL، customer) |
| `hs_lead_status` optional | string | حالة تأهيل العميل المحتمل |
| `hubspot_owner_id` optional | string | معرف مالك المبيعات المُعيَّن |

#### ربط الخصائص المخصصة

```yaml
field_mapping:
  # Standard fields
  email: email
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # CRM fields
  lifecyclestage: LIFECYCLE_STAGE
  hs_lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Deal metrics
  hs_total_deal_value: DEAL_VALUE
  num_associated_deals: DEAL_COUNT

  # Custom properties
  preferred_channel: PREFERRED_CHANNEL
  customer_segment: SEGMENT
```

## نقاط نهاية API

### كائنات CRM

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/contacts` | عرض قائمة جهات الاتصال |
| `POST` | `/crm/v3/objects/contacts` | إنشاء جهة اتصال |
| `PATCH` | `/crm/v3/objects/contacts/{id}` | تحديث جهة اتصال |
| `GET` | `/crm/v3/objects/companies` | عرض قائمة الشركات |
| `GET` | `/crm/v3/objects/deals` | عرض قائمة الصفقات |
| `POST` | `/crm/v3/objects/deals` | إنشاء صفقة |
| `GET` | `/crm/v3/objects/tickets` | عرض قائمة التذاكر |

### الارتباطات

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | الحصول على الارتباطات |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | إنشاء ارتباط |

### التفاعلات

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/calls` | قائمة تفاعلات المكالمات |
| `GET` | `/crm/v3/objects/emails` | قائمة تفاعلات البريد الإلكتروني |
| `GET` | `/crm/v3/objects/meetings` | قائمة الاجتماعات |
| `GET` | `/crm/v3/objects/notes` | قائمة الملاحظات |
| `GET` | `/crm/v3/objects/tasks` | قائمة المهام |

## الأحداث

### أحداث جهات الاتصال

| الحدث | المشغل | حالة الاستخدام |
| --- | --- | --- |
| `contact.creation` | إنشاء جهة اتصال جديدة | تشغيل تدفق الترحيب |
| `contact.propertyChange` | تحديث خاصية جهة الاتصال | مزامنة السمات |
| `contact.merge` | دمج جهات الاتصال | معالجة إزالة التكرار |
| `contact.deletion` | حذف جهة الاتصال | التنظيف في Brevo |

### أحداث الصفقات

| الحدث | المشغل | حالة الاستخدام |
| --- | --- | --- |
| `deal.creation` | إنشاء صفقة جديدة | إشعار المبيعات |
| `deal.propertyChange` | تغيير مرحلة الصفقة | أتمتة خط السير |
| `deal.deletion` | إزالة صفقة | تقارير الإيرادات |

### أحداث الشركات

| الحدث | المشغل | حالة الاستخدام |
| --- | --- | --- |
| `company.creation` | إضافة شركة جديدة | التسويق القائم على الحسابات |
| `company.propertyChange` | تحديث بيانات الشركة | مزامنة البيانات المؤسسية |

## أمثلة البرمجة

### تهيئة الموصل

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});
```

### تشغيل مزامنة جهات الاتصال

```javascript
// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
  type: 'full',
  resources: ['contacts', 'companies', 'deals'],
  direction: 'bidirectional',
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 34200,
//   companiesSynced: 5100,
//   dealsSynced: 2340
// }
```

### التعامل مع أحداث Webhook

```javascript
// Handle HubSpot webhook notifications
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature-v3');

  // Verify webhook signature
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      eventType: event.subscriptionType,
      objectId: event.objectId,
      propertyName: event.propertyName,
      propertyValue: event.propertyValue
    });
  }

  res.status(200).send('OK');
});
```

## حدود المعدل

يطبق HubSpot حدود معدل لكل تطبيق خاص أو تطبيق OAuth:

| الخطة | حد المعدل | حد الدفعة |
| --- | --- | --- |
| Free/Starter | 100 طلب/10 ثوانٍ | 150 طلب/10 ثوانٍ |
| Professional | 150 طلب/10 ثوانٍ | 200 طلب/10 ثوانٍ |
| Enterprise | 200 طلب/10 ثوانٍ | 250 طلب/10 ثوانٍ |
| إضافة API | 200 طلب/10 ثوانٍ | 250 طلب/10 ثوانٍ |

حدود إضافية:

- **Search API**: 5 طلبات/ثانية لكل تطبيق
- **عمليات الدُفعات**: 100 سجل لكل طلب دفعة
- **الحد اليومي**: 500,000 طلب/يوم (تطبيقات OAuth)

التعامل مع حد المعدل

يُرجع HubSpot استجابة `429 Too Many Requests` عند تجاوز الحدود. استخدم التراجع الأسي وراقب رؤوس `X-HubSpot-RateLimit-*`.

## استكشاف الأخطاء

### المشكلات الشائعة

| المشكلة | السبب | الحل |
| --- | --- | --- |
| 401 Unauthorized | رمز منتهي الصلاحية أو غير صالح | أعد توليد رمز التطبيق الخاص أو جدد رمز OAuth |
| جهة الاتصال لم تُزامن | خاصية البريد الإلكتروني مفقودة | جهات اتصال HubSpot تتطلب بريدًا إلكترونيًا للمزامنة مع Brevo |
| جهات اتصال مكررة | لا توجد قاعدة إزالة تكرار | اضبط قواعد الدمج في HubSpot |
| Webhook لم يُستلم | الاشتراك غير نشط | أعد تسجيل اشتراكات webhook |
| خاصية لم تُربط | خاصية مخصصة غير مُنشأة | أنشئ الخاصية في HubSpot أولاً |

### وضع التصحيح

فعّل تسجيلًا مفصلاً:

```yaml
connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### اختبار الاتصال

```bash
tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered
```

## أفضل الممارسات

1. **استخدم التطبيقات الخاصة بدلاً من مفاتيح API** - مفاتيح API مُهملة؛ استخدم التطبيقات الخاصة لأمان أفضل
2. **نفّذ المزامنة ثنائية الاتجاه بعناية** - تجنب الحلقات اللانهائية بتتبع مصدر المزامنة
3. **اربط مراحل دورة الحياة** - استخدم مراحل دورة الحياة في HubSpot لتقسيم جهات الاتصال في Brevo
4. **اجمع طلبات API** - استخدم نقاط نهاية الدُفعات للعمليات المجمعة للبقاء ضمن حدود المعدل
5. **راقب تسليم webhook** - أعدّ منطق إعادة المحاولة ومعالجة الحروف الميتة
6. **استخدم المزامنة التدريجية** - زامن السجلات المتغيرة فقط باستخدام خاصية `lastmodifieddate`

## الأمان

- **رموز التطبيقات الخاصة** - رموز وصول محددة النطاق بأذونات دقيقة
- **OAuth 2.0** - تفويض معياري صناعي مع تدوير رمز التحديث
- **توقيعات Webhook** - التحقق من التوقيع القائم على HMAC (v3)
- **تشفير TLS** - جميع اتصالات API مشفرة أثناء النقل
- **أذونات محددة النطاق** - وصول الحد الأدنى من النطاق المطلوب لكل تكامل

## موارد ذات صلة

- [وثائق HubSpot API](https://developers.hubspot.com/docs/api/overview)
- [دليل مصادقة HubSpot](https://developers.hubspot.com/docs/api/working-with-oauth)
- [موصل Salesforce](https://tajo.io/ar/docs/connectors/crm/salesforce)
- [مهارة مزامنة العملاء](https://tajo.io/ar/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/ar/docs/contact-management)