موصل Stripe

موصل Stripe

اربط حساب Stripe الخاص بك مع Brevo عبر Tajo لمزامنة كاملة لبيانات الدفع، وإدارة دورة حياة الاشتراكات، وأتمتة التسويق المدفوعة بالإيرادات.

نظرة عامة

الميزات

• مزامنة العملاء - مزامنة عملاء Stripe مع جهات اتصال Brevo بما في ذلك البيانات الوصفية
• تتبع المدفوعات - تتبع المدفوعات الناجحة، والاسترداد، والرسوم الفاشلة
• إدارة الاشتراكات - مزامنة أحداث دورة حياة الاشتراكات لحملات الاحتفاظ
• بيانات الفواتير - مزامنة تفاصيل الفواتير لأتمتة ما بعد الشراء والتجديد
• إسناد الإيرادات - ربط القيمة الدائمة والإيراد الشهري المتكرر (MRR) بسمات Brevo
• أحداث Webhook - إشعارات أحداث آنية لجميع أنشطة الدفع
• دعم متعدد العملات - معالجة المدفوعات بعملات متعددة
• تتبع جلسات الدفع - تتبع Stripe Checkout لاسترداد المدفوعات المهجورة

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

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

1. حساب Stripe مع وصول إلى API
2. مفاتيح Stripe API (المفتاح القابل للنشر والمفتاح السري)
3. حساب Brevo مع وصول إلى API
4. حساب Tajo

المصادقة

مصادقة مفتاح API

يستخدم Stripe مصادقة bearer token مع مفتاح API السري الخاص بك.

curl https://api.stripe.com/v1/customers \
  -u sk_live_YOUR_SECRET_KEY:

مفاتيح API المقيدة

أنشئ مفاتيح مقيدة بصلاحيات محددة لأمان معزز:

1. انتقل إلى Stripe Dashboard > Developers > API Keys
2. انقر على “Create restricted key”
3. امنح فقط الصلاحيات التي يتطلبها Tajo

الصلاحيات المطلوبة

customers: read
charges: read
payment_intents: read
subscriptions: read
invoices: read
events: read
products: read
prices: read

الإعداد

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

connectors:
  stripe:
    enabled: true
    secret_key: "${STRIPE_SECRET_KEY}"
    webhook_secret: "${STRIPE_WEBHOOK_SECRET}"

    # Data sync options
    sync:
      customers: true
      payments: true
      subscriptions: true
      invoices: true
      products: true

    # Brevo list assignment
    lists:
      all_customers: 20
      subscribers: 21
      churned: 22

تعيين الحقول

ربط بيانات عملاء Stripe بسمات جهات اتصال Brevo:

تعيين السمات المخصصة

field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Payment metrics
  total_spent: TOTAL_SPENT
  payment_count: PAYMENT_COUNT
  last_payment_date: LAST_PAYMENT_DATE
  average_order_value: AOV

  # Subscription fields
  subscription_status: SUB_STATUS
  plan_name: PLAN_NAME
  mrr: MONTHLY_REVENUE
  subscription_start: SUB_START_DATE

  # Custom metadata
  metadata.customer_tier: VIP_TIER
  metadata.referral_source: REFERRAL_SOURCE

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

نقاط النهاية الأساسية

نقاط نهاية الاشتراكات

نقاط نهاية الأحداث

الأحداث

أحداث الدفع

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

أحداث العميل

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

تهيئة الموصل

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

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

// Connect Stripe
await tajo.connectors.connect('stripe', {
  secretKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
});

تشغيل مزامنة العملاء

// مزامنة تاريخية كاملة
await tajo.connectors.sync('stripe', {
  type: 'full',
  resources: ['customers', 'subscriptions', 'payments'],
  since: '2023-01-01'
});

// التحقق من حالة المزامنة
const status = await tajo.connectors.status('stripe');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   customersSynced: 12500,
//   subscriptionsSynced: 8200,
//   paymentsSynced: 45000
// }

التعامل مع Stripe Webhooks

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

app.post('/webhooks/stripe', async (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // إعادة التوجيه إلى Tajo لمزامنة Brevo
  await tajo.connectors.handleWebhook('stripe', {
    type: event.type,
    data: event.data.object
  });

  res.status(200).json({ received: true });
});

حدود المعدل

يفرض Stripe حدود المعدل التالية:

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

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

وضع التصحيح

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

connectors:
  stripe:
    debug: true
    log_level: verbose
    log_webhooks: true

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

tajo connectors test stripe
# ✓ API connection successful
# ✓ Customers readable
# ✓ Subscriptions readable
# ✓ Payments readable
# ✓ Webhook endpoint verified

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

1. استخدم مفاتيح API المقيدة - أنشئ مفاتيح بأدنى الصلاحيات المطلوبة
2. تحقق دائمًا من توقيعات webhook - منع أحداث webhook المزورة
3. تعامل مع idempotency - استخدم معرّفات أحداث Stripe لمنع المعالجة المكررة
4. زامن البيانات الوصفية للعميل - خزّن البيانات ذات الصلة بالتسويق في حقول البيانات الوصفية لـ Stripe
5. راقب تسليم webhook - تحقق من Stripe Dashboard للتسليمات الفاشلة
6. استخدم وضع الاختبار أولاً - تحقق من تكاملك باستخدام وضع اختبار Stripe وساعات الاختبار

الأمان

• مصادقة مفتاح API - وصول قائم على المفتاح السري مع دعم المفاتيح المقيدة
• التحقق من توقيع Webhook - التحقق من توقيع HMAC SHA-256
• تشفير TLS - جميع اتصالات API مشفرة عبر HTTPS
• الامتثال لـ PCI - يتعامل Stripe مع الامتثال لـ PCI DSS لبيانات الدفع
• قائمة IP المسموح بها - قيود IP اختيارية للوصول إلى API

موارد ذات صلة

• وثائق Stripe API
• دليل Stripe Webhooks
• موصل Shopify
• مهارة مزامنة العملاء
• واجهة جهات اتصال Brevo