> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> المصادقة، وعنوان URL الأساسي، ورموز الأخطاء، وترقيم الصفحات، وحدود المعدل، ومفاتيح idempotency لواجهة Flowella REST API v1 — كل ما تحتاجه قبل أول استدعاء.

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

توجد مرجع نقاط النهاية الكامل في الشريط الجانبي **مرجع واجهة برمجة التطبيقات** (يتم إنشاؤه تلقائيًا من [مواصفات OpenAPI
](/api-reference/openapi.json)).

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

```
https://app.flowella.io
```

توجد جميع نقاط النهاية v1 تحت`/api/v1`
.

## المصادقة

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

```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```

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

<Warning>
  تعامل مع المفاتيح ككلمات مرور. لا تقم أبدًا بإدراجها في التحكم في المصدر، ولا تلصقها أبدًا في الدردشة أو المستندات المشتركة، وقم بتغييرها عندما يغادر زملاء الفريق المؤسسة. انظر [الإعدادات → مفاتيح API](/ar/settings/api-keys) لمعرفة خطوات التغيير.
</Warning>

### إنشاء مفتاح

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

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

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

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

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.flowella.io/api/v1/ping \
    -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

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

  ```python Python theme={null}
  import os, requests

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

يعني الرد`200 OK`
مع`{ "ok": true, "organizationId": "…" }`
أنك قد تمت مصادقتك.

## الأخطاء

تظهر جميع الأخطاء في غلاف ثابت:

```json theme={null}
{
  "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`
  مفقودًا، فهذا يعني أنك وصلت إلى النهاية.

```bash theme={null}
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 الكامل وتبديل القنوات، انظر [القنوات المتعددة](/ar/essentials/multi-channel).

## مواصفات OpenAPI

توجد المواصفات القابلة للقراءة آليًا على:

```
/api-reference/openapi.json
```

قم بإدراجها في Postman أو Insomnia أو منشئ الكود الذي تختاره.

<Tip>
  هل تقوم بإنشاء تكامل؟ اربط هذه الصفحة بـ [Webhooks](/ar/api-reference/webhooks) للتفاعل مع الأحداث بدلاً من استقصاء الحالة.
</Tip>