API-viite: Publisher Revenue Audit API

Suorita julkisia julkaisijan tulojen tarkistuksia, hae Sulvon raportteja ja hallinnoi hyväksyttyä julkaisijan inventaariota saman API-rajapinnan kautta, jota CLI ja MCP-palvelin käyttävät.

Isännöity perusosoite

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI:n ja MCP:n käyttöönotto

Perusteet

Perusosoitteet

Julkinen auditoinnin päätepiste ei tarkoituksella vaadi todennusta. Sulvo-tilin raporttikutsut ja inventaariokutsut käyttävät hallintapaneelissa luotua API-avainta.

Julkisen auditoinnin API

POST

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

Sulvo-tilin API-rajapinta

Bearer API-avain

https://surge.sulvo.com/api

Isännöity MCP-päätepiste

MCP

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

Julkinen päätepiste

Suorita tuloauditointi

Käytä tätä päätepistettä julkisiin tietoihin perustuvaan suuntaa antavaan julkaisijan verkkotunnuksen tarkistukseen. Vastaus ei todista tulonmenetystä eikä takaa kasvua. Vahvista havainnot julkaisijapuolen raportoinnilla.

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

Kenttä	Huomiot
input.domain	Pakollinen julkaisijan verkkotunnus tai julkinen isäntänimi. Paljas verkkotunnus muunnetaan HTTPS-muotoon. Yksityiset kohteet, raakamuotoiset IP-osoitteet, sisäiset isäntänimet ja muut kuin vakiomuotoiset portit hylätään.
input.vertical	Valinnainen. Hyväksyy arvot news, sports, entertainment, technology, education, gaming tai other.
input.metrics	Valinnainen julkaisijan antama konteksti hallintapaneelista, kuten täyttöaste, näkyvyys, keskimääräinen CPM, tulot istuntoa kohden, kuukausittaiset sivunäytöt tai kuukausittaiset istunnot.
input.options	Valinnaiset tulosteen ja keruun hallinta-asetukset, kuten format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel ja partnerId.

Todennus

Käytä tilin API-rajapinnoissa Sulvon API-avainta

Luo API-avain Sulvon hallintapaneelissa kohdassa Account Settings. Lähetä se Bearer-tunnisteena Sulvo-tilin API-pyyntöjen yhteydessä.

Authorization-otsake

Authorization: Bearer $SULVO_API_KEY

reports:read

Vaaditaan raporttien vientiin ja tallennettujen raporttien luettelointiin.

reports:write

Vaaditaan edistyneiden raporttien luomiseen, päivittämiseen, suorittamiseen tai poistamiseen.

inventory:write

Vaaditaan mainosyksiköiden luomiseen ja poistamiseen. Tilin on oltava hyväksytty ja sen on omistettava inventaario.

Raportit

Päätepisteet raporttien lukemiseen

Raporttien lukeminen käyttää GET-pyyntöjä Sulvo-tilin API-perusosoitteessa. Pelkät päivämääräarvot tulkitaan koko UTC-päivän rajoiksi.

Raporttipyyntö

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	Päivittäinen tulosyhteenveto. Tukee päivämäärän, verkkotunnuksen, mainosjuuren ja palveluntarjoajan suodattimia.
GET	/api/v1/reports/by-date-and-ad-unit	Päivittäiset tulokset mainosyksiköittäin ryhmiteltyinä.
GET	/api/v1/reports/by-domain-and-ad-unit	Verkkotunnuksen ja mainosyksikön tuloserittely.
GET	/api/v1/reports/bot-filtering	Bottiliikenteen suodatusraportti tilin liikenteen laadun tarkasteluun.
GET	/api/v1/reports/bot-scores	Bottiliikenteen pisteytysraportti päivämäärän ja siihen liittyvien ulottuvuuksien mukaan.
GET	/api/v1/reports/invalid-activity	Virheellisen toiminnan raportointi. Tavallista päivämäärä- tai verkkotunnuskyselyä ei tarvita.
GET	/api/v1/reports/direct-bidder-analysis	Suoran tarjoajan raportti. Edellyttää directBidder-arvoa, ja siihen voi sisällyttää start- ja end-arvot.
GET	/api/v1/inventory/ad-units-by-domain	Mainosyksiköiden inventaario verkkotunnuksittain ryhmiteltynä.

Yleiset kyselyparametrit: start, end, toistettava domains, toistettava adRoots ja adProvider. Suoran tarjoajan analyysi edellyttää lisäksi arvoa directBidder.

Edistyneet raportit

Luo ajastettuja tai heti lähetettäviä sähköpostiraportteja

Edistyneet raportit voidaan suorittaa heti tai toistuvasti aikataulun mukaan. Ne toimitetaan sähköpostitse sen sijaan, että ne palautettaisiin suoraan vastauksessa.

Tallenna edistynyt raportti

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	Luettele todennetun tilin tallennetut edistyneet raportit.
POST	/api/v2/reports/save-advanced-report	Luo tai päivitä edistynyt raportti. Edellyttää arvoja reportType, toAddress ja immediateRun sekä vähintään yhtä kohdetta: adRoots tai domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Poista tallennettu edistynyt raportti tunnisteen perusteella.

Raporttityypit

adUnit, dimensions, customData

Ulottuvuudet

country, device, os

Toistuvuus

daily, weekly, biweekly, monthly

Inventaario

Luo ja poista hyväksyttyjä mainosyksiköitä

Inventaariomuutokset edellyttävät hyväksyttyä Sulvo-tiliä ja omistajan luomaa API-avainta, jolla on inventory:write-laajuus.

Luo mainosyksikkö

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	Luo yksi mainosyksikkö, jonka asetuksia ovat domain, type, valinnainen size, placement, custom name ja focusedAd.
PUT	/api/v2/inventory/interstitial-units	Luo verkkotunnukselle tietokone- ja/tai mobiilikäyttöön tarkoitettuja välisivumainosyksiköitä.
PUT	/api/v2/inventory/auto-sticky-units	Luo verkkotunnukselle kiinnittyviä display- ja/tai mobiiliyksiköitä.
DELETE	/api/v2/inventory/unit/{adId}	Poista todennetun tilin omistama mainosyksikkö.

Tuetut mainosyksikkötyypit

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Virheet

Virheiden käsittely

Auditoinnin muut kuin 2xx-vastaukset sekä Sulvo-tilin API-virheet palauttavat JSON-rungon, joka on suunniteltu tekoälyagenttien ja CLI-asiakasohjelmien käyttöön.

401

Tilin API-kutsuista puuttuu API-avain, se on virheellinen tai vanhentunut. Julkinen auditoinnin päätepiste ei vaadi avainta.

403

Avain todennettiin, mutta siltä puuttuu vaadittu laajuus, tiliä ei ole hyväksytty tai resurssi kuuluu toiselle tilille.

503 / 504

Julkinen auditointipalvelu on ruuhkautunut tai auditointi aikakatkaistiin. Yritä myöhemmin uudelleen ja noudata Retry-After-arvoa, jos se on saatavilla.

Auditoinnin virhevastauksen rakenne

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

Haluatko mieluummin valmiiksi paketoidun asiakasohjelman?

MCP-käyttöönotto ja npm-paketti kutsuvat näitä päätepisteitä puolestasi ja tarjoavat samat auditointi-, raportointi- ja inventaariotyönkulut yhteensopiville tekoälyasiakasohjelmille.

Katso käyttöönotto