سجل تغييرات المطورين: API وwebhooks وOAuth وMCP

دورة حياة Flow

• يُرجع GET /v1/flows/{id} حالة Flow في Meta (metaStatus)، وشاشاته وحقوله وإجراء الإرسال.
• يتحقق POST /v1/flows/{id}/publish?dry_run=true من Flow دون نشره.
• يُوقف POST /v1/flows/{id}/deprecate العمل بـ Flow في Meta. لا يمكن لـ Meta التراجع عن ذلك. يمنعه Flowella ما دامت هناك قوالب تستخدم Flow، إلا إذا أرسلت force.
• يُرجع DELETE /v1/flows/{id} الرمز 409 HUBSPOT_FLOW_MANAGED لـ Flow مبني من نموذج HubSpot، و409 FLOW_REFERENCED_BY_TEMPLATES ما دامت مسودة قالب تستخدم Flow. لا يؤدي حذف Flow أبدًا إلى حذفه في Meta: أوقف العمل به أولًا لإيقافه هناك. يُرجع نشر Flow موقوف العمل به 409 FLOW_DEPRECATED.
• عند إنشاء قالب، يمكن لزر Flow أن يشير إلى Flowella Flow باستخدام flowellaFlowId بدلًا من معرّف Meta Flow.
• تُنشر Flows التي تنشئها عبر API بشاشة الدخول MAIN_FORM. تستمر Flows التي نشرتها سابقًا في العمل. أعد نشرها قبل استخدامها مع flowellaFlowId.

Webhooks

• حدث جديد flow.status_updated عند تغيّر حالة Flow في Meta، مثلًا عند إيقاف العمل به. اشترك فيه من Settings ← Webhooks. أنواع الأحداث

بيانات الاعتماد

• يُرجع GET /v1/ping طريقة تسجيل دخولك والنطاقات المتاحة لك، ومعرّف العميل بالنسبة إلى التطبيقات. التحقق من بيانات الاعتماد
• تتضمن الاستجابات المُعادة لمنع التكرار الترويسة Idempotent-Replayed: true. منع التكرار

خادم MCP

• يمكن لمساعدي الذكاء الاصطناعي الاتصال بخادم Flowella MCP بتسجيل الدخول، دون مفتاح API. يختار المستخدم مؤسسة وينقر على Allow access في شاشة الموافقة في Flowella. الاتصالات من الأعضاء الذين ليسوا Owner أو Admin للقراءة فقط. تطبيقات المطورين
• أصبحت Installed apps الآن AI assistants، مع عمود Last token. مراجعة التطبيقات المثبتة وإلغاء وصولها

• خادم Flowella MCP. يمكن لمساعدي الذكاء الاصطناعي الذين يدعمون Model Context Protocol قراءة قنواتك وقوالبك وFlows. الخادم للقراءة فقط ويستخدم مفتاح API للمؤسسة. مفاتيح API
• يقبل GET /v1/flows/{id} معرّف نموذج Flowella. تعديل مخطط Flow مبني من نموذج HubSpot يُرجع 409: أجرِ التغيير في HubSpot ثم زامن مرة أخرى. Flowella REST API
• يمكن لـ Flows المبنية في Flowella إرسال كل إرسال إلى إحدى نقاط نهاية webhook لديك، ويُضبط ذلك في تبويب Settings الخاص بـ Flow. Webhooks
• تسجيل تطبيق مطور بعنوان URI لإعادة التوجيه غير صالح يُرجع خطأً بلغة واضحة. تسجيل تطبيق

التغييرات الجذرية

• لا يقبل API-Version إلا 2026-08-11. أي قيمة أخرى تُرجع 400. احذف الترويسة، أو أرسل 2026-08-11. إدارة الإصدارات
• تحتاج نقاط نهاية webhook إلى عنوان URL عام يستخدم HTTPS. لا تُقبل العناوين الخاصة وعناوين loopback وعناوين بيانات التعريف السحابية. تحقق من كل نقطة نهاية قبل الترقية. إضافة نقطة نهاية webhook
• تطبيقات OAuth. راجع هذه المتطلبات قبل ترقية تطبيق مبني على Flowella OAuth:
  • تحصل الطلبات التي لا تتضمن نطاقًا على وصول للقراءة فقط، وتُرفض النطاقات غير المعروفة.
  • تتطلب نقاط نهاية token وintrospect وrevoke مصادقة العميل.
  • يتطلب طلب التفويض state.
  • لا تُرجع منح client credentials رمز تحديث.
  • إلغاء رمز يلغي عائلة ذلك الرمز فقط.
  تطبيقات المطورين

API

• تتضمن استجابات الأخطاء requestId داخل error، ويمكنك ذكره عند التواصل مع الدعم. الأخطاء
• يُرجع إنشاء جهة اتصال 201 ويُرجع تحديثها 200. يُرجع تكرار externalId الرمز 409، وتُرجع جهة الاتصال المحذوفة 404.

Webhooks

• أحداث جديدة contact.created وcontact.updated وcontact.deleted. أنواع الأحداث
• امنح كل نقطة نهاية اسمًا عبر Name (optional). يظهر الاسم فوق عنوان URL في القائمة.
• لمدة 24 ساعة بعد تدوير سر التوقيع، يوقّع Flowella كل عملية تسليم أيضًا بالسر القديم ويرسل التوقيع في X-Flowella-Signature-Previous، لتتمكن من تبديل الأسرار دون فقدان أحداث. تدوير سر التوقيع
• يحتفظ الحدث المُعاد تسليمه بمعرّف الحدث وطابعه الزمني الأصليين. تتضمن سجلات التسليم في API معرّف الارتباط وترويسات الاستجابة ووقت المحاولة التالية. إزالة تكرار الأحداث
• يتلقى مالكو المؤسسة إشعارًا واحدًا عندما يوقف Flowella نقطة نهاية فاشلة مؤقتًا. المحاولات المتكررة والتراجع

• استخدم https://api.flowella.io. تُرجع الطلبات إلى https://api.flowella.io/v1/... بيانات JSON. تُعاد توجيه عناوين URL القديمة https://app.flowella.io/api/v1/...، بما فيها مستند OpenAPI، بشكل دائم إلى مضيف API. حدّث عنوان URL الأساسي لديك كي لا تعتمد على إعادة التوجيه. عنوان URL الأساسي
• الخادم الأول في مستند OpenAPI هو https://api.flowella.io، فتستدعي المجموعات المستوردة عنوان URL الأساسي الصحيح. مواصفة OpenAPI
• يرفض API مكونات القوالب غير الصالحة، والقوالب التي تتجاوز حدود الإرسال في Meta، قبل وصولها إلى Meta.
• يمكنك إنشاء قوالب العرض الدوّار وإرسالها عبر API. إذا لم تمرّر وسائط لبطاقة ما، يستخدم Flowella النموذج المعتمد لتلك البطاقة. قوالب العرض الدوّار
• تنطبق القيم الاحتياطية لمتغيرات القوالب على عمليات الإرسال عبر API. القيم الاحتياطية
• يتضمن Developer hub أدلة كاملة ومجموعة Postman. مركز المطورين

• تُرسَل عمليات الإرسال المتكررة للقالب نفسه عبر API بشكل أسرع.
• عندما تقيّد Meta استدعاءً لإدارة القوالب، يبلّغ Flowella عنه كحد للمعدل، فتتباطأ محاولاتك المتكررة بالشكل الصحيح. حدود المعدل

• يُرجع POST /v1/templates/send الرمز 202. يقبل Flowella الطلب، ويُرجع معرّف مهمة فورًا ويسلّم الرسائل في الخلفية، مع إعادة المحاولة عند أخطاء WhatsApp المؤقتة. إذا كان تكاملك يتحقق من استجابة 200، فحدّثه ليتوقع 202 مع "status": "accepted". تابع التسليم في تبويب Statistics الخاص بالقالب. الإرسال الجماعي للقوالب
• Idempotency-Key. أرسل الترويسة Idempotency-Key مع POST /v1/templates/send وسيتعرّف Flowella على تكرارات الطلب نفسه لمدة سبعة أيام، ويُرجع معرّف المهمة الأصلي بدلًا من الإرسال مرة أخرى. منع التكرار

• أصبحت REST v1 موثّقة ومتاحة على مضيف API المخصص على المسار /v1/.... Flowella REST API