Publisher Revenue Audit API

Führen Sie öffentliche Umsatzprüfungen für Publisher durch, rufen Sie Sulvo-Berichte ab und verwalten Sie genehmigtes Publisher-Inventar über dieselbe API-Schnittstelle wie CLI und MCP-Server.

Gehostete Basis-URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI- und MCP-Einrichtung

Grundlagen

Basis-URLs

Der öffentliche Audit-Endpunkt erfordert absichtlich keine Authentifizierung. Für Berichte und Inventarabrufe zum Sulvo-Konto wird ein im Dashboard generierter API-Schlüssel verwendet.

Öffentliche Audit-API

POST

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

Sulvo-Konto-API

Bearer-API-Schlüssel

https://surge.sulvo.com/api

Gehosteter MCP-Endpunkt

MCP

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

Öffentlicher Endpunkt

Umsatz-Audit ausführen

Verwenden Sie diesen Endpunkt für eine orientierende Prüfung öffentlicher Belege zu einer Publisher-Domain. Die Antwort ist kein Beweis für Umsatzverluste und garantiert keine Steigerung. Prüfen Sie die Befunde anhand des publisherseitigen Reportings.

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
      }
    }
  }'

Feld	Hinweise
input.domain	Erforderliche Publisher-Domain oder öffentlicher Host. Domains ohne Protokoll werden zu HTTPS normalisiert. Private Ziele, reine IP-Adressen, interne Hosts und nicht standardmäßige Ports werden abgelehnt.
input.vertical	Optional. Zulässig sind news, sports, entertainment, technology, education, gaming oder other.
input.metrics	Optionaler, vom Publisher bereitgestellter Dashboard-Kontext, etwa Fill Rate, Viewability, durchschnittlicher CPM, Umsatz pro Sitzung, monatliche Seitenaufrufe oder monatliche Sitzungen.
input.options	Optionale Steuerung von Ausgabe und Datenerfassung, einschließlich format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel und partnerId.

Authentifizierung

Sulvo-API-Schlüssel für Konto-APIs verwenden

Erstellen Sie im Sulvo-Dashboard unter Account Settings einen API-Schlüssel. Senden Sie ihn bei API-Anfragen an Ihr Sulvo-Konto als Bearer-Token.

Authorization-Header

Authorization: Bearer $SULVO_API_KEY

reports:read

Erforderlich für Berichtsexporte und die Auflistung gespeicherter Berichte.

reports:write

Erforderlich, um erweiterte Berichte zu erstellen, zu aktualisieren, auszuführen oder zu löschen.

inventory:write

Erforderlich zum Erstellen und Löschen von Anzeigenblöcken. Das Konto muss genehmigt sein und das Inventar besitzen.

Berichte

Endpunkte zum Abrufen von Berichten

Lesezugriffe auf Berichte verwenden GET-Anfragen unter der Basis-URL der Sulvo-Konto-API. Datumsangaben ohne Uhrzeit werden als vollständiger UTC-Tag interpretiert.

Berichtsanfrage

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	Tägliche Leistungsübersicht. Unterstützt Filter für Datum, Domain, Ad-Root und Anbieter.
GET	/api/v1/reports/by-date-and-ad-unit	Tägliche Leistung, aufgeschlüsselt nach Anzeigenblock.
GET	/api/v1/reports/by-domain-and-ad-unit	Leistungsaufschlüsselung nach Domain und Anzeigenblock.
GET	/api/v1/reports/bot-filtering	Bericht zur Bot-Filterung für die Prüfung der Konto-Traffic-Qualität.
GET	/api/v1/reports/bot-scores	Bot-Score-Berichte nach Datum und verwandten Dimensionen.
GET	/api/v1/reports/invalid-activity	Berichte zu ungültigen Aktivitäten. Eine standardmäßige Datums- oder Domainabfrage ist nicht erforderlich.
GET	/api/v1/reports/direct-bidder-analysis	Bericht zu direkten Bietern. Erfordert directBidder; start und end können enthalten sein.
GET	/api/v1/inventory/ad-units-by-domain	Anzeigenblockinventar, gruppiert nach Domain.

Übliche Abfrageparameter: start, end, wiederholbare domains, wiederholbare adRoots und adProvider. Die Analyse direkter Bieter erfordert außerdem directBidder.

Erweiterte Berichte

Geplante oder sofortige E-Mail-Berichte erstellen

Erweiterte Berichte können sofort oder regelmäßig nach Zeitplan ausgeführt werden. Sie werden per E-Mail zugestellt und nicht direkt in der Antwort zurückgegeben.

Erweiterten Bericht speichern

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	Gespeicherte erweiterte Berichte für das authentifizierte Konto auflisten.
POST	/api/v2/reports/save-advanced-report	Erweiterten Bericht erstellen oder aktualisieren. Erfordert reportType, toAddress, immediateRun und mindestens ein Ziel aus adRoots oder domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Gespeicherten erweiterten Bericht anhand seiner ID löschen.

Berichtstypen

adUnit, dimensions, customData

Dimensionen

country, device, os

Häufigkeit

daily, weekly, biweekly, monthly

Inventar

Genehmigte Anzeigenblöcke erstellen und löschen

Zum Ändern des Inventars ist ein genehmigtes Sulvo-Konto sowie ein vom Kontoinhaber erstellter API-Schlüssel mit dem Scope inventory:write erforderlich.

Anzeigenblock erstellen

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	Einen einzelnen Anzeigenblock mit Domain, Typ, optionaler Größe, Platzierung, benutzerdefiniertem Namen und focusedAd-Einstellungen erstellen.
PUT	/api/v2/inventory/interstitial-units	Interstitial-Anzeigenblöcke für Desktop und/oder Mobilgeräte für eine Domain erstellen.
PUT	/api/v2/inventory/auto-sticky-units	Sticky-Display- und/oder Sticky-Mobile-Anzeigenblöcke für eine Domain erstellen.
DELETE	/api/v2/inventory/unit/{adId}	Einen Anzeigenblock löschen, der dem authentifizierten Konto gehört.

Unterstützte Anzeigenblocktypen

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Fehler

Fehlerbehandlung

Audit-Antworten außerhalb des 2xx-Bereichs und Fehler der Sulvo-Konto-API geben JSON-Inhalte zurück, die für Agenten- und CLI-Clients ausgelegt sind.

401

Der API-Schlüssel fehlt, ist ungültig oder für Konto-API-Anfragen abgelaufen. Für den öffentlichen Audit-Endpunkt ist kein Schlüssel erforderlich.

403

Der Schlüssel wurde authentifiziert, verfügt aber nicht über den erforderlichen Scope, das Konto ist nicht genehmigt oder die Ressource gehört zu einem anderen Konto.

503 / 504

Der öffentliche Audit-Dienst ist ausgelastet oder das Audit hat das Zeitlimit überschritten. Versuchen Sie es später erneut und beachten Sie gegebenenfalls Retry-After.

Audit-Fehlerstruktur

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

Bevorzugen Sie einen installierten Client?

Das npm-Paket und die MCP-Einrichtung rufen diese Endpunkte für Sie auf und stellen kompatiblen KI-Clients dieselben Workflows für Audits, Berichte und Inventar bereit.

Einrichtung ansehen