مقدمة واجهة برمجة التطبيقات

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

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

https://api.flowella.io/v1

توجد جميع نقاط نهاية v1 ضمن هذا الأساس القانوني — على سبيل المثال https://api.flowella.io/v1/messages.

كانت واجهة API سابقًا على مضيف التطبيق عند https://app.flowella.io/api/v1/.... تُعاد توجيه الطلبات إلى هذا المسار القديم بشكل دائم (308) إلى https://api.flowella.io/v1/...، مع الحفاظ على الطريقة والجسم — لذا تستمر عمليات الدمج القائمة في العمل. حدّث عنوان URL الأساسي عندما تتمكن من ذلك لتفادي القفزة الإضافية.

المصادقة

يحتاج كل طلب إلى مفتاح API في رأسAuthorization :

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

المفاتيح محددة بنطاق المؤسسة — فهي تعمل على مؤسسة واحدة Flowella وترث أذونات المسؤول في تلك المؤسسة.

تعامل مع المفاتيح ككلمات مرور. لا تقم أبدًا بإدراجها في التحكم في المصدر، ولا تلصقها أبدًا في الدردشة أو المستندات المشتركة، وقم بتغييرها عندما يغادر زملاء الفريق المؤسسة. انظر الإعدادات → مفاتيح API لمعرفة خطوات التغيير.

إنشاء مفتاح

تحتاج إلى دور المالك أو المسؤول لإدارة مفاتيح API.

انتقل إلى الإعدادات → مفاتيح API في تطبيق Flowella .
انقر على إنشاء مفتاح وأعطه اسمًا يسهل تذكره.
انسخ المفتاح مرة واحدة — فهو يظهر فقط عند إنشائه.

تعامل مع المفاتيح ككلمات المرور: لا تقم أبدًا بإدراجها في نظام التحكم في المصادر، ولا تلصقها أبدًا في الدردشة، وقم بتدويرها عندما يغادر زملاء الفريق المنظمة.

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

اضغط على نقطة نهاية ping لتأكيد صحة المفتاح:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

يعني الرد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 ”. عند وجود رأس الاستجابة Retry-After، فإنه يخبرك بعدد الثواني التي يجب انتظارها. تراجع وحاول مرة أخرى مع تأخير أسي. إذا كنت تقوم بإرسال كميات كبيرة، فافضل **POST /v1/templates/send ** مع المعلمة “throttlePerHour ” — حيث يفرض “Flowella ” التقييد من جانب الخادم، لذا لا تحتاج إلى تنظيم الطلبات بنفسك.

مفاتيح idempotency

عمليات الإرسال الجماعي للقوالب غير متزامنة. تتحقق POST /v1/templates/send من صحة الطلب، وتضعه في قائمة انتظار دائمة، وتعيد 202 Accepted فورًا:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

يقوم Flowella بتسليم الدفعة في الخلفية ويعيد المحاولة تلقائيًا عند حدوث أخطاء WhatsApp المؤقتة. تتم معالجة المستلمين بشكل فردي، لذا لا يمنع رقم واحد غير صالح بقية الدفعة. تابع تقدم التسليم في علامة التبويب الإحصائيات الخاصة بالقالب في التطبيق. نظرًا لأن التسليم يحدث بعد الاستجابة، يجب أن تكون إعادة المحاولات آمنة. مرر رأس Idempotency-Key (حتى 200 حرف) يحدد كل دفعة بشكل فريد:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

يؤدي تكرار المفتاح نفسه خلال سبعة أيام إلى إرجاع id المهمة الأصلية بدلاً من إنشاء إرسال جديد. يمكنك إعادة محاولة الطلب بأمان بعد انتهاء المهلة أو حدوث خطأ في الشبكة دون مراسلة أي شخص مرتين. إذا حذفت الرأس، فسيشتق Flowella مفتاحًا من نص الطلب. وبالتالي، فإن الدفعة المتطابقة المُرسلة مرتين في تتابع سريع لا يتم إرسالها مرتين. ومع ذلك، يظل المفتاح الصريح أكثر أمانًا، لأن أي تغيير في النص (حتى إعادة ترتيب المستلمين) ينتج مفتاحًا مشتقًا جديدًا.

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

تستخدم نقاط نهاية القائمة (/conversations ،/contacts ،/templates ) ترقيم الصفحات بالمؤشر:

مررlimit (1–100، الافتراضي 25) وcursor اختياري.
تحتوي الاستجابة علىitems ، وعندما يكون هناك المزيد من النتائج،nextCursor .
مررnextCursor مرة أخرى كمعلمةcursor لجلب الصفحة التالية.
عندما يكونnextCursor مفقودًا، فهذا يعني أنك وصلت إلى النهاية.

curl "https://api.flowella.io/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 للتفاعل مع الأحداث بدلاً من استقصاء الحالة.

البدء

سجل التغييرات

أساسيات

استخدام التطبيق

الإعدادات

إعداد Meta وWhatsApp

تكامل HubSpot

التدفقات والحملات

الحساب وتسجيل الدخول

الأمان والخصوصية

مرجع API

استكشاف الأخطاء

مقدمة واجهة برمجة التطبيقات

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

المصادقة

إنشاء مفتاح

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

الأخطاء

حدود المعدل

مفاتيح idempotency

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

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

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

القنوات

مواصفات OpenAPI

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

​المصادقة

​إنشاء مفتاح

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

​الأخطاء

​حدود المعدل

​مفاتيح idempotency

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

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

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

​القنوات

​مواصفات OpenAPI

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

المصادقة

إنشاء مفتاح

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

الأخطاء

حدود المعدل

مفاتيح idempotency

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

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

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

القنوات

مواصفات OpenAPI