发布商收入审计 API

运行公开的发布商收入筛查，获取 Sulvo 报表，并通过 CLI 和 MCP 服务器使用的同一 API 接口管理已获批准的发布商广告资源。

托管基础 URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI 与 MCP 设置

基础信息

基础 URL

公开审计端点有意设为无需身份验证。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 控制台的“账户设置”中生成 API 密钥。在 Sulvo 账户 API 请求中将其作为 Bearer 令牌发送。

Authorization 标头

Authorization: Bearer $SULVO_API_KEY

reports:read

导出报表和查看已保存报表列表时必需。

reports:write

创建、更新、运行或删除高级报表时必需。

inventory:write

创建和删除广告单元时必需。账户必须已获批准且拥有相应广告资源。

报表

读取报表端点

读取报表时，请在 Sulvo 账户 API 基础 URL 下使用 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	每日效果摘要。支持按日期、域名、广告根目录和需求方筛选。
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 权限范围且由账户所有者生成的 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 故障会返回 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 客户端提供相同的审计、报表和广告资源工作流程。

查看设置指南