موصل Notion

اربط مساحة عمل Notion الخاصة بك مع Brevo لتشغيل سير عمل تسويقي قائم على المحتوى، ومزامنة قواعد بيانات إدارة علاقات العملاء، والإشعارات الآلية عبر Tajo.

نظرة عامة

الميزات

• مزامنة قواعد البيانات - مزامنة إدخالات قواعد بيانات Notion مع جهات اتصال وقوائم Brevo
• جسر إدارة علاقات العملاء - استخدام قواعد بيانات Notion كنظام CRM خفيف متزامن مع Brevo
• إشعارات المحتوى - تشغيل حملات Brevo عند نشر صفحات Notion
• تعيين الخصائص - ربط خصائص قواعد بيانات Notion بسمات جهات اتصال Brevo
• مراقبة الصفحات - تتبع تحديثات الصفحات وإعادة توجيهها كأحداث في Brevo
• مزامنة دليل المستخدمين - مزامنة أعضاء مساحة عمل Notion مع جهات اتصال Brevo

المتطلبات الأساسية

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

1. مساحة عمل Notion مع صلاحيات مسؤول
2. تكامل Notion داخلي أو تطبيق OAuth
3. صفحات قواعد بيانات تمت مشاركتها مع التكامل
4. حساب Brevo مع وصول إلى API
5. حساب Tajo مع اشتراك نشط

المصادقة

يدعم Notion طريقتين للمصادقة.

الخيار الأول: التكامل الداخلي (موصى به لمساحة عمل واحدة)

1. انتقل إلى notion.so/my-integrations
2. انقر على New integration
3. سمِّه “Tajo Integration”
4. اختر مساحة العمل الخاصة بك
5. حدد الإمكانيات:

Content Capabilities:
  Read content: ✓
  Update content: ✓
  Insert content: ✓

User Capabilities:
  Read user information: ✓

6. انسخ Internal Integration Secret (يبدأ بـ ntn_)

الخيار الثاني: OAuth 2.0 (التكاملات العامة)

للتكاملات التي تخدم مساحات عمل متعددة، استخدم تدفق OAuth 2.0:

1. سجّل التكامل الخاص بك كتكامل عام
2. أعد توجيه المستخدمين إلى: https://api.notion.com/v1/oauth/authorize?client_id=...
3. استبدل الكود برمز وصول في /v1/oauth/token

الاتصال بـ Tajo

tajo connectors install notion \
  --token $NOTION_TOKEN

الإعداد

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

connectors:
  notion:
    enabled: true
    api_version: "2022-06-28"

    sync:
      databases: true
      pages: false
      users: true

    databases:
      - id: "abc123def456"
        name: "Customers"
        sync_to_list: 25
      - id: "ghi789jkl012"
        name: "Leads"
        sync_to_list: 26

تعيين الحقول

اربط خصائص قاعدة بيانات Notion بسمات جهات اتصال Brevo:

field_mapping:
  # Notion property -> Brevo attribute
  Name:
    type: title
    target: FIRSTNAME
  Email:
    type: email
    target: email
  Phone:
    type: phone_number
    target: SMS
  Company:
    type: rich_text
    target: COMPANY
  Status:
    type: select
    target: LEAD_STATUS
  Deal Value:
    type: number
    target: DEAL_VALUE
  Last Contact:
    type: date
    target: LAST_CONTACT_DATE
  Tags:
    type: multi_select
    target: TAGS

نقاط نهاية واجهة البرمجة

يتكامل Tajo مع نقاط نهاية Notion API التالية:

أمثلة على الكود

تهيئة الموصل

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

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

await tajo.connectors.connect('notion', {
  token: process.env.NOTION_TOKEN
});

مزامنة قاعدة بيانات مع Brevo

// مزامنة قاعدة بيانات Notion إلى قائمة Brevo
await tajo.connectors.sync('notion', {
  type: 'full',
  resources: ['databases'],
  databaseId: 'abc123def456',
  targetList: 25
});

const status = await tajo.connectors.status('notion');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T14:30:00Z',
//   databasesSynced: 2,
//   pagesTracked: 1450,
//   usersCount: 32
// }

الاستعلام والتصفية

// استعلام قاعدة بيانات Notion مع عوامل تصفية
const results = await tajo.connectors.query('notion', {
  databaseId: 'abc123def456',
  filter: {
    property: 'Status',
    select: { equals: 'Active' }
  },
  sorts: [
    { property: 'Last Contact', direction: 'descending' }
  ]
});

إنشاء صفحة من حدث في Brevo

// إنشاء صفحة Notion عندما يصل جهة اتصال Brevo إلى مرحلة معينة
tajo.events.on('contact.attribute_updated', async (event) => {
  if (event.attribute === 'LIFECYCLE_STAGE' && event.value === 'customer') {
    await tajo.connectors.create('notion', {
      databaseId: 'ghi789jkl012',
      properties: {
        Name: { title: [{ text: { content: event.contact.name } }] },
        Email: { email: event.contact.email },
        'Converted Date': { date: { start: new Date().toISOString() } }
      }
    });
  }
});

حدود المعدل

يفرض Notion حدود معدل لكل تكامل:

يعيد Notion 429 Too Many Requests عند تجاوز حدود المعدل، مع ترويسة Retry-After.

استكشاف الأخطاء وإصلاحها

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

وضع التصحيح

connectors:
  notion:
    debug: true
    log_level: verbose
    log_api_calls: true

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

tajo connectors test notion
# ✓ API authentication successful
# ✓ Database access verified
# ✓ User list accessible
# ✓ Search operational
# ✓ Page creation available

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

1. شارك قواعد البيانات صراحةً - لا ترى التكاملات الداخلية سوى المحتوى المشترك
2. استخدم استعلامات قواعد البيانات بدلاً من البحث - الاستعلامات أسرع وأكثر موثوقية لقواعد البيانات المعروفة
3. عيّن أنواع الخصائص بعناية - يحتوي Notion على أنواع خصائص عديدة؛ طابقها مع أنواع سمات Brevo
4. تعامل مع ترقيم الصفحات - مرّر دائمًا عبر جميع صفحات المؤشر للحصول على البيانات الكاملة
5. المزامنة التزايدية - استخدم عوامل تصفية last_edited_time لمزامنة الإدخالات المتغيرة فقط
6. إعداد جدول استطلاع - لا يدعم Notion الـ webhooks أصلاً؛ استطلع على فترات منتظمة

الأمان

• مصادقة Bearer Token - أسرار التكامل ورموز OAuth
• HTTPS فقط - جميع اتصالات API مشفرة عبر TLS 1.2+
• وصول مُقيّد - لا تصل التكاملات إلا إلى المحتوى المشترك صراحةً
• OAuth 2.0 - تدفق تفويض آمن للتكاملات العامة
• تخزين مُشفَّر - يتم تشفير الرموز في حالة السكون داخل Tajo
• عزل مساحة العمل - يقتصر كل تكامل على مساحة عمل واحدة

موارد ذات صلة

• موصل Airtable
• موصل GitHub
• موصل Linear
• واجهة برمجة جهات اتصال Brevo