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

# تسجيل تطبيق شريك باستخدام OAuth وإدارة التطبيقات المثبتة

> سجّل تطبيق OAuth، ووجّه العملاء عبر شاشة الموافقة في Flowella، واستبدل الرموز بالرموز المميزة، وراجع التطبيقات المثبتة في مؤسستك أو ألغِ وصولها.

يتيح تطبيق OAuth لمؤسسات Flowella الأخرى ربط منتجك بحسابها دون مشاركة مفاتيح API. توافق كل مؤسسة على تطبيقك في شاشة الموافقة ويمكنها إلغاء وصوله في أي وقت. توضح هذه الصفحة للشركاء كيفية تسجيل تطبيق واستخدام OAuth، وتوضح للعملاء كيفية مراجعة التطبيقات التي ثبّتوها وإلغاء وصولها.

لبرامجك النصية وتكاملاتك الخاصة، يكون [مفتاح API](https://knowledge.flowella.io/ar/settings/api-keys.md) أبسط.

## كيف يعمل

يدعم Flowella ثلاثة أنواع من منح OAuth: رمز التفويض مع PKCE لمؤسسات العملاء، وبيانات اعتماد العميل لمؤسستك الخاصة، ورموز التحديث. يوضح التسلسل كيف يثبّت العميل تطبيقك باستخدام منحة رمز التفويض.

```mermaid theme={null}
sequenceDiagram
    participant Admin as مسؤول العميل
    participant App as تطبيقك
    participant Flowella
    App->>Admin: إعادة التوجيه إلى عنوان التفويض في Flowella
    Admin->>Flowella: فتح عنوان التفويض
    Flowella->>Admin: عرض شاشة الموافقة
    Admin->>Flowella: اختيار Allow access
    Flowella->>App: إعادة التوجيه مع رمز
    App->>Flowella: استبدال الرمز والمُحقِّق
    Flowella->>App: رمزا الوصول والتحديث
    App->>Flowella: استدعاء API برمز الوصول
```

## قبل أن تبدأ

* تحتاج إلى دور **Owner** أو **Admin** في المؤسسة التي ستملك التطبيق. يمكن للأدوار الأخرى رؤية **Developer apps** في القائمة، لكن القائمة لا تُحمَّل لهم.
* يحتاج تطبيقك إلى عنوان رد اتصال (redirect URI) يمكنه استقبال رمز التفويض.
* يجب أن يرسل تطبيقك قيمة `state` وقيمة PKCE `code_challenge` مُنشأة باستخدام `S256` مع كل طلب تفويض.

## تسجيل تطبيق

**1. افتح Developer apps**

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

**2. ابدأ تطبيقًا جديدًا**

اختر **Create app**. يُفتح مربع الحوار **Create developer app**.

**3. سمِّ التطبيق**

في **App name**، أدخل الاسم الذي يعرف به العملاء منتجك، بحد أقصى 120 حرفًا، على سبيل المثال `Acme CRM connector`.

**4. أضف عناوين إعادة التوجيه**

في **Redirect URIs**، أدخل كل عنوان رد اتصال في سطر مستقل، بحد أقصى 20 عنوانًا. أثناء التفويض، يجب أن يطابق `redirect_uri` الذي يرسله تطبيقك أحد هذه العناوين تمامًا.

**5. اختر النطاقات**

ضمن **Scopes**، تكون نطاقات القراءة محددة مسبقًا. حدّد أي نطاق آخر يحتاجه تطبيقك وألغِ تحديد النطاقات التي لا يحتاجها. هذه هي أقصى النطاقات التي يمكن لتطبيقك طلبها. راجع [النطاقات](https://knowledge.flowella.io/ar/api-reference/introduction.md#النطاقات).

**6. أنشئ التطبيق وانسخ السر**

اختر **Create app**. يعرض مربع الحوار **Save your client secret** سر العميل، الذي يبدأ بـ `flc_`. اختر **Copy**، وخزّن السر على خادمك، ثم اختر **Done**.

> [!WARNING]
>
> يعرض Flowella سر العميل مرة واحدة فقط، ولا يمكنك إعادة تعيينه. إذا فقدته، فعليك حذف التطبيق وتسجيل تطبيق جديد، ويجب على كل مؤسسة تستخدم تطبيقك الموافقة على التطبيق الجديد.

لا يمكنك تغيير اسم التطبيق أو عناوين إعادة التوجيه أو النطاقات بعد إنشائه. لتغييرها، سجّل تطبيقًا جديدًا.

تعرض قائمة **Developer apps** لكل تطبيق **Name** و**Client ID** (يبدأ بـ `floa_`) و**Redirect URIs** وتاريخ **Created**، مع زر **Delete** ضمن **Actions**.

## توجيه العميل عبر التفويض

أرسل متصفح العميل إلى نقطة نهاية التفويض على مضيف تطبيق Flowella:

```text theme={null}
https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
```

| المعامل | مطلوب | القيمة |
| - | - | - |
| `response_type` | نعم | `code` |
| `client_id` | نعم | معرّف العميل الخاص بتطبيقك. |
| `redirect_uri` | نعم | أحد عناوين إعادة التوجيه المسجّلة للتطبيق، بشكل مطابق تمامًا. |
| `state` | نعم | قيمة عشوائية يتحقق منها تطبيقك عند عودة العميل. |
| `code_challenge` | نعم | تجزئة SHA-256 بترميز base64url لقيمة `code_verifier` عشوائية يحتفظ بها تطبيقك. |
| `code_challenge_method` | لا | `S256`، وهي الطريقة الوحيدة المدعومة والافتراضية. |
| `scope` | لا | نطاقات مفصولة بمسافات، تقع جميعها ضمن نطاقات التطبيق. بدونها، لا يحصل التطبيق إلا على نطاقات القراءة المسموح بها له. |
| `publicOrgId` | لا | رقم المؤسسة المكوّن من ستة أرقام من عنوان الويب الخاص بالعميل في Flowella. بدونه، يستخدم Flowella المؤسسة التي يعمل فيها الشخص حاليًا. |

إذا كان الطلب غير صالح، يعرض Flowella خطأ بدلًا من شاشة الموافقة ولا يعيد التوجيه. يحدث ذلك، على سبيل المثال، عندما لا يتطابق `redirect_uri` أو عندما يكون أحد النطاقات غير مسموح به.

### ما يراه العميل

1. إذا لم يكن الشخص مسجّل الدخول، يطلب منه Flowella تسجيل الدخول أولًا.
2. يجب أن يكون الشخص **Owner** أو **Admin** في المؤسسة. يرى أي شخص آخر الخطأ `Owner or admin role required to authorize apps`.
3. تعرض شاشة **Authorize app** قيمة **Client ID:** الخاصة بك و**Requested scopes:**. إذا لم يرسل تطبيقك `scope`، تعرض **This app will receive its default allowed scopes.**
4. يختار الشخص **Allow access** أو **Deny**.

يرسل **Allow access** المتصفح إلى `redirect_uri` الخاص بك مع `code` و`state` في سلسلة الاستعلام. يكون الرمز صالحًا لمدة 10 دقائق ويعمل مرة واحدة. ويرسل **Deny** المتصفح إلى `redirect_uri` الخاص بك مع `error=access_denied` و`error_description` وقيمة `state` الخاصة بك.

## استبدال الرمز بالرموز المميزة

يستبدل خادمك الرمز عند نقطة نهاية الرموز. صادق باستخدام معرّف العميل والسر، إما عبر مصادقة HTTP Basic أو بوصفهما `client_id` و`client_secret` في نص الطلب. يمكن أن يكون نص الطلب بترميز النماذج أو بتنسيق JSON.

```bash theme={null}
curl -X POST "https://app.flowella.io/api/oauth/token" \
  -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://example.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"
```

تحتوي الاستجابة على الرموز:

```json theme={null}
{
  "access_token": "fla_xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "flr_xxxxxxxxxxxxxxxx",
  "scope": "messages:read contacts:read"
}
```

| الرمز | يبدأ بـ | مدة الصلاحية |
| - | - | - |
| رمز الوصول | `fla_` | ساعة واحدة |
| رمز التحديث | `flr_` | 30 يومًا، وإلى أن يُستخدم مرة واحدة فقط |

تقبل نقطة نهاية الرموز 30 طلبًا في الدقيقة لكل معرّف عميل وعنوان IP. وفوق ذلك، تُرجع `429` مع ترويسة `Retry-After`.

## استدعاء API

أرسل رمز الوصول كـ bearer token، تمامًا مثل مفتاح API:

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

لا يعمل الرمز إلا مع المؤسسة التي وافقت عليه، وللنطاقات التي مُنحت له فقط. يُرجع الطلب خارج تلك النطاقات `403 INSUFFICIENT_SCOPE`. لكل رمز وصول حد معدل خاص به. راجع [مقدمة API](https://knowledge.flowella.io/ar/api-reference/introduction.md).

> [!NOTE]
>
> يقبل `POST /v1/templates/send` مفاتيح API فقط ويرفض رموز وصول OAuth مع `401`.

### تحديث رمز الوصول

قبل انتهاء صلاحية رمز الوصول، اطلب رمزًا جديدًا باستخدام `grant_type=refresh_token` و`refresh_token` ومصادقة العميل الخاصة بك. تحتوي الاستجابة على رمز وصول جديد ورمز تحديث جديد، ويتوقف رمز التحديث القديم عن العمل. إذا قدّم شخص ما رمز تحديث سبق استخدامه، يلغي Flowella كل رمز صادر عن ذلك التفويض، ويتعين على العميل الموافقة على تطبيقك مرة أخرى.

### الوصول إلى مؤسستك الخاصة

لاستدعاء API للمؤسسة التي تملك التطبيق، استخدم `grant_type=client_credentials` مع مصادقة العميل وقيمة `scope` اختيارية. تحصل على رمز وصول دون رمز تحديث. بعد ذلك يظهر تطبيقك ضمن **Installed apps** في مؤسستك.

### إلغاء رمز أو فحصه

| نقطة النهاية | ما تفعله |
| - | - |
| `POST https://app.flowella.io/api/oauth/revoke` | تلغي `token` الذي ترسله، مع كل رمز صادر معه. |
| `POST https://app.flowella.io/api/oauth/introspect` | تُرجع ما إذا كان `token` بحالة `active`، مع `scope` و`client_id` و`organization_id` ووقت انتهاء الصلاحية. |

تحتاج كلتا نقطتي النهاية إلى مصادقة العميل الخاصة بك. يسرد مستند الاكتشاف على `https://app.flowella.io/.well-known/oauth-authorization-server` كل نقطة نهاية وكل خيار مدعوم.

## مراجعة التطبيقات المثبتة وإلغاء وصولها

يدير العملاء التطبيقات التي وافقوا عليها ضمن **Installed apps**. تحتاج إلى دور **Owner** أو **Admin**. تعرض القائمة:

| العمود | ما يعرضه |
| - | - |
| **App** | اسم التطبيق، وأسفله معرّف العميل. |
| **Scopes** | النطاقات التي مُنحت للتطبيق. |
| **Installed** | وقت الموافقة على التطبيق لأول مرة. |
| **Actions** | **Revoke**، أو شارة **Revoked**. |

لإلغاء وصول تطبيق:

1. انتقل إلى **Settings**، ثم اختر **Installed apps** في مجموعة **Developer**.
2. اختر **Revoke** في صف التطبيق.
3. أكّد المطالبة **Revoke this install? Existing tokens stop working.**

تتوقف رموز التطبيق عن العمل فورًا، ولا يمكنه تحديثها. يبقى الصف في القائمة مع شارة **Revoked**. لمنح التطبيق الوصول مرة أخرى، يوافق عليه صاحب دور Owner أو Admin مجددًا في شاشة الموافقة.

> [!NOTE]
>
> لا يؤدي إلغاء وصول تطبيقك الخاص في مؤسستك إلى إيقاف منحة بيانات اعتماد العميل: إذ يمكن للتطبيق طلب رمز جديد، مما يعيد تفعيل التثبيت. لقطع وصول تطبيقك الخاص بالكامل، احذفه ضمن **Developer apps**.

## حذف تطبيق

في **Developer apps**، اختر **Delete** في صف التطبيق وأكّد **Delete this app and its tokens?** يزيل Flowella التطبيق، وتثبيته في كل مؤسسة وافقت عليه، وجميع رموزه. لا يمكن التراجع عن ذلك.

## استكشاف الأخطاء وإصلاحها

> **Could not load developer apps أو Could not load installed apps**
>
> لا يستطيع عرض هذه الشاشات إلا أصحاب دور Owner وAdmin. اطلب من صاحب دور Owner أو Admin إدارة التطبيق لك. لا يمكن تغيير الأدوار في التطبيق: راجع [تغيير دور شخص ما](https://knowledge.flowella.io/ar/settings/team.md#تغيير-دور-شخص-ما).

> **عدم تطابق عنوان إعادة التوجيه**
>
> يجب أن يطابق `redirect_uri` في الطلب أحد عناوين إعادة التوجيه المسجّلة للتطبيق تمامًا، بما في ذلك البروتوكول والمسار وأي شرطة مائلة في النهاية. ويجب إرسال القيمة نفسها مرة أخرى عند استبدال الرمز. لا يمكنك تعديل عناوين إعادة التوجيه لتطبيق ما، لذا سجّل تطبيقًا جديدًا إذا احتجت إلى عنوان مختلف.

> **invalid\_scope**
>
> أحد النطاقات المطلوبة مكتوب بشكل خاطئ أو ليس من نطاقات التطبيق. لا تطلب إلا النطاقات التي حددتها عند تسجيل التطبيق.

> **Owner or admin role required to authorize apps**
>
> الشخص الذي يوافق على التطبيق ليس Owner أو Admin في المؤسسة. اطلب من صاحب دور Owner أو Admin إكمال التفويض.

> **فشل استبدال الرمز**
>
> تعني الرسالتان `Authorization code expired` و`Authorization code already used` أنك تحتاج إلى بدء التفويض من جديد: تدوم الرموز 10 دقائق وتعمل مرة واحدة. وتعني `PKCE verification failed` أن `code_verifier` لا يطابق `code_challenge` الذي أرسلته.

## ذات صلة

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

> **[مركز المطورين](https://knowledge.flowella.io/ar/settings/developer-hub.md)**
>
> طلبات API الأخيرة وأدلة البدء السريع وبيئة API التجريبية.

> **[مفاتيح API](https://knowledge.flowella.io/ar/settings/api-keys.md)**
>
> وصول أبسط لبرامجك النصية وتكاملاتك الخاصة.

> **[مرجع 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.