پبلشر کی آمدنی کا آڈٹ API

CLI اور MCP سرور والے اسی API کے ذریعے عوامی پبلشر آمدنی آڈٹس چلائیں، Sulvo رپورٹس حاصل کریں اور منظور شدہ پبلشر انوینٹری مینیج کریں۔

ہوسٹڈ بیس URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI اور MCP سیٹ اپ

بنیادی باتیں

بیس URLs

عوامی آڈٹ اینڈ پوائنٹ میں جان بوجھ کر توثیق درکار نہیں۔ Sulvo اکاؤنٹ کی رپورٹس اور انوینٹری کی درخواستوں کے لیے ڈیش بورڈ سے تیار کردہ API کلید استعمال ہوتی ہے۔

عوامی آڈٹ API

POST

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

Sulvo اکاؤنٹ API

Bearer API کلید

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	پبلشر کا لازمی domain یا عوامی host۔ اسکیم کے بغیر 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 کلید استعمال کریں

Sulvo ڈیش بورڈ میں اکاؤنٹ کی ترتیبات کے تحت API کلید بنائیں۔ Sulvo اکاؤنٹ API درخواستوں میں اسے Bearer ٹوکن کے طور پر بھیجیں۔

Authorization ہیڈر

Authorization: Bearer $SULVO_API_KEY

reports:read

رپورٹیں ایکسپورٹ کرنے اور محفوظ شدہ رپورٹس کی فہرست کے لیے درکار ہے۔

reports:write

جدید رپورٹس بنانے، اپ ڈیٹ کرنے، چلانے یا حذف کرنے کے لیے درکار ہے۔

inventory:write

اشتہاری یونٹ بنانے اور حذف کرنے کے لیے درکار ہے۔ اکاؤنٹ منظور شدہ ہو اور انوینٹری اسی کی ملکیت ہو۔

رپورٹس

رپورٹ اینڈ پوائنٹس سے ڈیٹا لیں

رپورٹ پڑھنے کی درخواستیں Sulvo اکاؤنٹ API بیس کے تحت GET درخواستیں استعمال کرتی ہیں۔ صرف تاریخ والی قدروں کو پورے 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	روزانہ کارکردگی کا خلاصہ۔ date، domain، ad root اور provider فلٹرز دستیاب ہیں۔
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	ایک domain کے لیے ڈیسک ٹاپ، موبائل یا دونوں کے انٹرسٹیشل یونٹس بنائیں۔
PUT	/api/v2/inventory/auto-sticky-units	ایک domain کے لیے اسٹکی ڈسپلے، اسٹکی موبائل یا دونوں یونٹس بنائیں۔
DELETE	/api/v2/inventory/unit/{adId}	توثیق شدہ اکاؤنٹ کی ملکیت والا اشتہاری یونٹ حذف کریں۔

تائید شدہ اشتہاری یونٹ کی اقسام

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

خرابیاں

خرابیوں کو سنبھالنا

غیر 2xx آڈٹ جوابات اور Sulvo اکاؤنٹ API کی ناکامیاں 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 سیٹ اپ آپ کی طرف سے ان اینڈ پوائنٹس کو استعمال کرتے ہیں اور مطابقت رکھنے والے AI کلائنٹس کو وہی آڈٹ، رپورٹ اور انوینٹری ورک فلو فراہم کرتے ہیں۔

سیٹ اپ دیکھیں