Dokumentacija: Publisher Revenue Audit API

Pokrenite javne provjere prihoda izdavača, dohvatite Sulvo izvješća i upravljajte odobrenim inventarom izdavača putem istog API sučelja koje koriste CLI i MCP poslužitelj.

Hostirana osnovna adresa

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsPostavljanje CLI-ja i MCP-a

Osnove

Osnovni URL-ovi

Javni endpoint za reviziju namjerno ne zahtijeva autentifikaciju. Za Sulvo izvješća računa i pozive za pristup inventaru upotrebljava se API ključ generiran na nadzornoj ploči.

Javni API za reviziju

POST

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

API za Sulvo račun

Bearer API ključ

https://surge.sulvo.com/api

Hostirani MCP endpoint

MCP

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

Javni endpoint

Pokrenite reviziju prihoda

Ovaj endpoint upotrijebite za orijentacijsku provjeru javno dostupnih pokazatelja za domenu izdavača. Odgovor nije dokaz gubitka prihoda ni jamstvo rasta; provjerite nalaze u izvješćima na strani izdavač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
      }
    }
  }'

Polje	Napomene
input.domain	Obavezna domena izdavača ili javni host. Gole domene automatski se normaliziraju na HTTPS. Privatna odredišta, izravne IP adrese, interni hostovi i nestandardni portovi odbijaju se.
input.vertical	Neobavezno. Prihvaća news, sports, entertainment, technology, education, gaming ili other.
input.metrics	Neobavezni kontekst s nadzorne ploče koji je dao izdavač, kao što su stopa popunjenosti, vidljivost, prosječni CPM, prihod po sesiji, mjesečni prikazi stranica ili mjesečne sesije.
input.options	Neobavezne kontrole izlaza i prikupljanja, uključujući format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel i partnerId.

Autentifikacija

Za API-je računa upotrijebite Sulvo API ključ

Generirajte API ključ na Sulvovoj nadzornoj ploči, u odjeljku Postavke računa. Šaljite ga kao Bearer token u zahtjevima prema API-ju Sulvo računa.

Zaglavlje Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Obavezno za izvoz izvješća i prikaz spremljenih izvješća.

reports:write

Obavezno za izradu, ažuriranje, pokretanje ili brisanje naprednih izvješća.

inventory:write

Obavezno za izradu i brisanje oglasnih jedinica. Račun mora biti odobren i mora biti vlasnik inventara.

Izvješća

Endpointi za čitanje izvješća

Za čitanje izvješća šalju se GET zahtjevi na osnovnu adresu API-ja Sulvo računa. Vrijednosti koje sadrže samo datum tumače se kao cijeli dan u UTC-u.

Zahtjev za izvješće

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	Dnevni sažetak učinka. Podržava filtre za datum, domenu, korijen oglasa i pružatelja.
GET	/api/v1/reports/by-date-and-ad-unit	Dnevni učinak grupiran prema oglasnoj jedinici.
GET	/api/v1/reports/by-domain-and-ad-unit	Pregled učinka prema domeni i oglasnoj jedinici.
GET	/api/v1/reports/bot-filtering	Izvješće o filtriranju botova za provjeru kvalitete prometa računa.
GET	/api/v1/reports/bot-scores	Izvješćivanje o ocjenama botova prema datumu i povezanim dimenzijama.
GET	/api/v1/reports/invalid-activity	Izvješćivanje o nevaljanoj aktivnosti. Nije potreban standardni upit s datumom ili domenom.
GET	/api/v1/reports/direct-bidder-analysis	Izvješće o izravnom ponuditelju. Zahtijeva directBidder, a može uključivati start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventar oglasnih jedinica grupiran prema domeni.

Uobičajeni parametri upita: start, end, višekratni domains, višekratni adRoots i adProvider. Analiza izravnog ponuditelja zahtijeva i directBidder.

Napredna izvješća

Izradite zakazana izvješća e-poštom ili ih odmah pošaljite

Napredna izvješća mogu se pokrenuti odmah ili se mogu ponavljati prema rasporedu. Šalju se e-poštom umjesto da se vraćaju izravno u odgovoru.

Spremite napredno izvješće

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	Prikažite spremljena napredna izvješća za autentificirani račun.
POST	/api/v2/reports/save-advanced-report	Izradite ili ažurirajte napredno izvješće. Potrebni su reportType, toAddress, immediateRun i najmanje jedno odredište adRoots ili domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Izbrišite spremljeno napredno izvješće prema ID-u.

Vrste izvješća

adUnit, dimensions, customData

Dimenzije

country, device, os

Učestalost

daily, weekly, biweekly, monthly

Inventar

Izradite i izbrišite odobrene oglasne jedinice

Za izmjene inventara potreban je odobren Sulvo račun i API ključ koji je izradio vlasnik te kojem je dodijeljen opseg inventory:write.

Izradite oglasnu jedinicu

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	Izradite jednu oglasnu jedinicu s domenom, vrstom, neobaveznom veličinom, pozicijom, prilagođenim nazivom i postavkama focusedAd.
PUT	/api/v2/inventory/interstitial-units	Izradite interstitial jedinice za stolna računala i/ili mobilne uređaje za domenu.
PUT	/api/v2/inventory/auto-sticky-units	Izradite sticky display jedinice i/ili sticky jedinice za mobilne uređaje za domenu.
DELETE	/api/v2/inventory/unit/{adId}	Izbrišite oglasnu jedinicu u vlasništvu autentificiranog računa.

Podržane vrste oglasnih jedinica

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Pogreške

Obrada pogrešaka

Odgovori revizije koji nisu 2xx i pogreške API-ja Sulvo računa vraćaju JSON tijela namijenjena agentskim i CLI klijentima.

401

Za pozive prema API-ju računa nedostaje API ključ ili je nevažeći ili mu je istekao rok valjanosti. Javni endpoint za reviziju ne zahtijeva ključ.

403

Autentifikacija ključem uspjela je, ali ključ nema potreban opseg dopuštenja, račun nije odobren ili je resurs u vlasništvu drugog računa.

503 / 504

Javni servis za reviziju preopterećen je ili je isteklo vrijeme za reviziju. Pokušajte ponovno kasnije i poštujte Retry-After ako je naveden.

Omotnica pogreške revizije

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

Biste li radije koristili klijent spreman za upotrebu?

npm paket i postavljanje MCP-a pozivaju ove endpointe umjesto vas i kompatibilnim AI klijentima omogućuju iste tijekove rada za reviziju, izvješća i inventar.

Pogledajte postavljanje