تخطَّ إلى المحتوى

تطبيقات OAuth

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

ورمز OAuth يصل إلى العمليات نفسها تمامًا التي يصل إليها مفتاح API، وصفحة نظرة عامة على API تشرح العنوان الأساسي والحدود وأشكال الأخطاء المشتركة بينهما.

  1. يضغط أحد مستخدمي منتجك زر «ربط شارك» عندك.
  2. ترسله إلى شاشة التصريح في شارك بمعرف عميلك.
  3. يعرض شارك شاشة تصريح تسمي تطبيقك، فيوافق أو يرفض.
  4. يعيده شارك إلى رابط إعادة التوجيه عندك ومعه code قصير العمر.
  5. يبادل خادمك رمز التفويض ذلك برمز وصول.
  6. تستدعي API برمز الوصول.

الخطوتان 2 و4 تجريان في متصفحه. والخطوة 5 تجري على خادمك، لأنها تحتاج السر الخاص بعميلك.

يمكن لكل مؤسسة أن تملك تطبيق OAuth واحدًا، وإدارته تتطلب دور مشرف أو مشرف عام في حساب يتيح الوصول إلى API. ومن يفتح تبويب التطبيقات غير هؤلاء لا يرى إلا التطبيقات المصرح لها.

  1. افتح شارك، واذهب إلى الإعدادات، ثم تبويب التطبيقات.

  2. أنشئ تطبيقًا. تقدم اسم التطبيق (يظهر على شاشة التصريح)، والوصف وصورة الملف الشخصي اختياريًا، ورابط إعادة التوجيه الذي يعيد شارك الناس إليه بعد أن يقرروا.

  3. يصدر شارك معرف العميل مسبوقًا بـ pca_ والسر الخاص بالعميل مسبوقًا بـ pcs_.

أعد توجيههم إلى شاشة التصريح في شارك:

https://dash.sharek.app/oauth/authorize?client_id=pca_your_client_id&response_type=code&state=random-string
المعامل مطلوب الوصف
client_id نعم معرف العميل الخاص بتطبيقك.
response_type نعم يجب أن يكون code.
state لا نص عشوائي تولده لكل محاولة. وينصح به بشدة: فهو ما تكشف به استدعاءً مزورًا.

يرون اسم تطبيقك ووصفه وصورته، ويختارون تصريح أو رفض.

يعيدهم شارك إلى رابط إعادة التوجيه المسجل عندك.

عند الموافقة:

https://your-app.example/callback?code=the-code&state=random-string

عند الرفض:

https://your-app.example/callback?error=access_denied&state=random-string

قارن state العائد بالذي أنشأته قبل أن تفعل أي شيء آخر. فإن لم يتطابق، فتجاهل الطلب.

من جهة الخادم، لأن هذا الاستدعاء يحمل سرك:

Terminal window
curl -X POST https://dash.sharek.app/api/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "the-code-from-the-callback",
"client_id": "pca_your_client_id",
"client_secret": "pcs_your_client_secret"
}'
الحقل مطلوب الوصف
grant_type نعم يجب أن يكون authorization_code.
code نعم رمز التفويض الآتي من الاستدعاء الراجع.
client_id نعم معرف العميل الخاص بتطبيقك.
client_secret نعم السر الخاص بعميل تطبيقك.

ويمكنك إرسال client_id وclient_secret في ترويسة Authorization: Basic بدلًا من ذلك، بترميز base64 لـ client_id:client_secret، ثم حذفهما من جسم الطلب.

والتبادل الناجح يجيب بـ 200:

{
"id": "organization-id",
"cus": "billing-customer-id",
"access_token": "pos_your_oauth_token",
"token_type": "bearer",
"scope": "mcp:read mcp:write"
}
الحقل الوصف
id المؤسسة التي يتصرف رمز الوصول نيابةً عنها. احفظه بجانب رمز الوصول.
cus معرف عميل الفوترة لتلك المؤسسة.
access_token رمز الوصول، مسبوقًا بـ pos_.
token_type دائمًا bearer.
scope دائمًا mcp:read mcp:write للتطبيق الذي تسجله. وهو للعلم فقط: فرمز الوصول يصل إلى كل عملية في واجهة API العامة أيًا كان ما يقوله.

الترويسة نفسها كمفتاح API، وما زالت بلا بادئة Bearer رغم أن token_type يقول bearer:

Terminal window
curl -H "Authorization: pos_your_oauth_token" \
https://dash.sharek.app/api/public/v1/integrations

وأول استدعاء مناسب هو جلب الحساب الحالي: فهو يسمي الشخص الذي وافق على تطبيقك ومؤسسته، لتعرض من المتصل.

ورموز الوصول لا تنتهي بمؤقت. بل تتوقف عن العمل حين يسحب الشخص تطبيقك، أو حين تحذفه أنت.

تدوير السر إن تسرب. فالسر القديم يتوقف عن العمل فورًا. ورموز الوصول القائمة تبقى تعمل، لأن السر لا يستخدمه إلا تبادل الرموز.

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

الخطأ متى الحالة المعنى
access_denied في الاستدعاء الراجع لا يوجد اختار رفض. وليس خطأً يستدعي إعادة المحاولة.
invalid_client تبادل الرموز 401 معرف العميل أو السر خاطئ أو مفقود.
invalid_grant تبادل الرموز 400 رمز التفويض مجهول، أو استخدم من قبل، أو يخص تطبيقًا آخر.
invalid_grant مع error_description: "Code has expired" تبادل الرموز 400 مضى أكثر من 10 دقائق. أعد بدء التدفق.
unsupported_grant_type تبادل الرموز 400 grant_type لم يكن authorization_code.