Audit príjmov vydavateľa cez API

Spúšťajte verejné predbežné kontroly príjmov vydavateľov, získavajte reporty Sulvo a spravujte schválený reklamný inventár cez rovnaké rozhranie API, ktoré používajú CLI a server MCP.

Základná adresa API

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

Základy

Základné adresy

Verejný koncový bod auditu zámerne nevyžaduje autentifikáciu. Reporty účtu Sulvo a požiadavky na inventár používajú kľúč API vygenerovaný v ovládacom paneli.

Verejné API auditu

POST

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

API účtu Sulvo

Kľúč API typu Bearer

https://surge.sulvo.com/api

Hostovaný koncový bod MCP

MCP

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

Verejný koncový bod

Spustite audit príjmov

Tento koncový bod použite na orientačnú kontrolu domény vydavateľa podľa verejne dostupných dôkazov. Odpoveď nedokazuje stratu príjmov ani nezaručuje ich zvýšenie. Zistenia overte podľa vlastných reportov vydavateľa.

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 vydavateľa alebo verejný hostiteľ. Domény bez protokolu sa normalizujú na HTTPS. Súkromné ciele, priame IP adresy, interné názvy hostiteľov a neštandardné porty sa odmietajú.
input.vertical	Voliteľné. Podporované hodnoty: news, sports, entertainment, technology, education, gaming alebo other.
input.metrics	Voliteľný kontext z ovládacieho panela od vydavateľa, napríklad miera naplnenia, viditeľnosť reklamy, priemerné CPM, príjem na reláciu, mesačné zobrazenia stránok alebo mesačný počet relácií.
input.options	Voliteľné nastavenia výstupu a zberu údajov vrátane format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel a partnerId.

Autentifikácia

Pre API účtu používajte kľúč API Sulvo

V ovládacom paneli Sulvo v časti Nastavenia účtu vytvorte kľúč API. Pri požiadavkách na API účtu Sulvo ho odošlite ako token typu Bearer.

Hlavička Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Vyžaduje sa na export reportov a zobrazenie zoznamu uložených reportov.

reports:write

Vyžaduje sa na vytváranie, aktualizáciu, spúšťanie alebo odstraňovanie pokročilých reportov.

inventory:write

Vyžaduje sa na vytváranie a odstraňovanie reklamných jednotiek. Účet musí byť schválený a musí vlastniť inventár.

Reporty

Koncové body na čítanie reportov

Požiadavky GET na čítanie reportov smerujú na základnú adresu API účtu Sulvo. Dátumy bez uvedeného času sa interpretujú ako časové hranice celého dňa v UTC.

Požiadavka 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ý súhrn výkonu. Podporuje filtrovanie podľa dátumu, domény, ad rootu a poskytovateľa reklám.
GET	/api/v1/reports/by-date-and-ad-unit	Denný výkon rozdelený podľa reklamnej jednotky.
GET	/api/v1/reports/by-domain-and-ad-unit	Prehľad výkonu podľa domény a reklamnej jednotky.
GET	/api/v1/reports/bot-filtering	Report filtrovania botov na kontrolu kvality návštevnosti účtu.
GET	/api/v1/reports/bot-scores	Reporty hodnotenia botov podľa dátumu a súvisiacich dimenzií.
GET	/api/v1/reports/invalid-activity	Report o neplatnej aktivite. Nevyžaduje sa štandardný dopyt s dátumom ani doménou.
GET	/api/v1/reports/direct-bidder-analysis	Report priameho biddera. Vyžaduje parameter directBidder a môže obsahovať start a end.
GET	/api/v1/inventory/ad-units-by-domain	Inventár reklamných jednotiek rozdelený podľa domény.

Bežné parametre dopytu: start, end, opakovateľný domains, opakovateľný adRoots a adProvider. Analýza priameho biddera vyžaduje aj directBidder.

Pokročilé reporty

Vytvárajte plánované alebo okamžité e-mailové reporty

Pokročilé reporty môžete spustiť okamžite alebo ich nastaviť na opakované spúšťanie podľa plánu. Odosielajú sa e-mailom, nevracajú sa priamo v odpovedi API.

Uložiť 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	Zobrazí zoznam uložených pokročilých reportov autentifikovaného účtu.
POST	/api/v2/reports/save-advanced-report	Vytvorí alebo aktualizuje pokročilý report. Vyžaduje reportType, toAddress, immediateRun a aspoň jeden cieľ v adRoots alebo domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Odstráni uložený pokročilý report podľa id.

Typy reportov

adUnit, dimensions, customData

Dimenzie

country, device, os

Frekvencia

daily, weekly, biweekly, monthly

Inventár

Vytvárajte a odstraňujte schválené reklamné jednotky

Zápis do inventára vyžaduje schválený účet Sulvo a kľúč API vygenerovaný vlastníkom účtu s oprávnením inventory:write.

Vytvoriť 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	Vytvorí jednu reklamnú jednotku s doménou, typom, voliteľnou veľkosťou, umiestnením, vlastným názvom a nastavením focusedAd.
PUT	/api/v2/inventory/interstitial-units	Vytvorí intersticiálne reklamné jednotky pre počítače, mobilné zariadenia alebo oboje v danej doméne.
PUT	/api/v2/inventory/auto-sticky-units	Vytvorí jednotky s formátom sticky display, sticky mobile alebo s oboma formátmi v danej doméne.
DELETE	/api/v2/inventory/unit/{adId}	Odstráni reklamnú jednotku, ktorú vlastní autentifikovaný účet.

Podporované typy reklamných jednotiek

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Chyby

Spracovanie chýb

Odpovede auditu mimo rozsahu 2xx a zlyhania API účtu Sulvo vracajú telá JSON určené pre agentov a klientov CLI.

401

Kľúč API v požiadavkách na API účtu chýba, nie je platný alebo jeho platnosť vypršala. Verejný koncový bod auditu kľúč nevyžaduje.

403

Kľúč bol overený, ale nemá potrebné oprávnenie, účet nie je schválený alebo zdroj patrí inému účtu.

503 / 504

Verejná služba auditu je preťažená alebo vypršal časový limit auditu. Skúste to znova neskôr a dodržte hlavičku Retry-After, ak je uvedená.

Obálka chyby auditu

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

Dávate prednosť klientovi z balíka?

Balík npm a nastavenie MCP volajú tieto koncové body za vás a sprístupňujú kompatibilným AI klientom rovnaké audity, reporty a pracovné postupy na správu inventára.

Pozrite si nastavenie