الموصّلات

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

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

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

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

تُضاف موصّلات جديدة باستمرار.

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

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

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

إعداد موصّل

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

القراءة عبر موصّل من تطبيقك

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

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

هناك ضابطان يجدر معرفتهما، فهما مقصودان بالتصميم:

• القراءة فقط. لا يمكن الوصول إلا إلى الإجراءات التي وسمتها المنصة بأنها آمنة للمتصفح — وأي شيء غير ذلك يُعيد 403. أما عمليات الكتابة (النشر في Slack، أو إرسال البريد، أو خصم مبلغ من بطاقة) فلا يمكن بلوغها من المتصفح إطلاقاً.
• لا يمكنك تمرير رابط أو مضيف. بالنسبة للموصّل العام http-read تكون المدخلات { endpointKey, params }، والرابط الكامن خلف endpointKey تضبطه أنت بصفتك صاحب التطبيق — لا كود التطبيق. وتُخزَّن الاستجابات مؤقتاً على الخادم وتخضع لتحديد معدل الطلبات، لأن مفاتيح الأطراف الخارجية محسوبة بحصص.

ويعني الرمز 404 أن صاحب التطبيق لم يربط ذلك الموصّل بعد — وهذه هي الحالة الجديرة بالمعالجة في واجهتك.

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

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

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

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

Resend (connectorId: 'resend')

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

Slack (connectorId: 'slack')

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

ElevenLabs (connectorId: 'eleven-labs')

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

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

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

الأمان

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

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

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

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

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

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

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

لا يحتفظ تطبيقك ببيانات الاعتماد أبداً. تُمرَّر إجراءات القراءة الآمنة للمتصفح عبر Proyecta Cloud الذي يُضيف بيانات الاعتماد على جانب الخادم، فلا يظهر المفتاح في حزمة كودك مطلقاً. أما إجراءات الكتابة فلا يمكن بلوغها من المتصفح إطلاقاً.

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

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

قريباً

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