API לבדיקת הכנסות של בעלי אתרים

הפעילו בדיקות ציבוריות של הכנסות בעלי אתרים, אחזרו דוחות Sulvo ונהלו מלאי שטחי פרסום מאושר של בעלי אתרים באמצעות אותו ממשק API שמשמש את ה-CLI ואת שרת ה-MCP.

כתובת בסיס מתארחת

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsהגדרת CLI ו-MCP

יסודות

כתובות בסיס

נקודת הקצה הציבורית לבדיקה אינה דורשת אימות, בכוונה. דוחות החשבון של 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

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.

דוחות מתקדמים

צרו דוחות מתוזמנים או שלחו דוחות באימייל באופן מיידי

אפשר להריץ דוחות מתקדמים מיד או להגדיר להם לוח זמנים חוזר. הדוחות נשלחים באימייל ולא מוחזרים כחלק מתשובת ה-API.

שמירת דוח מתקדם

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	יצירת יחידות Interstitial למחשב שולחני ו/או לנייד עבור דומיין.
PUT	/api/v2/inventory/auto-sticky-units	יצירת יחידות Sticky לתצוגה ו/או לנייד עבור דומיין.
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 קוראות לנקודות הקצה האלה עבורכם ומעמידות לרשות לקוחות AI תואמים את אותם תהליכי עבודה לבדיקה, לדוחות ולמלאי.

הצגת הוראות ההגדרה