Endpoints

Endpoints هي عناوين URL المحددة التي ترسل إليها واجهتك طلبات لتنفيذ إجراءات أو استرجاع بيانات.

أنواع الطلبات

تدعم HeroMate كل طرق HTTP القياسية لمعالجة أنواع مختلفة من العمليات:

• GET (قراءة): تُستخدم لجلب البيانات من قاعدة بياناتك (مثلاً سرد المنتجات أو الحصول على ملف مستخدم).
• POST (إنشاء/إجراء): تُستخدم لحفظ معلومات جديدة أو تشغيل عملية (مثلاً إنشاء طلب أو بدء مهمة ذكاء اصطناعي).
• PATCH/PUT (تحديث): تُستخدم لتعديل سجلات موجودة (مثلاً تغيير حالة مستخدم).
• DELETE (إزالة): تُستخدم لحذف المعلومات بأمان.

إدارة Endpoints

في قسم بنّاء الـ API، يمكنك رؤية قائمة بكل endpoints. من هنا يمكنك:

التحرير باللوحة

انقر أي endpoint لفتح اللوحة البصرية. هنا يمكنك:

• مراجعة تدفق المنطق.
• تعديل العقد الموجودة أو إضافة جديدة.
• تغيير بنية الإدخال والإخراج.

الاختبار في الوقت الفعلي

استخدم لوحة Test للتحقق من أن endpoint يعمل كما تتوقع. يمكنك محاكاة سيناريوهات مختلفة ورؤية ما يُرجعه الـ API بالضبط.

البداية والمحفّزات وWebhooks

يبدأ كل endpoint في HeroMate من عقدة Start واحدة. تعرّف عقدة Start تلك كيف يُشغَّل سير العمل.

أنواع المحفّزات المتاحة

متى تستخدم Webhook

استخدم Webhook عندما تحتاج خدمة خارجية إلى إشعار مشروعك بحدث.

أمثلة شائعة:

• نجح دفع Stripe
• حدث دفع GitHub
• إرسال نموذج من أداة خارجية
• رد نداء حالة التسليم من مزوّد مراسلة

بخلاف endpoint HTTP API عادي، صُمّم webhook ليستدعيه منصة أخرى، لا واجهة تطبيقك.

كيف تعمل Webhooks في HeroMate

عندما تضبط عقدة Start كـ webhook:

• تكشف HeroMate عنوان URL فريداً لـ webhook لذلك endpoint
• يبدأ سير العمل تلقائياً عندما يستلم ذلك العنوان طلباً
• يمكنك حماية webhook بطريقة المصادقة المضبوطة (سر نظام أو رمز رأس أو HMAC أو مصادقة أساسية)
• يمكنك فحص حالة webhook والتشغيلات الأخيرة من عرض تفاصيل endpoint

هذا يسهّل ربط سير عمل HeroMate بأنظمة أحداث الأطراف الثالثة دون بناء مستقبل خلفية منفصل.

أوضاع مصادقة HTTP API

عند استخدام محفّز HTTP API، يجب اختيار وضع المصادقة:

• jwt: يتطلب endpoint جلسة مستخدم صالحة. يمكنك تقييد الوصول أكثر باستخدام Allowed Roles.
• api_key: يتطلب endpoint مفتاح API المشروع في رأس X-API-KEY. يتجاوز هذا فحوصات الأدوار وهو مثالي للتواصل من خادم إلى خادم.

endpoints العامة (دون مصادقة) غير مدعومة. يجب أن يُعرَّف كل طلب إما بمستخدم أو بمفتاح المشروع.

البناء بالذكاء الاصطناعي

تذكّر، لا تحتاج بناء هذه يدوياً. يمكنك استخدام MCP لإدارة endpoints بلغة طبيعية:

• "List all my current endpoints."
• "Explain the logic of the 'process-payment' endpoint."
• "Update the 'get-user' endpoint to also return the user's role."

عقد العناصر النائبة (workflow_code)

لتجنب الغموض، استخدم تنسيقاً صارماً واحداً في سير العمل:

• ${input.field}: بيانات إدخال endpoint
• ${vars.<variable>.field}: مخرج عقدة سابقة حسب اسمها المستعار variable (موصى به)
• ${nodes.<node_id>.field}: مخرج عقدة سابقة حسب id التقني (مدعوم أيضاً)
• ${current_user.field} و ${current_user_id}: سياق المستخدم المصادَق

لا تستخدم عناصر نائبة مسطحة مثل ${name} و ${email} و ${id}.

فحص MCP المسبق قبل إنشاء/تحديث سير العمل

قبل توليد workflow_code بالذكاء الاصطناعي:

1. استخدم list_node_catalog لاكتشاف العقد المتاحة.
2. إذا احتجت تفاصيل تقنية، استدعِ list_node_catalog للعقدة المحددة.
3. ابنِ سير العمل فقط بقيم node_type الموجودة.
4. شغّل التحقق من سير العمل قبل الحفظ.

بيانات الاعتماد في عقد التكامل

للعقد التي تتطلب مزوّدين خارجيين (ذكاء اصطناعي ومراسلة وبريد وجداول ومدفوعات)، ضمّن credential_id في parameters العقدة. تشحن HeroMate 26 نوع بيانات اعتماد مكتوبة الأنواع عبر نحو 24 مزوّداً (Stripe و Telegram و WhatsApp و Slack و Notion و Google Sheets و GitHub والمزيد) — راجع بيانات الاعتماد للقائمة الكاملة.

موصى به:

• credential_id: "${input.<provider>_credential_id}"

لا تضمّن أسراراً داخل JSON لسير العمل.

قاعدة إدراج البيانات

لـ dypai_database مع operation = insert:

• input_mode: "explicit" (موصى به): يتطلب data بأعمدة معرّفة.
• input_mode: "passthrough": إذا كان data فارغاً، يستخدم جسم طلب endpoint.

هذا يتيح النماذج الأولية السريعة مع إبقاء سلوك الإنتاج قابلاً للتوقع.

استعلام مخصص (SQL)

في عقدة dypai_database مع operation = custom_query، يستخدم حقل query الصيغة الرسمية نفسها لبقية سير العمل:

• التنسيق: ${variable}
• المتغيّرات المتاحة: ${input.field} و ${params.field} و ${current_user_id} و ${record_id} و ${limit} و ${offset}
• دون علامات اقتباس: لا تلف العناصر النائبة بعلامات اقتباس. يحوّلها المحرك إلى معاملات ربط آمنة ($1 و $2...).