Dokumentace k Publisher Revenue Audit API

Spouštějte veřejné kontroly příjmů vydavatelů, načítejte reporty Sulvo a spravujte schválený reklamní inventář vydavatele přes stejné API jako CLI a server MCP.

Hostovaná základní URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsNastavení CLI a MCP

Základy

Základní URL

Veřejný endpoint auditu záměrně nevyžaduje ověření. Reporty účtu Sulvo a požadavky na reklamní inventář používají klíč API vytvořený v řídicím panelu.

Veřejné API pro audit

POST

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

API účtu Sulvo

Klíč API typu Bearer

https://surge.sulvo.com/api

Hostovaný endpoint MCP

MCP

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

Veřejný endpoint

Spustit audit příjmů

Tento endpoint použijte k orientační kontrole veřejně dostupných podkladů o doméně vydavatele. Odpověď není důkazem ztráty příjmů ani zaručeného růstu. Zjištění ověřte podle reportů vydavatele.

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	Poznámky
input.domain	Povinné. Doména vydavatele nebo veřejný host. Domény bez schématu se převedou na HTTPS. Soukromé cíle, surové IP adresy, interní hosty a nestandardní porty jsou odmítnuty.
input.vertical	Volitelné. Přijímá hodnoty news, sports, entertainment, technology, education, gaming nebo other.
input.metrics	Volitelný kontext z řídicího panelu dodaný vydavatelem, například míra zaplnění, viewability, průměrné CPM, výnos na relaci, měsíční zobrazení stránek nebo měsíční relace.
input.options	Volitelné ovládací prvky výstupu a sběru dat, včetně format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel a partnerId.

Ověřování

Použijte klíč API Sulvo pro API účtu

Vytvořte klíč API v řídicím panelu Sulvo v části Account Settings. Při požadavcích na API účtu Sulvo jej odešlete jako token Bearer.

Hlavička Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Vyžadováno pro export reportů a výpis uložených reportů.

reports:write

Vyžadováno pro vytvoření, aktualizaci, spuštění nebo odstranění pokročilých reportů.

inventory:write

Vyžadováno pro vytvoření a odstranění reklamních jednotek. Účet musí být schválený a musí vlastnit reklamní inventář.

Reporty

Čtecí endpointy reportů

Čtecí reporty používají požadavky GET na základní URL API účtu Sulvo. Hodnoty obsahující pouze datum se interpretují jako celý den v UTC.

Požadavek na report

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	Denní souhrn výkonu. Podporuje filtry pro datum, doménu, kořen reklamní jednotky a poskytovatele.
GET	/api/v1/reports/by-date-and-ad-unit	Denní výkon seskupený podle reklamní jednotky.
GET	/api/v1/reports/by-domain-and-ad-unit	Rozpis výkonu podle domény a reklamní jednotky.
GET	/api/v1/reports/bot-filtering	Report filtrování botů pro kontrolu kvality provozu účtu.
GET	/api/v1/reports/bot-scores	Report skóre botů podle data a souvisejících dimenzí.
GET	/api/v1/reports/invalid-activity	Report neplatné aktivity. Standardní dotaz na datum nebo doménu není vyžadován.
GET	/api/v1/reports/direct-bidder-analysis	Report přímých dražitelů. Vyžaduje directBidder a může zahrnovat start/end.
GET	/api/v1/inventory/ad-units-by-domain	Reklamní jednotky seskupené podle domény.

Běžné parametry dotazu: start, end, opakovatelné domains, opakovatelné adRoots a adProvider. Analýza přímých dražitelů vyžaduje také directBidder.

Pokročilé reporty

Vytvářejte plánované e-mailové reporty nebo je spusťte ihned

Pokročilé reporty lze spustit okamžitě nebo je opakovat podle plánu. Odesílají se e-mailem, nikoli přímo v odpovědi.

Uložit pokročilý report

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	Zobrazit uložené pokročilé reporty pro ověřený účet.
POST	/api/v2/reports/save-advanced-report	Vytvořit nebo aktualizovat pokročilý report. Vyžaduje reportType, toAddress, immediateRun a alespoň jeden cílový parametr adRoots nebo domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Odstranit uložený pokročilý report podle ID.

Typy reportů

adUnit, dimensions, customData

Dimenze

country, device, os

Frekvence

daily, weekly, biweekly, monthly

Inventář

Vytváření a odstraňování schválených reklamních jednotek

Zápis do reklamního inventáře vyžaduje schválený účet Sulvo a klíč API vytvořený vlastníkem s rozsahem inventory:write.

Vytvořit reklamní jednotku

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	Vytvořit jednu reklamní jednotku s nastavením domain, type, volitelným size, placement, vlastním názvem a focusedAd.
PUT	/api/v2/inventory/interstitial-units	Vytvořit pro doménu intersticiální jednotky pro desktop a/nebo mobil.
PUT	/api/v2/inventory/auto-sticky-units	Vytvořit pro doménu fixní display jednotky a/nebo fixní mobilní jednotky.
DELETE	/api/v2/inventory/unit/{adId}	Odstranit reklamní jednotku vlastněnou ověřeným účtem.

Podporované typy reklamních jednotek

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Chyby

Zpracování chyb

Auditní odpovědi mimo rozsah 2xx a chyby API účtu Sulvo vracejí těla JSON určená agentům a klientům CLI.

401

Klíč API pro požadavky na účet chybí, je neplatný nebo vypršel. Veřejný endpoint auditu klíč nevyžaduje.

403

Klíč byl ověřen, ale nemá požadovaný rozsah, účet není schválený nebo zdroj patří jinému účtu.

503 / 504

Veřejná auditní služba je přetížená nebo vypršel časový limit auditu. Zkuste to později a dodržte Retry-After, pokud je uvedeno.

Struktura chyby auditu

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

Dáváte přednost klientovi v balíčku?

Balíček npm a nastavení MCP za Vás volají tyto endpointy a zpřístupňují kompatibilním AI klientům stejné pracovní postupy pro audity, reporty a reklamní inventář.

Zobrazit nastavení