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

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

كيف يعمل

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

قبل أن تبدأ

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

تسجيل تطبيق

افتح Developer apps

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

ابدأ تطبيقًا جديدًا

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

سمِّ التطبيق

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

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

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

اختر النطاقات

ضمن Scopes، تكون نطاقات القراءة محددة مسبقًا. حدّد أي نطاق آخر يحتاجه تطبيقك وألغِ تحديد النطاقات التي لا يحتاجها. هذه هي أقصى النطاقات التي يمكن لتطبيقك طلبها. راجع النطاقات.

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

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

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

لا يمكنك تغيير اسم التطبيق أو عناوين إعادة التوجيه أو النطاقات بعد إنشائه. لتغييرها، سجّل تطبيقًا جديدًا. تعرض قائمة Developer apps لكل تطبيق Name وClient ID (يبدأ بـ floa_) وRedirect URIs وتاريخ Created، مع زر Delete ضمن Actions.

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

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

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 أو عندما يكون أحد النطاقات غير مسموح به.

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

إذا لم يكن الشخص مسجّل الدخول، يطلب منه Flowella تسجيل الدخول أولًا.
يجب أن يكون الشخص Owner أو Admin في المؤسسة. يرى أي شخص آخر الخطأ Owner or admin role required to authorize apps.
تعرض شاشة Authorize app قيمة Client ID: الخاصة بك وRequested scopes:. إذا لم يرسل تطبيقك scope، تعرض This app will receive its default allowed scopes.
يختار الشخص 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.

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"

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

{
  "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:

Authorization: Bearer fla_xxxxxxxxxxxxxxxx

لا يعمل الرمز إلا مع المؤسسة التي وافقت عليه، وللنطاقات التي مُنحت له فقط. يُرجع الطلب خارج تلك النطاقات 403 INSUFFICIENT_SCOPE. لكل رمز وصول حد معدل خاص به. راجع مقدمة API.

يقبل 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.

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

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

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

لا يؤدي إلغاء وصول تطبيقك الخاص في مؤسستك إلى إيقاف منحة بيانات اعتماد العميل: إذ يمكن للتطبيق طلب رمز جديد، مما يعيد تفعيل التثبيت. لقطع وصول تطبيقك الخاص بالكامل، احذفه ضمن 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 إدارة التطبيق لك. لا يمكن تغيير الأدوار في التطبيق: راجع تغيير دور شخص ما.

عدم تطابق عنوان إعادة التوجيه

يجب أن يطابق 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

المصادقة والنطاقات وحدود المعدل والأخطاء.

مركز المطورين

طلبات API الأخيرة وأدلة البدء السريع وبيئة API التجريبية.

مفاتيح API

وصول أبسط لبرامجك النصية وتكاملاتك الخاصة.

مرجع Webhooks

استجب للأحداث في المؤسسات التي تثبّت تطبيقك.

البدء

أساسيات

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

الإعدادات

إعداد Meta وWhatsApp

تكامل HubSpot

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

مرجع API

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

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

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

كيف يعمل

قبل أن تبدأ

تسجيل تطبيق

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

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

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

استدعاء API

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

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

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

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

حذف تطبيق

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

ذات صلة

مقدمة API

مركز المطورين

مفاتيح API

مرجع Webhooks

​كيف يعمل

​قبل أن تبدأ

​تسجيل تطبيق

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

​ما يراه العميل

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

​استدعاء API

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

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

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

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

​حذف تطبيق

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

​ذات صلة

مقدمة API

مركز المطورين

مفاتيح API

مرجع Webhooks

كيف يعمل

قبل أن تبدأ

تسجيل تطبيق

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

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

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

استدعاء API

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

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

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

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

حذف تطبيق

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

ذات صلة