Publisher Revenue Audit API 文件

執行公開的發布商營收檢視、擷取 Sulvo 報表，並透過 CLI 與 MCP 伺服器使用的同一套 API，管理已核准的發布商廣告空間。

託管基底網址

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI 與 MCP 設定

基本概念

基底網址

公開稽核端點刻意設計為無須驗證。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	必填。發布商網域或公開主機。未附協定的網域會正規化為 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。

驗證

使用 Sulvo API 金鑰呼叫帳戶 API

在 Sulvo 儀表板的 Account Settings 中產生 API 金鑰。呼叫 Sulvo 帳戶 API 時，請將它作為 Bearer token 傳送。

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 帳戶，以及由擁有者建立且具備 inventory:write scope 的 API 金鑰。

建立廣告單元

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 的稽核回應與 Sulvo 帳戶 API 失敗時，會傳回供代理程式與 CLI 用戶端使用的 JSON 內容。

401

呼叫帳戶 API 時，API 金鑰可能不存在、無效或已過期。公開稽核端點不需要金鑰。

403

金鑰已通過驗證，但缺少必要 scope、帳戶尚未獲核准，或資源屬於其他帳戶。

503 / 504

公開稽核服務已滿載，或稽核逾時。請稍後重試，並在有 Retry-After 時遵守該值。

稽核錯誤封裝格式

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

偏好使用套件用戶端嗎？

npm 套件與 MCP 設定會代您呼叫這些端點，並讓相容的 AI 用戶端使用相同的稽核、報表與廣告空間工作流程。

查看設定