Meduza Business API

أدِر الشركات والأعضاء والوصول إلى VPN والمسارات عبر واجهة API نفسها التي تستخدمها لوحة الشركة.

الإصدار الأول: 169 طريقة من العقد الحالي — وليس 169 من 191 متطلبًا منجزًا. تستخدم المسودة مسارات وعمليات مختلفة. المصفوفة الكاملة للإصدار الأول: خارج النطاق SSO/SCIM ونقل الملكية ونشر البرامج الثابتة على أجهزة التوجيه وتصدير الإعدادات والبيانات القانونية للفواتير. notification-channels مجرد جرد قديم: عقدها والتسليم عبر email/webhook/in_app خارج الإصدار الأول. تتوفر سبعة أنواع من التنبيهات في المراقبة والتدقيق وAPI؛ ويبقى التسليم عبر webhooks API الموقّعة المستقلة ضمن النطاق. أجهزة التوجيه والموارد حاليًا مجرد جرد؛ وbilling-profile يخزّن بيانات وصفية فقط دون ارتباط بالفواتير.

التفويض والصلاحيات

المسار الأساسي: https://api.meduzavpn.com/api/business/v1. تستخدم الواجهة جلسة المستخدم الحالية. للأتمتة، أنشئ عميل API في لوحة الشركة واحفظ السر عند إصداره.

curl -X POST https://api.meduzavpn.com/api/business/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET

curl https://api.meduzavpn.com/api/business/v1/organizations/ORGANIZATION_ID/members \
  -H "Authorization: Bearer TOKEN"

مرّر الرمز الذي حصلت عليه في Authorization: Bearer TOKEN. الرمز صالح لمدة ساعة واحدة وداخل الشركة التي أصدرت العميل فقط. يُلغى الوصول عند تعطيل العميل أو سحب صلاحيات المسؤول الذي أنشأه.

الدفع وإصدار VPN

1. أنشئ الشركة عبر POST /organizations من جلسة مستخدم.
2. احصل على عرض سعر عبر subscription/quotes: عدد خوادم VPN والمدة والعملية purchase أو renewal أو upgrade.
3. مرّر quote_id وpayment_method: stripe_card إلى subscription/checkout.
4. الاستجابة 202 تعني أن الفاتورة قيد الإعداد. اقرأ invoices حتى يظهر payment_url، ثم ادفع عبر هذا الرابط.
5. بعد أن يؤكد سجل المدفوعات الدفع يصبح الاشتراك نشطًا. أنشئ خوادم VPN باستخدام pricing_id من catalog/vpn-locations وIdempotency-Key إلزامي.

تبدأ الباقة من 5 خوادم VPN. السعر الأساسي لكل VPN: $5.99 شهريًا أو $54.99 سنويًا. خصم الباقة: 5–9 خوادم — 5%، 10–99 — 10%، من 100 — 20%. العودة إلى المتصفح بعد الدفع لا تمنح الوصول قبل التحقق من الدفع.

يحافظ التجديد على العدد والمدة. توسيع الباقة يحسب فرق السعر للمدة المتبقية. لحذف خادم نهائيًا استخدم POST /organizations/{organization_id}/vpns/{id}/retire مع confirm: true وIf-Match. يُحرَّر المكان بعد تأكيد الحذف، ولا يتغير سعر الاشتراك. يُمرَّر التعيين لموظف بالحقل member_id؛ ومن دونه يكون VPN متاحًا للشركة وفق تعيينات الوصول.

يحدّد الحقل access في PATCH /organizations/{organization_id}/vpns/{id} مع If-Match من يمكنه استخدام VPN الشركة. القيمة company تتيحه لجميع أعضاء الشركة الذين يسمح دورهم بالاتصال، وتُفرَّغ القائمتان member_ids وgroup_ids. أما restricted فتقصره على الموظفين المدرجين وأعضاء المجموعات المدرجة، والقوائم الفارغة تسحب الوصول من الجميع. يُرفض company مع قوائم غير فارغة بالرمز 422. تتضمن استجابات GET و/me/vpn-grants دائمًا data.access، بما في ذلك شبكات VPN التي أُنشئت قبل ظهور الحقل. الطلب الذي لا يحتوي access ولكنه يحتوي member_ids أو group_ids يحوّل VPN إلى restricted كما في السابق. شبكة VPN المخصصة لموظف تكون دائمًا restricted. تُسجَّل تغييرات الوضع في سجل التدقيق باسم vpn_access_changed، وعند تضييق الوصول تُلغى بيانات اعتماد الأجهزة التي فقدته.

curl -X PATCH https://api.meduzavpn.com/api/business/v1/organizations/ORGANIZATION_ID/vpns/VPN_ID \
  -H "Authorization: Bearer TOKEN" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: vpn-access-1" \
  -H "Content-Type: application/json" \
  -d '{"access":"company"}'

المسارات ومجموعات الحركة

تصف المجموعة مواقع أو شبكات، وتختار القاعدة الإجراء: VPN محددًا أو اتصالًا مباشرًا أو حظرًا. استخدم الدول والمناطق من catalog/traffic-presets. في وضع first-match تُفحص القواعد من الأعلى إلى الأسفل، بحد أقصى 128؛ ولا يتوفر الحظر لـ«بقية الحركة».

الحفظ ينشئ مسودة. نفّذ التحقق ثم النشر مع If-Match. تحقّق من policy-deployments: الدخول في قائمة الانتظار والتطبيق المؤكَّد من الجهاز حالتان مختلفتان. الاتصال بـ VPN يتم عبر تطبيق العميل.

الأدوار والمجموعات والأجهزة

تُرجع GET /organizations/{id}/roles الأدوار المدمجة والمخصصة وتعريفات الصلاحيات والعلامة can_manage. ينشئ المالك دورًا مخصصًا على أساس دور المسؤول أو الموظف أو الدور المالي، مع إبقاء الصلاحيات اللازمة فقط. يتم التعيين عبر PATCH members/{id}: role وcustom_role_id. تسري تغييرات الصلاحيات أيضًا على عملاء API الذين أنشأهم هذا المستخدم.

الدور يسمح بالإجراءات في اللوحة. يعيّن group_ids للموظف خوادم VPN وباقة التوجيه؛ والعضوية في مجموعة لا تمنح صلاحيات إدارية. لا يمكن نسخ دور المالك إلى دور مخصص. ولا يمكن حذف دور معيَّن لموظفين.

تحصل الأجهزة على display_name ومالك وبيانات VPN. يغيّر PATCH devices/{id} الاسم فقط مع التحقق من If-Match. يطلب POST devices/{id}/revocations الإلغاء؛ وتؤكد العقدة الحالة النهائية. أجهزتك الخاصة متاحة عبر /me/devices. الحقل last_api_ip هو عنوان نقل API وليس عنوان اتصال VPN. لا يُستخدم الاسم والطراز اللذان يبلّغ عنهما التطبيق في التفويض.

الاتصالات وسجل الوجهات

تعرض GET /organizations/{id}/employee-analytics الاتصالات المرصودة وتغيّرات الحالة والسجل بالساعة لمدة 7 أيام. القياس المفقود لا يُستبدل بصفر؛ وعدد الجلسات ليس وقت عمل الموظف.

تُرجع GET /organizations/{id}/activity طلبات الاتصال التي سجّلتها العقدة: النطاق أو IP المطلوب والمنفذ والبروتوكول والوقت والقرار والجهاز والموظف. المرشحات: from وto وmember_id وaction وsearch؛ والصفحات: cursor وlimit. يرسل العميل النطاق في طلب الاتصال، ولا يُستخرج بفك تشفير HTTPS.

الجمع معطّل افتراضيًا. يغيّر المالك activity-settings عبر PATCH مع {"enabled": true} وIf-Match. تتطلب القراءة activity.read. عند تفعيل الجمع يعرض التطبيق إشعارًا للموظف؛ ويتطلب إصدار المفتاح تأكيدًا محدَّثًا لـ X-Corporate-Activity-Version بعد التحقق من مالك المفتاح. العميل القديم لا يحصل على مفتاح لهذا الوضع.

يقتصر التخزين على 7 أيام و100,000 حدث لكل شركة؛ ويحتفظ مخزن العقدة المؤقت بما يصل إلى 24 ساعة. يبلّغ coverage عن حداثة البيانات والأجهزة غير المتاحة وخسائر المخزن المؤقت. لا تُسجَّل شبكات VPN الشخصية ولا حركة الجهاز المباشرة ولا الحظر المحلي قبل الوصول إلى العقدة ولا مسارات HTTPS ولا محتوى الطلبات ولا تقييم الإنتاجية. إيقاف الجمع لا يستعيد السجل المفقود ولا يحذف فورًا السجلات المجمّعة سابقًا: تسري مدة الاحتفاظ.

الفئات ووقت النشاط الشبكي

تحتوي استجابة السجل على analysis: التوزيع حسب الفئات والموظفين والساعات، وأهم الوجهات، وعدد active_minutes. تُحسب الملخصات على جميع الأحداث المحفوظة للفترة المختارة، بغض النظر عن صفحة السجل الأصلي. ينقلك المرشح category إلى الأحداث المحددة.

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

يحدد المالك ما يصل إلى 64 قاعدة classification_rules في إعدادات التسجيل: نطاق وفئة. تسري القواعد على النطاقات الفرعية ولها الأولوية على الدليل المدمج. تبقى الوجهات غير المعروفة في فئة مستقلة. تصنّف القواعد الحالية الفترة المختارة كلها؛ وتذكر الاستجابة إصدار التصنيف.

تُعالَج وجهات اتصالات الشركة، لا محتوى HTTPS ولا عناوين URL الكاملة ولا الحركة الشخصية. يُحفظ تأكيد الإشعار مرة واحدة لكل موظف في الشركة؛ وتغيير الفئات أو المجموعات أو وضع الجمع لا يتطلب تأكيد الإشعار نفسه مجددًا. لا يجوز تفسير علامات التغطية غير الكاملة وtruncated على أنها غياب للنشاط.

الاشتراك في الأحداث

أنشئ webhooks بعنوان HTTPS عام على المنفذ 443 مع الأحداث audit.event أو * أو groups.created وmembers.updated وغيرها من تغييرات الموارد. يُعرض السر عند الإنشاء أو التدوير فقط.

Meduza-Signature: t=UNIX_SECONDS,v1=HEX_SIGNATURE
Meduza-Event-Id: EVENT_ID
Meduza-Delivery-Id: DELIVERY_ID

HEX_SIGNATURE = HMAC-SHA256(secret, timestamp + "." + RAW_JSON_BODY)

تحقّق من التوقيع على البايتات الأصلية لجسم الطلب، ومن العمر المسموح لـ timestamp، ومن تكرار event ID. أثناء التدوير احتفظ بالسر السابق للأحداث الموجودة في قائمة الانتظار. أي استجابة 2xx تُعد نجاحًا؛ وتُعاد المحاولة لبقية الاستجابات بفواصل متزايدة حتى ثماني محاولات. السجل وإعادة الإرسال اليدوي متاحان عبر deliveries. تُحفظ عمليات التسليم الناجحة والملغاة حتى 30 يومًا، بحد أقصى 2,000 لكل webhook. تقتصر قائمة الانتظار والإخفاقات على 1,000 حدث؛ وعند الامتلاء تُحذف الأحداث الأقدم ويبلّغ العدّاد dropped_deliveries عن الفقد. في هذه الحالة زامِن الحالة عبر API.

يتم التسليم مرة واحدة على الأقل. إلى جانب التغييرات عبر API تُرسَل التغييرات المؤكدة في الفواتير (invoices.updated) والاشتراكات (subscriptions.updated) وجاهزية VPN (vpns.updated) والتنبيهات (alerts.created). الاستعلام المتكرر دون تغيّر الحالة لا ينشئ حدثًا جديدًا. هذا ليس تدفقًا لحركة الشبكة. يُمنع استخدام عناوين IP الخاصة وإعادة التوجيه والوصول إلى الخدمات الداخلية.

طرق API

جارٍ تحميل العقد…

صفحات القوائم ومرشحاتها

في قوائم الجرد مرّر limit=1..200 ثم cursor من next_cursor مع الإبقاء على بقية المعاملات. من دون limit/cursor يحصل العملاء القدامى على القائمة كاملة: لا تُقتطع البيانات بصمت أبدًا. المتاح: status وmember_id وuser_id وvpn_id وsearch وcreated_from/created_to (‏RFC3339، الحد الأدنى مشمول والأعلى غير مشمول). يُتحقق من الوصول قبل التصفية وفي كل صفحة. المعاملات غير المعروفة أو المكررة تُرجع 422. تستخدم قوائم سجل النشاط عقدًا مستقلًا. معاملات كل طريقة.

ما يغطيه هذا الإصدار

يُحفظ التدقيق الإداري حتى 90 يومًا، بحد أقصى آخر 10,000 حدث لكل شركة؛ وتُنظَّف سجلات عدم التكرار المنتهية. لا يحذف هذا التنظيف الفواتير والاشتراكات. تُرجع قوائم الجرد items وtotal وnext_cursor؛ ويظهر التتابع عند تمرير limit/cursor صراحة. ومن دونهما تبقى الاستجابة الكاملة متوافقة مع العملاء القدامى. يدعم السجل activity بشكل مستقل مؤشرًا والمرشحات الموثّقة. لا تتكرر الأسرار في الاستجابات القادمة من ذاكرة عدم التكرار. يأتي تأكيد إلغاء المفتاح من خادم VPN؛ وتعطيل العضوية يمنع فورًا أي إصدار جديد.

تعرض المراقبة الاتصالات والحمل الفعليين. سجل الوجهات متاح عبر سجل مستقل يجب تفعيله صراحة. لا تشمل هذه البيانات محتوى HTTPS ولا تقييم إنتاجية الموظفين. لا يشمل هذا العقد المنفَّذ SSO/SCIM وغيرها من طرق المسودة الموسّعة.

تُرجع أخطاء الإدارة application/problem+json مع status وdetail وrequest_id. تستخدم أخطاء إصدار رمز OAuth الحقل error.