API do audytu przychodów wydawców

Wykonuj wstępne publiczne analizy przychodów wydawców, pobieraj raporty Sulvo i zarządzaj zatwierdzoną powierzchnią reklamową wydawcy przez to samo API, z którego korzystają CLI i serwer MCP.

Hostowany adres bazowy

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsKonfiguracja CLI i MCP

Podstawy

Podstawowe adresy URL

Publiczny punkt końcowy audytu celowo nie wymaga uwierzytelnienia. Raporty kont Sulvo i operacje na powierzchni reklamowej korzystają z klucza API wygenerowanego w panelu.

Publiczne API audytu

POST

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

API konta Sulvo

Klucz API typu Bearer

https://surge.sulvo.com/api

Hostowany punkt końcowy MCP

MCP

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

Publiczny punkt końcowy

Uruchom audyt przychodów

Użyj tego punktu końcowego, aby wstępnie ocenić domenę wydawcy na podstawie publicznie dostępnych danych. Odpowiedź nie stanowi dowodu utraty przychodów ani gwarancji wzrostu. Zweryfikuj wyniki w raportach po stronie wydawcy.

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

Pole	Uwagi
input.domain	Wymagana domena wydawcy lub publiczny host. Domeny bez protokołu są uzupełniane do HTTPS. Adresy prywatne, surowe adresy IP, hosty wewnętrzne i porty niestandardowe są odrzucane.
input.vertical	Opcjonalne. Przyjmuje wartości: news, sports, entertainment, technology, education, gaming lub other.
input.metrics	Opcjonalny kontekst z panelu podany przez wydawcę, na przykład fill rate, viewability, średni CPM, przychód na sesję, miesięczna liczba odsłon lub miesięczna liczba sesji.
input.options	Opcjonalne ustawienia wyjścia i zbierania danych, w tym format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel i partnerId.

Uwierzytelnianie

Użyj klucza API Sulvo do API konta

Wygeneruj klucz API w panelu Sulvo, w sekcji Ustawienia konta. W żądaniach do API konta Sulvo wysyłaj go jako token Bearer.

Nagłówek Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Wymagany do eksportowania raportów i wyświetlania listy zapisanych raportów.

reports:write

Wymagany do tworzenia, aktualizowania, uruchamiania lub usuwania raportów zaawansowanych.

inventory:write

Wymagany do tworzenia i usuwania jednostek reklamowych. Konto musi być zatwierdzone i posiadać daną powierzchnię reklamową.

Raporty

Odczyt raportów przez API

Raporty do odczytu korzystają z żądań GET kierowanych do podstawowego adresu API konta Sulvo. Wartości zawierające wyłącznie datę są interpretowane jako pełny dzień w UTC.

Żądanie raportu

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	Podsumowanie dziennych wyników. Obsługuje filtry daty, domeny, identyfikatora głównej jednostki reklamowej i dostawcy.
GET	/api/v1/reports/by-date-and-ad-unit	Dzienne wyniki z podziałem na jednostki reklamowe.
GET	/api/v1/reports/by-domain-and-ad-unit	Zestawienie wyników według domeny i jednostki reklamowej.
GET	/api/v1/reports/bot-filtering	Raport filtrowania botów do przeglądu jakości ruchu na koncie.
GET	/api/v1/reports/bot-scores	Raport wyników oceny botów według daty i powiązanych wymiarów.
GET	/api/v1/reports/invalid-activity	Raport nieprawidłowej aktywności. Nie wymaga standardowego zapytania z datą ani domeną.
GET	/api/v1/reports/direct-bidder-analysis	Raport bezpośredniego oferenta. Wymaga directBidder, może też zawierać start i end.
GET	/api/v1/inventory/ad-units-by-domain	Powierzchnia reklamowa z podziałem na domeny.

Typowe parametry zapytania: start, end, powtarzalne domains, powtarzalne adRoots oraz adProvider. Analiza bezpośredniego oferenta wymaga również directBidder.

Raporty zaawansowane

Twórz zaplanowane lub natychmiastowe raporty e-mail

Raporty zaawansowane można uruchomić od razu lub cyklicznie według harmonogramu. Są wysyłane e-mailem, a nie zwracane bezpośrednio w odpowiedzi.

Zapisz raport zaawansowany

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	Wyświetl zapisane raporty zaawansowane uwierzytelnionego konta.
POST	/api/v2/reports/save-advanced-report	Utwórz lub zaktualizuj raport zaawansowany. Wymaga reportType, toAddress, immediateRun i co najmniej jednego celu w adRoots lub domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Usuń zapisany raport zaawansowany według id.

Typy raportów

adUnit, dimensions, customData

Wymiary

country, device, os

Częstotliwość

daily, weekly, biweekly, monthly

Powierzchnia reklamowa

Twórz i usuwaj zatwierdzone jednostki reklamowe

Operacje zapisu powierzchni reklamowej wymagają zatwierdzonego konta Sulvo oraz klucza API utworzonego przez jego właściciela z zakresem inventory:write.

Utwórz jednostkę reklamową

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	Utwórz pojedynczą jednostkę reklamową, podając pola domain, type, placement i custom name oraz ustawienia focusedAd. Pole size jest opcjonalne.
PUT	/api/v2/inventory/interstitial-units	Utwórz dla domeny jednostki interstitial na komputery stacjonarne, urządzenia mobilne lub oba typy urządzeń.
PUT	/api/v2/inventory/auto-sticky-units	Utwórz dla domeny jednostki sticky display, sticky mobile albo oba typy jednostek.
DELETE	/api/v2/inventory/unit/{adId}	Usuń jednostkę reklamową należącą do uwierzytelnionego konta.

Obsługiwane typy jednostek reklamowych

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Błędy

Obsługa błędów

Odpowiedzi audytu inne niż 2xx oraz błędy API konta Sulvo zwracają treść JSON przeznaczoną dla agentów i klientów CLI.

401

W żądaniach do API konta brakuje klucza API albo jest on nieprawidłowy lub wygasł. Publiczny punkt końcowy audytu nie wymaga klucza.

403

Klucz został uwierzytelniony, ale nie ma wymaganego zakresu uprawnień, konto nie jest zatwierdzone albo zasób należy do innego konta.

503 / 504

Publiczna usługa audytu jest przeciążona albo audyt przekroczył limit czasu. Spróbuj ponownie później i przestrzegaj wartości Retry-After, jeśli jest obecna.

Struktura błędu audytu

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

Wolisz gotowego klienta?

Pakiet npm i konfiguracja MCP wywołują te punkty końcowe za Ciebie i udostępniają zgodnym klientom AI te same procesy pracy z audytem, raportami i powierzchnią reklamową.

Zobacz konfigurację