وثائق Amargi Hub

نظرة عامّة

Amargi Hub هي طبقة الهويّة الموحَّدة + المُشغِّل لعائلة منتجات Amargi. كلّ منتج (Reach، Agents، Escalate، Mail، Meet، Remote) يستخدم Hub لـ:

• مصادقة المستخدمين (البريد الإلكترونيّ + كلمة المرور، اختياري 2FA).
• إصدار رموز JWT يستهلكها كلّ منتج.
• إدارة عضويّة المؤسسات والأدوار.
• توفير المُشغِّل الذي يفتح كلّ منتج بنقرة واحدة.

يُخزِّن Hub فقط بيانات الهويّة (البريد، تجزئة كلمة المرور، 2FA، الجلسات، عضويّة المؤسسة). لا يُخزِّن أيّ بيانات منتج (رسائل WhatsApp، تذاكر، تشغيلات وكلاء — كلّ ذلك يعيش في قاعدة بيانات المنتج الخاصّة به مع عزل المستأجر المطبَّق).

بدء سريع

1. سجِّل في signin.amargicreative.com. تحقّق من بريدك الإلكترونيّ.
2. أنشئ مساحة عمل (يُنشأ تلقائياً عند التسجيل الأوّل، اختر اسم العمل).
3. ادعُ زملاء الفريق من Settings → Team. كلّ زميل يحصل على رابط دعوة مباشر.
4. افتح المُشغِّل في app.amargicreative.com للوصول إلى منتجاتك المتّصلة.
5. فعِّل 2FA من Settings → Security. مطلوب للحسابات التي تستخدم منتجات Meta (Reach، Escalate).

مفاهيم رئيسيّة

المستخدم، مساحة العمل، المؤسسة

المستخدم (User) هو حساب فرديّ، مُحدَّد بالبريد الإلكترونيّ. المؤسسة (Organization) هي الكيان القانونيّ / الإدارة، عادة شركتك. مساحة العمل (Workspace) هي حاوية تشغيليّة داخل المؤسسة، معظم العملاء لديهم مساحة عمل واحدة لكلّ مؤسسة، الفِرَق الكبيرة قد تستخدم العديد منها (لكلّ فرع، علامة تجاريّة، إلخ.). الموارد (WABAs، الوكلاء، التذاكر) تنتمي إلى مساحة عمل، ليس مباشرة إلى مؤسسة.

الأدوار

• Owner — تحكّم كامل (الفوترة، تعليق، حذف).
• Admin — إعدادات المنتج، إدارة الفريق، لا فوترة.
• Member — مستخدم تشغيليّ يوميّ (إرسال الرسائل، فتح التذاكر).
• Viewer — وصول للقراءة فقط، مفيد للمراجعين الخارجيّين.

الأدوار على مستوى مساحة العمل — يمكن أن يكون نفس المستخدم Admin في مساحة عمل واحدة وViewer في أخرى. الأدوار الخاصّة بالمنتج (مثل "وكيل Reach يستطيع الإرسال") موجودة لكلّ منتج، اقرأ وثائق المنتج لكلّ منها.

JWT و JWKS

Hub يُصدر JWT يُوقَّع بـ RS256. المفتاح العامّ مُتاح في نقطة نهاية JWKS قياسيّة على https://signin.amargicreative.com/.well-known/jwks.json. يجب أن تتحقّق كلّ منتجات Amargi (وأيّ تكامل خارجيّ تكتبه) من توقيع الرموز ضدّ JWKS قبل قبول الطلب. مُطالبات JWT تشمل:

• sub — معرّف المستخدم (UUID).
• org — معرّف المؤسسة النشطة.
• workspace — معرّف مساحة العمل النشطة.
• role — الدور على مستوى مساحة العمل.
• iss — https://signin.amargicreative.com
• aud — amargi-platform (مشترك عبر كلّ المنتجات).

الجلسات + الكوكيز

يحتفظ Hub بكوكيين على المجال المتأصِّل .amargicreative.com بحيث تشارك كلّ المنتجات الفرعيّة الجلسة. الكوكيز:

• amargi_hub_access — JWT قصير الأمد (15 دقيقة) يُرسَل في كلّ طلب.
• amargi_hub_refresh — رمز تحديث طويل الأمد (30 يوماً) يُستخدم تلقائياً لتجديد رمز الوصول.

مهامّ شائعة

دعوة زميل فريق

1. Settings → Team → Invite
2. أدخل البريد الإلكترونيّ، اختر الدور.
3. انسخ رابط الدعوة أو اترك Hub يُرسله بالبريد.
4. الزميل يقبل، يُنشئ حساباً، ينضمّ إلى مساحة العمل تلقائياً.

إنشاء مفتاح API

1. Settings → API Keys → New Key
2. أعطِ اسماً وصفياً + اختر النطاقات (read، write).
3. انسخ الرمز فوراً، لن يُعرَض مرّة أخرى.
4. استخدمه كـ Authorization: Bearer <key> في طلبات API الخاصّة بك.

تفعيل 2FA

1. Settings → Security → Enable 2FA
2. امسح رمز QR بتطبيق المصادقة (Google Authenticator، 1Password، إلخ.).
3. احفظ رموز النسخ الاحتياطيّ في مكان آمن.
4. أكِّد بإدخال رمز TOTP حالي.

إلغاء جلسة

1. Settings → Sessions — يعرض كلّ الجلسات النشطة بـ IP والمتصفّح والآخر-رؤية.
2. اضغط "إلغاء" بجانب أيّ جلسة لا تتعرّفها.
3. تُلغى الرموز فوراً، تخرج تلك الجلسة عند الطلب التالي.

مرجع API

نقاط نهاية المصادقة العامّة (لا تحتاج JWT للوصول إليها):

• POST /api/auth/signup — إنشاء حساب جديد.
• POST /api/auth/login — تسجيل الدخول، يُعيد الكوكيز.
• POST /api/auth/logout — مسح الكوكيز + إلغاء رمز التحديث.
• POST /api/auth/refresh — تجديد رمز الوصول من رمز التحديث (يحدث تلقائياً).
• GET /.well-known/jwks.json — مفتاح JWKS العامّ للتحقّق من توقيع JWT.

نقاط نهاية API محميَّة بـ JWT (تحتاج كوكي amargi_hub_access أو رأس Authorization Bearer):

• GET /api/me — الملف الشخصيّ للمستخدم الحاليّ + عضويّات المؤسسة.
• GET /api/organizations/:id/members — قائمة أعضاء المؤسسة.
• POST /api/organizations/:id/invites — دعوة عضو.
• POST /api/api-keys — إنشاء مفتاح API جديد.

الحصول على المساعدة

• دعم البريد الإلكترونيّ: contact@amargicreative.com
• مشكلة في الفوترة أو حذف الحساب: دليل الحذف.
• موقف الخصوصيّة + التشفير: موقف الخصوصيّة.