الانتقال إلى المحتوى الرئيسي
تتيح لك واجهة برمجة التطبيقات REST الخاصة بـ “Flowella ” إرسال رسائل “WhatsApp ”، وإدارة جهات الاتصال وحالات إلغاء الاشتراك، وعرض القوالب وإرسالها بشكل جماعي، واستخراج التحليلات — برمجياً. تغطي هذه الصفحة كل ما تحتاج إلى معرفته قبل استدعاء نقطة نهاية. توجد مرجع نقاط النهاية الكامل في الشريط الجانبي مرجع واجهة برمجة التطبيقات (يتم إنشاؤه تلقائيًا من مواصفات OpenAPI ).

​
عنوان URL الأساسي

https://app.flowella.io
توجد جميع نقاط النهاية v1 تحت/api/v1 .

​
المصادقة

يحتاج كل طلب إلى مفتاح API في رأسAuthorization : 
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
المفاتيح محددة بنطاق المؤسسة — فهي تعمل على مؤسسة واحدة Flowella وترث أذونات المسؤول في تلك المؤسسة.
تعامل مع المفاتيح ككلمات مرور. لا تقم أبدًا بإدراجها في التحكم في المصدر، ولا تلصقها أبدًا في الدردشة أو المستندات المشتركة، وقم بتغييرها عندما يغادر زملاء الفريق المؤسسة. انظر الإعدادات → مفاتيح API لمعرفة خطوات التغيير.

​
إنشاء مفتاح

تحتاج إلى دور المالك أو المسؤول لإدارة مفاتيح API.
  1. انتقل إلى الإعدادات → مفاتيح API في تطبيق Flowella .
  2. انقر على إنشاء مفتاح وأعطه اسمًا يسهل تذكره.
  3. انسخ المفتاح مرة واحدة — فهو يظهر فقط عند إنشائه.
تعامل مع المفاتيح ككلمات المرور: لا تقم أبدًا بإدراجها في نظام التحكم في المصادر، ولا تلصقها أبدًا في الدردشة، وقم بتدويرها عندما يغادر زملاء الفريق المنظمة.

​
التحقق من المفتاح

اضغط على نقطة نهاية ping لتأكيد صحة المفتاح: 
curl https://app.flowella.io/api/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
يعني الرد200 OK مع{ "ok": true, "organizationId": "…" } أنك قد تمت مصادقتك.

​
الأخطاء

تظهر جميع الأخطاء في غلاف ثابت: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
حالة HTTPمتى ستراها
400
فشل التحقق من الصحة، أو نص غير صحيح، أو رفض من Meta
401
مفتاح API مفقود أو غير صالح
402
الدفع مطلوب — اشتراكك لا يغطي هذه العملية
403
ممنوع — على سبيل المثال، الإرسال إلى جهة اتصال قامت بإلغاء الاشتراك، أو Meta
غير متصل
404
القناة أو المورد المطلوب غير موجود
429
معدل محدود — إبطاء
حقلerror.code ثابت وآمن للتشغيل برمجياً. أماerror.message فهو قابل للقراءة البشرية وقد يتغير.

​
حدود المعدل

مفاتيح API محدودة السرعة لكل مؤسسة. إذا تجاوزت الحد، فستحصل على خطأ “429 ” مع الرمز “RATE_LIMITED ” والرسالة “Too many requests ”. تراجع وحاول مرة أخرى مع تأخير أسي. إذا كنت تقوم بإرسال كميات كبيرة، فافضل **POST /api/v1/templates/send ** مع المعلمة “throttlePerHour ” — حيث يفرض “Flowella ” التقييد من جانب الخادم، لذا لا تحتاج إلى تنظيم الطلبات بنفسك.

​
ترقيم الصفحات

تستخدم نقاط نهاية القائمة (/conversations ،/contacts ،/templates ) ترقيم الصفحات بالمؤشر:
  • مررlimit (1–100، الافتراضي 25) وcursor اختياري.
  • تحتوي الاستجابة علىitems ، وعندما يكون هناك المزيد من النتائج،nextCursor .
  • مررnextCursor مرة أخرى كمعلمةcursor لجلب الصفحة التالية.
  • عندما يكونnextCursor مفقودًا، فهذا يعني أنك وصلت إلى النهاية.
curl "https://app.flowella.io/api/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

​
التاريخ والوقت

جميع الطوابع الزمنية هي سلاسل ISO 8601 بتوقيت UTC (على سبيل المثال2025-01-15T14:30:00.000Z ). عندما تقبل واجهة برمجة التطبيقات (API) التواريخ، يتم تحويل كل من التواريخ فقط (2025-01-15 ) و ISO 8601 الكاملة إلى صيغة محددة من جانب الخادم.

​
أرقام الهواتف

قم بتمرير أرقام الهواتف بتنسيق E.164 (+15551234567 ) حيثما أمكن ذلك. سيقوم Flowella بتوحيد الاختلافات الشائعة من جانب الخادم، ولكن تنسيق E.164 هو الأكثر أمانًا.

​
القنوات

تقبل العديد من نقاط النهاية معرف القناة (whatsappChannelId ). إذا كان لدى مؤسستك قناة واحدة وقمت بحذفها، فسيستخدم Flowella قناتك الافتراضية. إذا كان لديك عدة قنوات، فقم بتمرير المعرف بشكل صريح لتجنب الإرسال من المرسل الخاطئ. للاطلاع على نمط URL الكامل وتبديل القنوات، انظر القنوات المتعددة.

​
مواصفات OpenAPI

توجد المواصفات القابلة للقراءة آليًا على: 
/api-reference/openapi.json
قم بإدراجها في Postman أو Insomnia أو منشئ الكود الذي تختاره.
هل تقوم بإنشاء تكامل؟ اربط هذه الصفحة بـ Webhooks للتفاعل مع الأحداث بدلاً من استقصاء الحالة.