# حزمة وكيل FineProxy

الإصدار: 2026-09-22

استخدم هذا الملف لتقييم إمكانية ترحيل تكامل بروكسي قائم إلى FineProxy. لا يحتوي الملف على مفتاح API أو بيانات حساب أو نقطة نهاية خاصة.

## مصادر الحقيقة

- توثيق API التفاعلي للعميل: `https://fineproxy.org/account_new/docs`
- إعداد MCP: `https://fineproxy.org/account_new/mcp`
- مواصفات OpenAPI الحالية للعميل: نزّلها من توثيق API في لوحة تحكم العميل.
- إنشاء مفاتيح API وإدارتها: `https://fineproxy.org/account_new/settings`
- نقطة نهاية MCP: `https://fineproxy.org/account_new/api/v1/mcp`

لا تخترع مطلقًا نقطة نهاية من هذه النظرة العامة. استخدم مواصفات OpenAPI الحالية لمسارات الطلبات والمخططات والمعلمات والاستجابات.

## ملخص المنصة

- REST API: ‏OpenAPI 3.1، و49 عملية موثقة للعملاء.
- MCP: ‏49 أداة عبر JSON-RPC 2.0 عديم الحالة وStreamable HTTP.
- المصادقة: مفاتيح API من نوع bearer تُنشأ في لوحة تحكم العميل.
- تستخدم API وMCP الأذونات محددة النطاق نفسها.
- لا يظهر توثيق API للشركاء إلا للحسابات ذات وضع الشريك النشط.

## مسارات العمل المدعومة

### الشراء والتوفير

- عرض الدول والمخزون المباشر من عناوين IP.
- تسعير حزمة دقيقة متعددة الدول من دون شراء.
- الشراء من محفظة لوحة التحكم مع قيد للسعر ومفتاح عدم تكرار.

تسلسل الشراء القياسي في MCP هو:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### إدارة الخدمات

- قراءة الخدمات وإدارتها.
- التجديد أو التعليق أو الاستعادة أو الإلغاء عندما يكون ذلك مدعومًا.
- تفعيل التجديد التلقائي أو تعطيله.
- استبدال عناوين IP أو إضافة عناوين جديدة.
- تغيير بيانات اعتماد الخدمة.
- قراءة حدود قائمة السماح وإدارتها.
- عرض الإضافات المتوافقة وشراؤها وإلغاؤها.

### التحليلات والتشخيص

- نظرة عامة على الاستخدام وسلاسله الزمنية.
- أهم الوجهات.
- فئات الأخطاء.
- توصيات تشغيلية.

### الفوترة والدعم

- قراءة الفواتير وتنزيل ملفات PDF الخاصة بها.
- عرض بوابات الدفع.
- بدء إيداع في المحفظة وقراءة حالته.
- إنشاء تذاكر الدعم وقراءتها والرد عليها وإغلاقها.

### الوصول عبر البروكسي والحساب

- قراءة إعداد اتصال البروكسي المتناوب.
- تغيير اسم دخول الخدمة وكلمة المرور.
- إدارة حدود الاتصالات لكل عنوان IP في قائمة السماح.
- قراءة معلومات الملف الشخصي وعنوان IP للمتصل وسجل تسجيل الدخول.
- تهيئة خطافات الويب.

## نطاقات الأذونات

- `customer:read` — قراءة معلومات العميل والحساب.
- `customer:write` — تحديث معلومات العميل.
- `wallet:read` — قراءة معلومات المحفظة.
- `wallet:deposit` — إنشاء الإيداعات ومراقبتها.
- `wallet:spend` — إنفاق أموال المحفظة. تعامل معه بوصفه إذنًا ماليًا.
- `services:read` — قراءة الخدمات وإعدادات البروكسي.
- `services:write` — إنشاء الخدمات والإضافات أو تعديلها.
- `tickets:read` — قراءة تذاكر الدعم.
- `tickets:write` — إنشاء التذاكر أو الرد عليها أو تحديثها أو إغلاقها.
- `catalog:read` — قراءة المنتجات والخيارات والدول والمخزون.
- `usage:read` — قراءة الاستخدام والتشخيصات.
- `webhooks` — إدارة اشتراكات خطافات الويب.

ابدأ تدقيق الترحيل بأذونات القراءة فقط. لا تضف أذونات الكتابة أو الأذونات المالية إلا بعد مراجعة التغييرات المقترحة.

## سلوك الأمان

- تتطلب الأدوات المالية `wallet:spend`.
- تحمل عمليات الشراء الإجمالي المتوقع الوارد في عرض السعر. يؤدي عدم تطابق السعر إلى رفض العملية.
- تتطلب العمليات غير القابلة للعكس تأكيدًا صريحًا.
- تستخدم إعادة محاولة العمليات المالية مفتاح عدم تكرار كي لا تُحصّل تكلفة العملية نفسها مرتين.
- قد يمنع المخزون المباشر وأهلية الخطة وأذونات الحساب عملية صحيحة من نواحٍ أخرى.
- يشغّل FineProxy MCP حساب العميل، ولا يحصل على وصول إلى الكود المصدري ما لم يمنح المستخدم وكيل البرمجة وصولًا منفصلًا إلى المستودع.

## قالب إعداد MCP

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

خزّن المفتاح الحقيقي في متغير بيئة أو مدير أسرار. لا تودعه في المستودع مع إعداد MCP.

## قائمة التحقق من توافق الترحيل

افحص التكامل القائم بحثًا عما يلي:

1. تهيئة عميل المزوّد وجميع عمليات الاستيراد الخاصة بالمزوّد.
2. ترويسات المصادقة وبيانات الاعتماد ومتغيرات البيئة وتخزين الأسرار.
3. سير عمل الشراء والتجديد والإلغاء واستبدال عناوين IP.
4. معرّفات الدول والافتراضات المتعلقة بالمخزون.
5. تنسيقات قوائم البروكسي والبروتوكولات والمنافذ وأسماء المستخدمين وكلمات المرور وإدراج عناوين IP في قائمة السماح.
6. التصفح بالصفحات والتصفية.
7. سلوك إعادة المحاولة ومعالجة انتهاء المهلة وعدم التكرار.
8. نماذج الأخطاء ومعالجة حدود المعدل.
9. تحليلات الاستخدام والتشخيصات.
10. الفوترة والفواتير والإيداعات.
11. تكامل تذاكر الدعم.
12. خطافات الويب والافتراضات المتعلقة بحمولات الأحداث.
13. الاختبارات وبيانات الاختبار والعناصر الوهمية وأسرار CI المرتبطة بالمزوّد الحالي.

صنّف كل سير عمل بوصفه:

- متوافقًا من دون تغييرات.
- متوافقًا عبر تغيير في الإعداد.
- يتطلب محوّلًا أو تحويلًا للبيانات.
- يتطلب سير عمل تشغيليًا مختلفًا.
- غير مدعوم أو غير مؤكد وفق التوثيق الحالي.

## مخرجات التدقيق المطلوبة

ينبغي أن يتضمن التدقيق ما يلي:

1. جردًا لكل تبعية مرتبطة بالمزوّد الحالي.
2. تقييمًا للتوافق لكل سير عمل.
3. نطاقات FineProxy المطلوبة.
4. الملفات ومسارات الكود الدقيقة التي ستتغير.
5. التغييرات في المصادقة وإدارة الأسرار.
6. أسئلة مفتوحة تتطلب مواصفات OpenAPI الحالية أو تأكيدًا من الدعم.
7. خطة ترحيل مرحلية مع التراجع.
8. اختبارات التكامل المطلوبة قبل التحويل.

لا تعدّل الكود خلال المرحلة الأولى من التدقيق.