توثيق تكامل ceentra.com مع Centra Meet

نظرة عامة

التكامل server-to-server: خادم ceentra.com يستدعي واجهة Centra Meet لإنشاء اجتماع مرتبط بموعد استشارة. المستخدمون (المستشار والعميل) يدخلون عبر روابط مباشرة دون تسجيل دخول إلزامي.

حالة التكامل على هذا الخادم

إعدادات البيئة

في Centra Meet (.env)

CENTRA_INTEGRATION_ENABLED=true
CENTRA_API_KEY=your-shared-secret-key
CENTRA_ALLOWED_ORIGINS=https://ceentra.com,https://www.ceentra.com,http://localhost
CENTRA_SSO_TTL_MINUTES=15

MAIL_MAILER=smtp
MAIL_HOST=mail.example.com
MAIL_FROM_ADDRESS=info@ceentra.com

LIVEKIT_ENABLED=true

في Centra / ceentra.com (.env)

CENTRA_MEET_ENABLED=true
CENTRA_MEET_API_URL=https://meet.ceentra.com
CENTRA_MEET_API_KEY=your-shared-secret-key
CENTRA_MEET_SOURCE_ORIGIN=https://ceentra.com

المصادقة والرؤوس المطلوبة

المسارات محدودة بـ 60 طلب/دقيقة لكل عنوان IP.

حجز موعد — POST /api/centra/bookings

ينشئ اجتماع فيديو 1:1 مرتبطاً بـ external_booking_id. الطلب idempotent: إعادة نفس المعرّف تُرجع نفس البيانات دون تكرار الإيميلات.

مخطط طلب الحجز (JSON)

{
  "external_booking_id": "appointment-1001",
  "centra_consultation_request_id": 42,
  "session_type": "video",
  "title": "استشارة تسويق رقمي",
  "description": "جلسة لمناقشة خطة التسويق للربع القادم",
  "timezone": "Asia/Riyadh",
  "scheduled_start_at": "2026-06-20T14:00",
  "duration_minutes": 60,
  "chat_enabled": true,
  "assistant_enabled": false,
  "provider": "livekit",
  "send_emails": true,
  "host": {
    "centra_user_id": 10,
    "name": "أحمد المستشار",
    "email": "consultant@ceentra.com",
    "timezone": "Asia/Riyadh",
    "password_hash": "$2y$12$..."
  },
  "participant": {
    "centra_user_id": 20,
    "name": "سارة العميلة",
    "email": "client@ceentra.com",
    "timezone": "Asia/Riyadh"
  }
}

شرح الحقول

مخطط الاستجابة الناجحة

HTTP 201 عند الإنشاء، أو 200 عند الاسترجاع (idempotent).

{
  "success": true,
  "message": "تم إنشاء اجتماع Centra Meet وإرسال روابط الدخول.",
  "created": true,
  "meeting": {
    "public_id": "01JXYZ...",
    "title": "استشارة تسويق رقمي",
    "description": "جلسة لمناقشة خطة التسويق",
    "scheduled_start_at": "2026-06-20 14:00",
    "url": "https://meet.ceentra.com/meetings/01JXYZ...",
    "host_join_url": "https://meet.ceentra.com/j/32charAccessTokenExampleHere12",
    "host_link_url": "https://meet.ceentra.com/j/32charAccessTokenExampleHere12",
    "participant_invitation_url": "https://meet.ceentra.com/j/32charAccessTokenExampleHere12"
  },
  "host": {
    "id": 1,
    "email": "consultant@ceentra.com",
    "name": "أحمد المستشار",
    "created": true,
    "join_url": "https://meet.ceentra.com/j/32charAccessTokenExampleHere12",
    "invitation_url": null,
    "sso_url": "https://meet.ceentra.com/centra/sso?..."
  },
  "participant": {
    "id": 2,
    "email": "client@ceentra.com",
    "name": "سارة العميلة",
    "created": true,
    "join_url": null,
    "invitation_url": "https://meet.ceentra.com/j/32charAccessTokenExampleHere12",
    "sso_url": "https://meet.ceentra.com/centra/sso?..."
  },
  "notifications": {
    "host_email_sent": true,
    "participant_email_sent": true
  }
}

روابط SSO — POST /api/centra/sso-links

اختياري — لتسجيل دخول المستخدم إلى لوحة Centra Meet (وليس للدخول المباشر للفيديو).

{
  "email": "client@ceentra.com",
  "centra_user_id": 20,
  "meeting_public_id": "01JXYZ..."
}

{
  "success": true,
  "message": "تم إنشاء رابط الدخول بنجاح.",
  "sso_url": "https://meet.ceentra.com/centra/sso?..."
}

الدخول بدون تسجيل دخول

من لوحة المستشار في Centra

واجهة ceentra.com الداخلية (بعد تسجيل دخول المستشار):

POST /api/consultant/appointments/{appointment_id}/meet/sync
Authorization: Bearer {consultant_token}

تستدعي داخلياً CentraMeetService::bookAppointment() وتُرجع:

{
  "success": true,
  "message": "تم إنشاء اجتماع Centra Meet وإرسال روابط الدخول إلى المشاركين.",
  "data": { ... نفس حقول استجابة Meet ... }
}

معاينة قبل التأكيد:

GET /api/consultant/appointments/{appointment_id}/meet/preview

رسائل الخطأ

صيغة موحّدة:

{
  "success": false,
  "message": "يجب أن يكون موعد الحجز في المستقبل.",
  "errors": {
    "scheduled_start_at": ["يجب أن يكون موعد الحجز في المستقبل."]
  }
}

أمثلة cURL

إنشاء حجز

curl -X POST "https://meet.ceentra.com/api/centra/bookings" \
  -H "Authorization: Bearer your-shared-secret-key" \
  -H "X-Centra-Source: https://ceentra.com" \
  -H "Origin: https://ceentra.com" \
  -H "Content-Type: application/json" \
  -d '{
    "external_booking_id": "appointment-1001",
    "session_type": "video",
    "title": "استشارة تسويق",
    "description": "جلسة استشارية",
    "timezone": "Asia/Riyadh",
    "scheduled_start_at": "2026-06-20T14:00",
    "duration_minutes": 60,
    "send_emails": true,
    "host": {
      "centra_user_id": 10,
      "name": "أحمد المستشار",
      "email": "consultant@ceentra.com",
      "timezone": "Asia/Riyadh",
      "password_hash": "$2y$12$..."
    },
    "participant": {
      "centra_user_id": 20,
      "name": "سارة العميلة",
      "email": "client@ceentra.com",
      "timezone": "Asia/Riyadh"
    }
  }'

طلب رابط SSO

curl -X POST "https://meet.ceentra.com/api/centra/sso-links" \
  -H "Authorization: Bearer your-shared-secret-key" \
  -H "X-Centra-Source: https://ceentra.com" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@ceentra.com",
    "centra_user_id": 20,
    "meeting_public_id": "01JXYZ..."
  }'

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

المصادر المسموحة حالياً

• https://ceentra.com
• https://www.ceentra.com