واجهة Publisher Revenue Audit API

أجرِ فحوصاً عامة لإيرادات الناشرين، واجلب تقارير Sulvo، وأدِر المخزون الإعلاني للناشرين المعتمدين عبر واجهة API نفسها التي يستخدمها CLI وخادم MCP.

عنوان URL الأساسي المستضاف

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsإعداد CLI وMCP

الأساسيات

عناوين URL الأساسية

نقطة نهاية التدقيق العام لا تتطلب مصادقة عمداً. أما تقارير حساب Sulvo وطلبات المخزون الإعلاني فتستخدم مفتاح API مُنشأ من لوحة التحكم.

API التدقيق العام

POST

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-audits

API حساب Sulvo

مفتاح API من نوع Bearer

https://surge.sulvo.com/api

نقطة نهاية MCP المستضافة

MCP

https://publisher-revenue-audit.sulvo.com/mcp

نقطة نهاية عامة

أجرِ تدقيقاً للإيرادات

استخدم نقطة النهاية هذه لإجراء فحص استرشادي لنطاق ناشر استناداً إلى الأدلة العامة. لا تثبت الاستجابة خسارة الإيرادات ولا تضمن زيادتها. تحقق من النتائج بالرجوع إلى تقارير الناشر.

cURL

curl -X POST https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-audits \
  -H "content-type: application/json" \
  -d '{
    "tool": "run_publisher_revenue_audit",
    "input": {
      "domain": "example.com",
      "vertical": "news",
      "options": {
        "format": "json",
        "compact": true,
        "maxPages": 2,
        "enablePageSpeed": true
      }
    }
  }'

الحقل	ملاحظات
input.domain	نطاق ناشر مطلوب أو مضيف عام. تُحوّل النطاقات المجردة تلقائياً إلى HTTPS. تُرفض الوجهات الخاصة وعناوين IP الخام والمضيفات الداخلية والمنافذ غير القياسية.
input.vertical	اختياري. يقبل news أو sports أو entertainment أو technology أو education أو gaming أو other.
input.metrics	سياق اختياري من لوحة تحكم الناشر، مثل معدل الملء أو قابلية الرؤية أو متوسط CPM أو الإيرادات لكل جلسة أو مشاهدات الصفحات الشهرية أو الجلسات الشهرية.
input.options	عناصر اختيارية للتحكم في المخرجات وجمع البيانات، تشمل format وcompact وmaxPages وincludeEvidence وenableBrowser وincludeScreenshots وenablePageSpeed وpageSpeedStrategy وconcurrency وwhiteLabel وpartnerId.

المصادقة

استخدم مفتاح API من Sulvo لواجهات API الخاصة بالحساب

أنشئ مفتاح API في لوحة تحكم Sulvo ضمن إعدادات الحساب. أرسله كرمز Bearer مع طلبات API لحساب Sulvo.

ترويسة التفويض

Authorization: Bearer $SULVO_API_KEY

reports:read

مطلوب لتصدير التقارير وعرض التقارير المحفوظة.

reports:write

مطلوب لإنشاء التقارير المتقدمة أو تحديثها أو تشغيلها أو حذفها.

inventory:write

مطلوب لإنشاء الوحدات الإعلانية وحذفها. يجب اعتماد الحساب وأن يكون مالكاً للمخزون الإعلاني.

التقارير

نقاط نهاية قراءة التقارير

تستخدم طلبات قراءة التقارير طريقة GET ضمن عنوان API الأساسي لحساب Sulvo. تُفسّر قيم التاريخ وحدها على أنها حدود يوم كامل بتوقيت UTC.

طلب تقرير

curl "https://surge.sulvo.com/api/v1/reports/by-date?start=2026-06-01&end=2026-06-07&domains=example.com" \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "accept: application/json"

Method	Path	Notes
GET	/api/v1/reports/by-date	ملخص الأداء اليومي. يدعم عوامل التصفية حسب التاريخ والنطاق وجذر الإعلان والموفر.
GET	/api/v1/reports/by-date-and-ad-unit	الأداء اليومي مجمّعاً حسب الوحدة الإعلانية.
GET	/api/v1/reports/by-domain-and-ad-unit	تفصيل الأداء حسب النطاق والوحدة الإعلانية.
GET	/api/v1/reports/bot-filtering	تقرير تصفية الروبوتات لمراجعة جودة الزيارات في الحساب.
GET	/api/v1/reports/bot-scores	تقارير درجات الروبوتات حسب التاريخ والأبعاد ذات الصلة.
GET	/api/v1/reports/invalid-activity	تقارير النشاط غير الصالح. لا يلزم استعلام قياسي حسب التاريخ أو النطاق.
GET	/api/v1/reports/direct-bidder-analysis	تقرير مقدم العطاء المباشر. يتطلب directBidder ويمكن أن يتضمن start وend.
GET	/api/v1/inventory/ad-units-by-domain	المخزون الإعلاني للوحدات الإعلانية مجمّع حسب النطاق.

معلمات الاستعلام الشائعة: start وend وdomains وadRoots (يمكن تكرار كل منهما) وadProvider. ويتطلب تحليل مقدم العطاء المباشر أيضاً directBidder.

التقارير المتقدمة

أنشئ تقارير مجدولة أو فورية عبر البريد الإلكتروني

يمكن تشغيل التقارير المتقدمة فوراً أو تكرارها وفق جدول زمني. تُرسل عبر البريد الإلكتروني بدلاً من إرجاعها ضمن الاستجابة.

حفظ تقرير متقدم

curl -X POST https://surge.sulvo.com/api/v2/reports/save-advanced-report \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "reportType": "dimensions",
    "toAddress": "publisher@example.com",
    "immediateRun": true,
    "domains": ["example.com"],
    "dimensions": ["country", "device"],
    "start": "2026-06-01",
    "end": "2026-06-07"
  }'

Method	Path	Notes
GET	/api/v2/reports/advanced-reports	اعرض التقارير المتقدمة المحفوظة للحساب المصادَق عليه.
POST	/api/v2/reports/save-advanced-report	أنشئ تقريراً متقدماً أو حدّثه. يتطلب reportType وtoAddress وimmediateRun وهدفاً واحداً على الأقل من adRoots أو domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	احذف تقريراً متقدماً محفوظاً باستخدام المعرّف id.

أنواع التقارير

adUnit, dimensions, customData

الأبعاد

country, device, os

التكرار

daily, weekly, biweekly, monthly

المخزون الإعلاني

أنشئ وحدات إعلانية معتمدة واحذفها

تتطلب تعديلات المخزون الإعلاني حساب Sulvo معتمداً ومفتاح API صادراً عن المالك مع نطاق inventory:write.

إنشاء وحدة إعلانية

curl -X PUT https://surge.sulvo.com/api/v2/inventory/unit \
  -H "authorization: Bearer $SULVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "domain": "example.com",
    "type": "display",
    "size": { "width": 300, "height": 250 }
  }'

Method	Path	Notes
PUT	/api/v2/inventory/unit	أنشئ وحدة إعلانية واحدة باستخدام domain وtype وsize اختياري وplacement وcustom name وإعدادات focusedAd.
PUT	/api/v2/inventory/interstitial-units	أنشئ وحدات إعلانية بينية لأجهزة الكمبيوتر و/أو الهواتف لنطاق معين.
PUT	/api/v2/inventory/auto-sticky-units	أنشئ وحدات ثابتة لإعلانات العرض و/أو وحدات ثابتة للهواتف لنطاق معين.
DELETE	/api/v2/inventory/unit/{adId}	احذف وحدة إعلانية يملكها الحساب المصادَق عليه.

أنواع الوحدات الإعلانية المدعومة

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

الأخطاء

معالجة الأخطاء

تعيد استجابات التدقيق ذات رموز الحالة غير 2xx وإخفاقات API حساب Sulvo أجسام JSON مصممة لعملاء الوكلاء وCLI.

401

مفتاح API مفقود أو غير صالح أو منتهي الصلاحية في طلبات API الخاصة بالحساب. لا تتطلب نقطة نهاية التدقيق العام مفتاحاً.

403

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

503 / 504

خدمة التدقيق العام مشغولة أو انتهت مهلة التدقيق. أعد المحاولة لاحقاً والتزم بترويسة Retry-After عند توفرها.

غلاف خطأ التدقيق

{
  "error": {
    "code": "audit_capacity_exceeded",
    "message": "Audit capacity is currently exhausted. Retry later."
  }
}

هل تفضل عميلاً مضمّناً؟

تستدعي حزمة npm وإعداد MCP نقاط النهاية هذه نيابة عنك، وتتيح سير العمل نفسه للتدقيق والتقارير وإدارة المخزون الإعلاني لعملاء الذكاء الاصطناعي المتوافقين.

عرض الإعداد