> ## 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.

# مركز المطورين: بيئة API التجريبية والطلبات الأخيرة ووثائق API

> اطّلع على طلبات Flowella API الأخيرة، وشغّل بيئة API التجريبية على مستوى المؤسسة أو أوقفها، وافتح أدلة البدء السريع ووثائق API التفاعلية وPostman وOpenAPI.

يجمع مركز المطورين كل ما تحتاجه للبناء على [Flowella REST API](https://knowledge.flowella.io/ar/api-reference/introduction.md). يعرض عنوان API، وسجلًا لطلبات API الأخيرة، ومفتاح **API sandbox** على مستوى المؤسسة، وأدلة البدء السريع، وروابط إلى وثائق API.

لفتحه، انتقل إلى **Settings**، ثم اختر **Developer hub** في مجموعة **Developer**.

## من يمكنه استخدامه

| جزء المركز | من يمكنه استخدامه |
| - | - |
| **API base URL** و**Quickstarts** و**Links** | كل شخص في المؤسسة. |
| **Recent API requests** | أصحاب دور Owner وAdmin. أما للأدوار الأخرى فلا تعرض البطاقة أي طلبات. |
| **API sandbox** | يمكن للجميع رؤية ما إذا كانت **Active** أو **Off**. لا يستطيع تشغيلها أو إيقافها إلا أصحاب دور Owner وAdmin. |
| مفاتيح API وتطبيقات المطورين التي تفتحها الروابط | أصحاب دور Owner وAdmin. راجع [مفاتيح API](https://knowledge.flowella.io/ar/settings/api-keys.md) و[تطبيقات المطورين](https://knowledge.flowella.io/ar/settings/developer-apps.md). |

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

تعرض هذه البطاقة عنوان REST API. في تكاملك، استخدم `https://api.flowella.io/v1` كعنوان أساسي، حتى لو عرضت البطاقة عنوانًا ينتهي بـ `/api/v1`. راجع [عنوان URL الأساسي](https://knowledge.flowella.io/ar/api-reference/introduction.md#عنوان-url-الأساسي) لمعرفة السبب.

## طلبات API الأخيرة

تسرد هذه البطاقة أحدث 25 طلب API أُجريت على مؤسستك باستخدام مفاتيح API أو رموز وصول OAuth، بدءًا من الأحدث.

| العمود | ما يعرضه |
| - | - |
| **Time** | وقت استلام Flowella للطلب. |
| **Method** | طريقة HTTP، على سبيل المثال `POST`. |
| **Path** | نقطة النهاية التي تم استدعاؤها. |
| **Status** | حالة HTTP التي أرجعها Flowella. |
| **Actor** | الجهة التي أجرت الاستدعاء: `key:` متبوعة بمعرّف لمفتاح API، أو `oauth:` متبوعة بمعرّف العميل لتطبيق OAuth. معرّف `key:` ليس بادئة المفتاح المعروضة في شاشة API keys. |
| **Request id** | معرّف الطلب، وهو القيمة نفسها الموجودة في ترويسة الاستجابة `X-Request-Id`. |

لا تُدرج الطلبات التي يرفضها Flowella قبل تشغيلها. ومنها الطلبات التي تحتوي على رمز مفقود أو غير صالح، أو نطاق مفقود، أو ترويسة `API-Version` غير مدعومة، أو التي تتجاوز حد المعدل.

لرؤية كل ما يرتبط بطلب ما، مثل الأحداث والمهام وعمليات تسليم webhook التي تسبب فيها، استدعِ `GET /v1/requests/{requestId}` باستخدام **Request id**. يحتاج ذلك إلى النطاق `account:read`. راجع [معرّفات الطلبات](https://knowledge.flowella.io/ar/api-reference/introduction.md#معرّفات-الطلبات).

## بيئة API التجريبية

تحتوي بطاقة **API sandbox** على مفتاح على مستوى المؤسسة للاختبار دون إرسال أي شيء إلى WhatsApp. تعرض الشارة **Active** عندما تكون البيئة التجريبية مفعّلة و**Off** عندما تكون متوقفة. يفتح **Sandbox guide** دليل البيئة التجريبية في التطبيق.

لتشغيل البيئة التجريبية، يحدد صاحب دور Owner أو Admin مربع الاختيار في أسفل البطاقة. ألغِ تحديده لإيقاف البيئة التجريبية. يُطبَّق التغيير فورًا على المؤسسة بأكملها. يمكنك أيضًا قراءة الإعداد وتغييره باستخدام `GET /v1/sandbox` و`PATCH /v1/sandbox`، مع نص الطلب `{ "enabled": true }` أو `{ "enabled": false }`. يحتاج كلاهما إلى النطاق `sandbox:manage`.

> [!WARNING]
>
> تؤثر بيئة API التجريبية في أكثر من استدعاءات API. فأثناء تشغيلها، يتوقف أيضًا [Bulk send](https://knowledge.flowella.io/ar/app/bulk-send.md) في التطبيق وإجراء **Send WhatsApp Template** في مسارات عمل HubSpot عن الوصول إلى جهات الاتصال. أما الردود من Inbox وإجراءا HubSpot **Send WhatsApp Message** و**Send WhatsApp Reply** فتُرسل فعليًا. أوقف البيئة التجريبية بمجرد انتهائك من الاختبار.

### بيئة API التجريبية ومفاتيح sandbox

هناك طريقتان لاستخدام البيئة التجريبية. تغطي **API sandbox** على مستوى المؤسسة كل طلب، بينما يغطي [مفتاح sandbox](https://knowledge.flowella.io/ar/settings/api-keys.md#مفاتيح-sandbox) الطلبات المُجراة بذلك المفتاح فقط.

| | **API sandbox** على مستوى المؤسسة | **Sandbox key** |
| - | - | - |
| كيفية تشغيلها | يحدد صاحب دور Owner أو Admin المفتاح هنا، أو يستدعي `PATCH /v1/sandbox`. | حدّد **Sandbox key** عند إنشاء مفتاح API. |
| الطلبات التي تغطيها | جميع طلبات API في المؤسسة، من أي مفتاح API أو تطبيق OAuth. | الطلبات المُجراة بذلك المفتاح فقط. |
| `POST /v1/messages` | تُخزَّن في Flowella ولا تُرسل. | تُخزَّن في Flowella ولا تُرسل. |
| إرسال القالب للمراجعة | قرار وهمي فوري. | قرار وهمي فوري. |
| عمليات الإرسال التجريبية للقوالب | يتم تخطيها. | يتم تخطيها. |
| `POST /v1/templates/send` | يُسجَّل المستلمون على أنهم مكتملون، ولا يُرسل شيء. | تُرسل فعليًا. |
| **Bulk send** في التطبيق وإجراء HubSpot **Send WhatsApp Template** | يُسجَّل المستلمون على أنهم مكتملون، ولا يُرسل شيء. | لا تتأثر. |

### ما الذي يتغير في البيئة التجريبية

عندما تغطي البيئة التجريبية طلبًا ما:

* يخزّن `POST /v1/messages` الرسالة في المحادثة ويُرجع `"sandbox": true` مع تعيين `metaMessageId` على `null`. لا يصل أي شيء إلى WhatsApp، ولا يُطلق webhook `message.sent`.
* لا يصل إرسال القالب عبر `POST /v1/templates/{id}/submit` إلى Meta. بل يعتمد القالب فورًا، أو يرفضه إذا كان اسم القالب يحتوي على `reject_`. تُرفض ترويسة الوسائط التي تكون عينتها مجرد عنوان ويب مع `400 INVALID_TEMPLATE_COMPONENTS`. يظهر القرار في API وفي موجز الأحداث، لكن صفحة **Templates** في التطبيق لا تتغير.
* تعمل البيئة التجريبية في مؤسستك الحقيقية. تُخزَّن جهات الاتصال والمحادثات والرسائل المُنشأة أثناء الاختبارات مثل أي بيانات أخرى وتظهر في التطبيق.

### أدوات الاختبار في البيئة التجريبية

تساعدك نقاط النهاية هذه على محاكاة النشاط. تحتاج إلى النطاق `sandbox:manage`، وتعمل سواء كانت البيئة التجريبية مفعّلة أم لا، لذا لا تستخدمها إلا مع بيانات الاختبار.

| الطريقة | المسار | ما تفعله |
| - | - | - |
| `GET` | `/v1/sandbox/status` | تُرجع ما إذا كانت بيئة API التجريبية مفعّلة، وقيمة `sandboxKey` التي توضح ما إذا كان مفتاحك مفتاح sandbox. |
| `POST` | `/v1/test/contacts` | تنشئ جهة اتصال أو تحدّثها من `phone` وقيمتي `name` و`email` الاختياريتين. |
| `POST` | `/v1/test/messages/{id}/simulate-status` | تضيف حدث `message.sent` أو `message.delivered` أو `message.read` أو `message.failed` أو `message.accepted` لرسالة ما إلى موجز الأحداث. أرسل `status` دون البادئة `message.`. |
| `POST` | `/v1/test/webhooks/replay-event` | تضيف حدثًا من `type` الذي تختاره إلى موجز الأحداث. |
| `POST` | `/v1/sandbox/fixtures/reset` | تمسح أحداث البيئة التجريبية ومهامها وقرارات القوالب الوهمية. ويفعل `POST /v1/test/reset` الشيء نفسه. |

لا تكتب أدوات الاختبار إلا في موجز الأحداث (`GET /v1/events`). ولا ترسل webhooks ولا تغيّر الرسالة نفسها.

## أدلة البدء السريع

ترتبط بطاقة **Quickstarts** بأدلة خطوة بخطوة. يُفتح كل منها كملف Markdown في علامة تبويب جديدة.

| دليل البدء السريع | ما يغطيه |
| - | - |
| Salesforce | التثبيت عبر OAuth، وإرسال القوالب، واستقبال النماذج. |
| Zoho CRM | الإدراج أو التحديث المجمّع لجهات الاتصال وwebhooks الصادرة. |
| SurveyMonkey | ربط تفاصيل الاستبيانات وwebhooks الواردة. |
| Typeform | مسارات موفّر Typeform وwebhooks الواردة. |
| n8n | عُقد HTTP Request التي تستدعي API. |

## الروابط

| الرابط | ما يفتحه |
| - | - |
| **Interactive API docs** | مرجع API في التطبيق، مع مخططات الطلبات وأمثلة قابلة للتجربة. الصق مفتاح API لإرسال طلبات تجريبية. |
| **Manage API keys** | [مفاتيح API](https://knowledge.flowella.io/ar/settings/api-keys.md)، حيث تنشئ المفاتيح وتلغيها. |
| **Developer apps** | [تطبيقات المطورين](https://knowledge.flowella.io/ar/settings/developer-apps.md)، حيث تسجّل تطبيقات OAuth. |
| **OpenAPI JSON** | مستند OpenAPI الخاص بـ API، والذي يمكنك استيراده إلى Postman أو Insomnia أو مولّد شيفرة. |
| **Postman collection** | ينزّل `flowella-v1.postman_collection.json`. |
| **Capabilities matrix (authenticated)** | `GET /v1/capabilities`، الذي يسرد نطاقات رمزك، وما إذا كانت البيئة التجريبية مفعّلة، وأنواع الرسائل وفئات القوالب المدعومة. يحتاج إلى مفتاح API بالنطاق `account:read`، لذا تعرض علامة تبويب المتصفح خطأ مصادقة. استدعه من عميل API الخاص بك بدلًا من ذلك. |

## ذات صلة

> **[مقدمة API](https://knowledge.flowella.io/ar/api-reference/introduction.md)**
>
> المصادقة والنطاقات وحدود المعدل والأخطاء.

> **[مفاتيح API](https://knowledge.flowella.io/ar/settings/api-keys.md)**
>
> أنشئ مفاتيح حية ومفاتيح sandbox.

> **[تطبيقات المطورين](https://knowledge.flowella.io/ar/settings/developer-apps.md)**
>
> سجّل تطبيق OAuth وأدِر التطبيقات المثبتة.

> **[مرجع Webhooks](https://knowledge.flowella.io/ar/api-reference/webhooks.md)**
>
> أنواع الأحداث والحمولات والتحقق من التوقيعات.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.