Flowella REST API: المصادقة والنطاقات والحدود والأخطاء

تتيح لك Flowella REST API إرسال رسائل WhatsApp، وإدارة جهات الاتصال وحالات إلغاء الاشتراك، والعمل مع القوالب وFlows، وقراءة التحليلات من خلال الكود الخاص بك. تغطي هذه الصفحة ما تحتاج إلى معرفته قبل استدعاء أي نقطة نهاية. يوثّق قسم Endpoints في مرجع API هذا الطلبات الفردية. للحصول على القائمة الكاملة والمحدّثة، استخدم مستند OpenAPI المباشر أو وثائق API التفاعلية في التطبيق.

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

https://api.flowella.io/v1

توجد كل نقاط النهاية تحت هذا الأساس، مثل https://api.flowella.io/v1/messages. استخدمه حتى عندما يعرض التطبيق عنوانًا ينتهي بـ /api/v1، مثل API base URL في Developer hub.

الطلبات المرسلة إلى مضيف التطبيق، https://app.flowella.io/api/v1/...، يُعاد توجيهها بشكل دائم (308) إلى https://api.flowella.io/v1/.... تُسقط كثير من عملاء HTTP رأس Authorization عند اتباع إعادة توجيه إلى مضيف آخر، لذا قد يفشل الطلب المعاد توجيهه برمز 401. استدعِ https://api.flowella.io/v1 مباشرة.

المصادقة

أرسل رمز Bearer في رأس Authorization لكل طلب:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

يقبل Flowella نوعين من الرموز. وكلاهما يعمل على مؤسسة واحدة فقط.

الرمز	يبدأ بـ	مصدره	النطاقات	انتهاء الصلاحية
مفتاح API	`flo_`	Settings → API keys، ينشئه مالك (Owner) أو مسؤول (Admin). راجع مفاتيح API.	كل النطاقات	لا ينتهي. يعمل حتى يُلغى.
رمز وصول OAuth	`fla_`	تطبيق OAuth مسجّل تحت Settings → Developer apps. راجع تسجيل تطبيق شريك باستخدام OAuth.	النطاقات الممنوحة عند تفويض التطبيق فقط	ساعة واحدة. اطلب رمزًا جديدًا عند انتهاء صلاحيته.

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

تعامل مع المفاتيح والرموز كما تتعامل مع كلمات المرور. لا تضفها أبدًا إلى نظام التحكم في المصدر ولا تلصقها في المحادثات أو المستندات المشتركة. ألغِ أي مفتاح لم تعد تحتاجه في مفاتيح API.

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

استدعِ نقطة النهاية ping للتأكد من أن المفتاح أو الرمز يعمل:

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

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

import os
import requests

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

تعني الاستجابة 200 OK أنك مصادَق عليك. organizationId هو المعرّف الرقمي لمؤسستك:

{
  "ok": true,
  "organizationId": 4821
}

تحمل الاستجابة 401 الرمز UNAUTHORIZED وإحدى هذه الرسائل: Missing bearer token أو Invalid or expired API key أو Invalid or expired access token أو Unsupported bearer token.

النطاقات

تحتاج كل نقطة نهاية إلى نطاق. تملك مفاتيح API المنشأة في التطبيق كل النطاقات. أما رموز وصول OAuth فلا تملك إلا النطاقات الممنوحة عند التفويض.

النطاق	يسمح بـ
`messages:read`	قراءة الرسائل.
`messages:write`	إرسال الرسائل باستخدام `POST /v1/messages`.
`contacts:read`	قراءة جهات الاتصال وحالات إلغاء الاشتراك.
`contacts:write`	إنشاء جهات الاتصال وتحديثها وحذفها، والإدراج أو التحديث الجماعي، وتسجيل حالات إلغاء الاشتراك.
`conversations:read`	قراءة المحادثات وقنوات WhatsApp.
`conversations:write`	تحديث المحادثات وإغلاقها وإعادة فتحها.
`templates:read`	قراءة القوالب وحالة الموافقة عليها.
`templates:write`	إنشاء القوالب وتعديلها وتقديمها وحذفها، والإرسال التجريبي، والإرسال الجماعي باستخدام `POST /v1/templates/send`.
`webhooks:manage`	إدارة Webhooks وعمليات التسليم وإعادة التشغيل وأسرار التوقيع.
`analytics:read`	قراءة التحليلات والاستخدام.
`account:read`	قراءة الإمكانات وحالة التكامل وتفاصيل الطلبات.
`flows:read`	قراءة Flows وحالة مزامنتها.
`flows:write`	إنشاء Flows وتعديلها ونشرها وحذفها، وإعداد مزوّدي النماذج.
`forms:ingest`	إرسال عمليات إرسال النماذج وقراءتها، بما في ذلك Webhooks النماذج الواردة.
`events:read`	قراءة موجز الأحداث باستخدام `GET /v1/events`.
`jobs:read`	قراءة المهام الخلفية ونتائجها.
`jobs:write`	إلغاء المهام الخلفية.
`sandbox:manage`	قراءة إعداد بيئة الاختبار وتغييره، واستخدام أدوات اختبار بيئة الاختبار.

لا تحتاج GET /v1/ping وGET /v1/rate-limits إلى أي نطاق. وتسرد GET /v1/capabilities (النطاق account:read) النطاقات التي يملكها رمزك. يُرجع الطلب الذي يفتقر إلى النطاق المطلوب 403 مع الرمز INSUFFICIENT_SCOPE. ويسرد details.required النطاقات الناقصة:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token is missing required scope(s)",
    "requestId": "req_5b1e0c2a-8f3d-4e6a-9c7b-2d4f6a8e0b1c",
    "details": { "required": ["webhooks:manage"] }
  }
}

الأخطاء

تستخدم الأخطاء الغلاف نفسه. يحدد requestId الطلب عند التواصل مع الدعم، ويحتوي details على معلومات إضافية، مثل مشكلات التحقق، عند وجودها:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

حالة HTTP	`error.code`	متى تظهر
`400`	`BAD_REQUEST`	فشل الطلب في التحقق، أو أن `API-Version` غير مدعوم، أو أن طول `Idempotency-Key` غير صحيح.
`400`	`META_ERROR`	رفضت Meta الطلب.
`400`	`INVALID_TEMPLATE_NAME`، `INVALID_TEMPLATE_COMPONENTS`	اسم القالب أو مكوناته غير صالحة.
`401`	`UNAUTHORIZED`	رمز Bearer مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.
`402`	`PAYMENT_REQUIRED`	دفعة اشتراكك متأخرة.
`403`	`INSUFFICIENT_SCOPE`	لا يملك رمزك نطاقًا تحتاجه نقطة النهاية.
`403`	`FORBIDDEN`	الإجراء غير مسموح، مثل الإرسال إلى جهة اتصال ألغت اشتراكها على ذلك الرقم، أو أن اشتراكك غير نشط.
`404`	`NOT_FOUND`	المورد غير موجود في مؤسستك.
`409`	`CONFLICT`، `IDEMPOTENCY_KEY_CONFLICT`، `IDEMPOTENCY_KEY_IN_FLIGHT`	قيمة مكررة مثل `externalId`، أو تعارض في مفتاح منع التكرار.
`429`	`RATE_LIMITED`	أرسلت عددًا كبيرًا جدًا من الطلبات. راجع حدود المعدل.
`500`	`INTERNAL_ERROR`، `INTERNAL_SERVER_ERROR`	حدث خطأ من جانب Flowella. أعد المحاولة لاحقًا واذكر `requestId` للدعم.

قيمة error.code ثابتة، لذا يمكن لكودك الاعتماد عليها. أما نص error.message فموجّه للأشخاص وقد يتغير.

حدود المعدل

لكل مفتاح API ولكل رمز وصول OAuth حد خاص به لعدد الطلبات في الدقيقة. يحتسب Flowella الطلبات في نوافذ ثابتة مدتها دقيقة واحدة تبدأ مع بداية الدقيقة (UTC). تتضمن الاستجابات للطلبات التي تجتاز فحوص المصادقة والنطاق هذه الرؤوس:

الرأس	المعنى
`X-RateLimit-Limit`	الطلبات المسموح بها في كل نافذة.
`X-RateLimit-Remaining`	الطلبات المتبقية في النافذة الحالية.
`X-RateLimit-Reset`	وقت انتهاء النافذة الحالية، بثواني Unix.

عند تجاوز الحد، يُرجع Flowella 429 مع الرمز RATE_LIMITED ورأس Retry-After يحمل عدد الثواني التي يجب انتظارها. وتُرجع GET /v1/rate-limits قيم limit وremaining وreset الخاصة بك بتنسيق JSON. لعمليات الإرسال الكبيرة، استخدم POST /v1/templates/send، التي تقبل ما يصل إلى 50,000 مستلم في طلب واحد. يقبل الطلب أيضًا حقلًا اختياريًا throttlePerHour، وهو عدد صحيح من 1 إلى 100,000، لكنه لا ينظّم وتيرة الإرسال حاليًا، لذا لا تعتمد عليه. لتوزيع عملية إرسال كبيرة على مدى زمني، قسّم قائمة المستلمين إلى دفعات أصغر وأرسل كل دفعة على حدة.

معرّفات الطلبات

تتضمن الاستجابات رأس X-Request-Id، وتكرره أجسام الأخطاء في error.requestId. الاستثناء هو POST /v1/templates/send: راجع الإرسال الجماعي للقوالب. لاستخدام معرّفك الخاص، أرسل رأس X-Request-Id بطول يصل إلى 128 حرفًا وسيعيد Flowella استخدامه. اذكر معرّف الطلب عند التواصل مع الدعم. للبحث عن طلب بنفسك، استدعِ GET /v1/requests/{requestId} (النطاق account:read): تُرجع الطلب المسجّل مع الأحداث والمهام وعمليات تسليم Webhooks المرتبطة به. يسرد Developer hub طلباتك الأخيرة ومعرّفاتها.

منع التكرار

تتيح لك مفاتيح منع التكرار (idempotency keys) إعادة محاولة طلب كتابة بعد انتهاء المهلة أو حدوث خطأ في الشبكة دون تنفيذ العمل مرتين. تتبع POST /v1/templates/send قواعدها الخاصة، الموضحة أدناه.

معظم طلبات الكتابة

تقبل طلبات POST وPATCH وPUT وDELETE رأسًا اختياريًا Idempotency-Key:

يجب أن يتكون المفتاح من 8 إلى 255 حرفًا. تُرجع الأطوال الأخرى 400.
يتذكر Flowella كل مفتاح لمؤسستك لمدة 24 ساعة.
يُرجع التكرار بالمفتاح والأسلوب والمسار والجسم نفسها الاستجابةَ المخزنة دون تنفيذ الطلب مجددًا.
يُرجع التكرار بالمفتاح نفسه مع أسلوب أو مسار أو جسم مختلف 409 IDEMPOTENCY_KEY_CONFLICT.
يُرجع التكرار المرسل بينما لا يزال الطلب الأول قيد التنفيذ 409 IDEMPOTENCY_KEY_IN_FLIGHT. انتظر ثم أعد المحاولة.
تعيد الاستجابات المفتاح في رأس Idempotency-Key.

تُنفَّذ الطلبات التي لا تتضمن الرأس بشكل طبيعي، دون أي حماية من التكرار.

الإرسال الجماعي للقوالب

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

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

يسلّم Flowella الدفعة في الخلفية ويعيد محاولة أخطاء WhatsApp المؤقتة تلقائيًا. يُعالج كل مستلم على حدة، لذا لا يعيق رقم واحد غير صالح بقية الدفعة. تابع تقدم التسليم في علامة التبويب Statistics الخاصة بالقالب في التطبيق. مرّر رأس Idempotency-Key يحدد كل دفعة:

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

تتعامل نقطة النهاية هذه مع المفاتيح بشكل مختلف عن طلبات الكتابة الأخرى:

يمكن أن يصل طول المفتاح إلى 200 حرف. يُرجع المفتاح الأطول 400.
يُرجع التكرار بالمفتاح نفسه خلال 7 أيام قيمة id الأصلية ولا يرسل شيئًا، حتى لو تغيّر الجسم.
في غياب الرأس، يستخدم Flowella تجزئة (hash) لجسم الطلب كمفتاح. إذا أرسلت جسمًا مطابقًا بايتًا ببايت مرة أخرى خلال 7 أيام، تحصل على id الأصلي ولا يُرسل شيء. استخدم مفتاحًا جديدًا لكل دفعة تنوي إرسالها.

تختلف بعض السلوكيات الأخرى أيضًا في نقطة النهاية هذه:

استدعها باستخدام مفتاح API. تُرفض رموز وصول OAuth برمز 401.
لا تتضمن استجاباتها الرؤوس X-Request-Id أو API-Version أو X-RateLimit-*. ومع ذلك تُحتسب طلباتها ضمن حد المعدل الخاص بالمفتاح.

إدارة الإصدارات

يمكنك تثبيت إصدار API باستخدام رأس API-Version:

API-Version: 2026-08-11

2026-08-11 هو الإصدار الوحيد المدعوم والإصدار الافتراضي عند حذف الرأس. أي قيمة أخرى، أو قيمة ليست تاريخًا بتنسيق YYYY-MM-DD، تُرجع 400 مع الرسالة Unsupported API-Version. تعيد الاستجابات الإصدار في الرأسين API-Version وX-Flowella-Api-Version.

بيئة الاختبار

تتيح لك بيئة الاختبار (sandbox) اختبار تكامل دون إرسال أي شيء إلى WhatsApp. وهي تعمل على مؤسستك الحقيقية: لا يوجد حساب اختبار منفصل. يمكنك استخدامها بطريقتين:

مفتاح بيئة اختبار، لا يؤثر إلا على الطلبات المرسلة بذلك المفتاح. راجع مفاتيح بيئة الاختبار.
API sandbox على مستوى المؤسسة في Developer hub، والتي يمكن لمالك أو مسؤول تفعيلها. راجع API sandbox.

أثناء تطبيق بيئة الاختبار، تخزّن POST /v1/messages الرسالة وتُرجع "sandbox": true دون التواصل مع Meta، ويُرجع تقديم القالب قرارًا وهميًا فوريًا. تحتاج أدوات اختبار بيئة الاختبار تحت /v1/test/ و/v1/sandbox إلى النطاق sandbox:manage.

الترقيم

تستخدم نقاط نهاية القوائم، مثل /v1/conversations و/v1/contacts و/v1/templates، الترقيم بالمؤشر (cursor):

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

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

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

كل الطوابع الزمنية سلاسل 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

المواصفة المباشرة القابلة للقراءة آليًا متاحة للعامة:

https://api.flowella.io/v1/openapi.json

استوردها إلى Postman أو Insomnia أو إلى مولّد كود. وهي تصف المصادقة بمفتاح API وبـ OAuth.

موارد المطورين

يتضمن التطبيق مزيدًا من المواد للمطورين. هذه الصفحات عامة، لذا يمكنك فتحها دون تسجيل الدخول:

المورد	العنوان
وثائق API تفاعلية، مع طلبات قابلة للتجربة	`https://app.flowella.io/docs`
مجموعة Postman (تنزّل ملف `.json`)	`https://app.flowella.io/docs/postman`
دليل بيئة الاختبار	`https://app.flowella.io/docs/sandbox`
أدلة بدء سريع بتنسيق Markdown لـ Salesforce وZoho CRM وSurveyMonkey وTypeform وn8n	`https://app.flowella.io/docs/quickstarts/salesforce`، مع `zoho` أو `surveymonkey` أو `typeform` أو `n8n` بدلًا من `salesforce`

يجمع Developer hub في Settings هذه الروابط مع طلبات API الأخيرة ومفتاح تبديل API sandbox.

استخدم هذه الصفحة مع مرجع Webhooks للاستجابة للأحداث بدلًا من الاستطلاع المتكرر بحثًا عن التغييرات.

البدء

أساسيات

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

الإعدادات

إعداد Meta وWhatsApp

تكامل HubSpot

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

مرجع API

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

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

Flowella REST API: المصادقة والنطاقات والحدود والأخطاء

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

المصادقة

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

النطاقات

الأخطاء

حدود المعدل

معرّفات الطلبات

منع التكرار

معظم طلبات الكتابة

الإرسال الجماعي للقوالب

إدارة الإصدارات

بيئة الاختبار

الترقيم

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

أرقام الهاتف

القنوات

مواصفة OpenAPI

موارد المطورين

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

​المصادقة

​التحقق من بيانات الاعتماد

​النطاقات

​الأخطاء

​حدود المعدل

​معرّفات الطلبات

​منع التكرار

​معظم طلبات الكتابة

​الإرسال الجماعي للقوالب

​إدارة الإصدارات

​بيئة الاختبار

​الترقيم

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

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

​القنوات

​مواصفة OpenAPI

​موارد المطورين

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

المصادقة

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

النطاقات

الأخطاء

حدود المعدل

معرّفات الطلبات

منع التكرار

معظم طلبات الكتابة

الإرسال الجماعي للقوالب

إدارة الإصدارات

بيئة الاختبار

الترقيم

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

أرقام الهاتف

القنوات

مواصفة OpenAPI

موارد المطورين