الموصّلات (Connectors)

اربط تطبيقك بخدمات خارجية مثل Slack وResend وElevenLabs. يتم تشفير بيانات الاعتماد وتتم المصادقة المسبقة على الإجراءات تلقائيًا.

تتيح لك الموصّلات دمج الخدمات الخارجية في تطبيقك دون الحاجة إلى إدارة مفاتيح API الخام في الكود. تُعدّ الاتصال مرة واحدة، وتربطه بمشروعك، ثم تستدعي الإجراءات الجاهزة من تطبيقك عبر Proyecta SDK. تُخزَّن بيانات الاعتماد مشفّرة ولا تُكشف أبدًا لكود الـ frontend.

الموصّلات المتاحة

الموصّل	الفئة	نوع المصادقة	ما الذي يفعله
Resend	الاتصالات	مفتاح API	إرسال بريد إلكتروني تحويلي، إرسال رسائل دفعية، عرض النطاقات الموثّقة
Slack	الاتصالات	OAuth	نشر الرسائل، عرض القنوات والمستخدمين، التفاعل مع الرسائل، قراءة المحادثات
ElevenLabs	الذكاء الاصطناعي	مفتاح API	تحويل النص إلى كلام، عرض الأصوات المتاحة، توليد المؤثرات الصوتية

يتم إضافة موصّلات جديدة بانتظام.

كيف تعمل الموصّلات

1. تُنشئ اتصالًا — تُقدّم بيانات الاعتماد (مفتاح API أو تسجيل الدخول عبر OAuth)
2. تربط الاتصال بمشروع — يُخوّل هذا المشروعَ باستخدام تلك البيانات
3. يستدعي تطبيقك الإجراءات — يُرسل SDK الطلب عبر Proyecta Cloud، الذي يُدرج بيانات الاعتماد على جانب الـ server

لا يتعامل كود تطبيقك أبدًا مع مفتاح API الخام أو رمز OAuth. يتولى نظام الموصّلات المصادقة وتحديد معدل الطلبات وسجلات التدقيق.

إعداد موصّل

1. افتح مشروعك في Builder
2. انتقل إلى Settings > Connectors
3. انقر على موصّل من القائمة (مثل Resend)
4. أدخل بيانات الاعتماد:
   • موصّلات مفتاح API (Resend، ElevenLabs): الصق مفتاحك السري
   • موصّلات OAuth (Slack): سجّل الدخول وامنح الصلاحية
5. أعطِ الاتصال اسمًا (مثل “Production Resend”)
6. يُختبَر الاتصال تلقائيًا ويُوسَم بـ Active إذا كان صالحًا

استخدام موصّل في تطبيقك

تُستدعى إجراءات الموصّلات من كود جانب الـ server (إجراءات Convex) باستخدام Proyecta SDK:

'use node';
import { action } from './_generated/server';
import { v } from 'convex/values';
import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY ?? null });

export const notifySlack = action({
    args: {
        message: v.string(),
    },
    handler: async (ctx, args) => {
        const result = await proyecta.connectors.execute({
            connectorId: 'slack',
            actionId: 'postMessage',
            input: {
                channel: '#general',
                text: args.message,
            },
        });
        return result.output;
    },
});

تُعيد دالة execute القيم التالية:

الحقل	الوصف
output	القيمة التي يُعيدها الإجراء (يختلف شكلها بحسب الإجراء)
durationMs	وقت التنفيذ بالميللي ثانية
invocationId	معرّف إدخال سجل التدقيق

دع الذكاء الاصطناعي يتولى التوصيل

لست مضطرًا لكتابة كود الموصّلات يدويًا. يعرف Builder بالذكاء الاصطناعي الموصّلات المرتبطة بمشروعك ويمكنه توليد التكامل نيابةً عنك:

• "أرسل بريد ترحيب عند تسجيل المستخدمين" — يستخدم موصّل Resend
• "انشر رسالة Slack عند ورود طلب جديد" — يستخدم موصّل Slack
• "شغّل تعليقًا صوتيًا في صفحة المقال" — يستخدم موصّل ElevenLabs

مرجع إجراءات الموصّلات

Resend

الإجراء	التأثيرات الجانبية	الوصف
sendEmail	كتابة	إرسال بريد إلكتروني تحويلي واحد
sendBatch	كتابة	إرسال رسائل إلكترونية متعددة دفعة واحدة
listDomains	قراءة	عرض النطاقات الموثّقة للإرسال

Slack

الإجراء	التأثيرات الجانبية	الوصف
postMessage	كتابة	نشر رسالة في قناة
listChannels	قراءة	عرض القنوات في مساحة العمل
listUsers	قراءة	عرض أعضاء مساحة العمل
reactToMessage	كتابة	إضافة تفاعل إيموجي
getThread	قراءة	الحصول على الردود في محادثة

ElevenLabs

الإجراء	التأثيرات الجانبية	الوصف
textToSpeech	كتابة	تحويل النص إلى كلام صوتي
listVoices	قراءة	عرض الأصوات المتاحة
generateSoundEffect	كتابة	توليد مؤثر صوتي بالذكاء الاصطناعي

حالات الاتصال

الحالة	المعنى
Active	بيانات الاعتماد صالحة والاتصال جاهز للاستخدام
Broken	انتهت صلاحية بيانات الاعتماد أو تم إلغاؤها — قم بتحديثها لاستعادة الاتصال

الأمان

• تُشفَّر بيانات الاعتماد باستخدام AES-256-GCM أثناء التخزين
• تخضع الإجراءات لتحديد معدل الطلبات بحد أقصى 1,000 طلب في الدقيقة لكل موصّل لكل مشروع
• يُسجَّل كل استدعاء إجراء مع مسار تدقيق كامل (الاتصال، الإجراء، المدة، الحالة)
• نطاق الاتصالات يشمل مساحة العمل بالكامل

الأسئلة الشائعة

هل يمكنني استخدام نفس الاتصال عبر مشاريع متعددة؟

نعم. أنشئ الاتصال مرة واحدة واربطه بأي عدد من المشاريع في مساحة العمل ذاتها.

ماذا يحدث إذا انتهت صلاحية مفتاح API أو تم إلغاؤه؟

تتغير حالة الاتصال إلى Broken. قم بتحديث بيانات الاعتماد في Settings > Connectors لاستعادته.

هل يمكنني استدعاء إجراءات الموصّلات من الـ frontend؟

لا. يجب استدعاء إجراءات الموصّلات من كود جانب الـ server (إجراءات Convex) للحفاظ على أمان بيانات الاعتماد. يُوجّه SDK الطلبات عبر Proyecta Cloud، الذي يُدرج المصادقة على جانب الـ server.

هل يمكنني إضافة موصّلات مخصصة خاصة بي؟

ليس بعد. تعريفات الموصّلات المخصصة موجودة على خارطة الطريق.

قريبًا

• موصّلات إضافية (Google وTwilio وSendGrid والمزيد)
• تعريفات موصّلات مخصصة — أضف API الخاص بك
• استقبال Webhook للأحداث الواردة من الخدمات المرتبطة
• بوابة OAuth — احتفظ بالرموز على جانب الـ server حتى في التدفقات التي يبدأها العميل