Revizija prihodkov založnika prek API-ja

Z istim API-jem kot CLI in strežnik MCP zaženite javne preglede prihodkov založnikov, pridobite poročila Sulvo in upravljajte odobreni inventar založnikov.

Gostovani osnovni naslov

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsNastavitev CLI-ja in MCP-ja

Osnove

Osnovni URL-ji

Javna končna točka revizije namerno ne zahteva preverjanja pristnosti. Za poročila računov Sulvo in klice inventarja uporabite ključ API, ustvarjen na nadzorni plošči.

Javni API za revizijo

POST

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

API za račun Sulvo

Ključ API kot žeton Bearer

https://surge.sulvo.com/api

Gostovana končna točka MCP

MCP

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

Javna končna točka

Zaženite revizijo prihodkov

To končno točko uporabite za orientacijski pregled javno dostopnih dokazov za domeno založnika. Odgovor ni dokaz izgube prihodkov ali zagotovljenega povečanja. Ugotovitve preverite s poročanjem na strani založnika.

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	Opombe
input.domain	Obvezna domena založnika ali javni gostitelj. Gole domene se pretvorijo v HTTPS. Zasebni cilji, surovi naslovi IP, notranji gostitelji in nestandardna vrata so zavrnjeni.
input.vertical	Izbirno. Sprejema news, sports, entertainment, technology, education, gaming ali other.
input.metrics	Izbirni kontekst nadzorne plošče, ki ga posreduje založnik, na primer stopnja zapolnjenosti, vidljivost oglasa, povprečni CPM, prihodek na sejo, mesečni ogledi strani ali mesečno število sej.
input.options	Izbirne možnosti izhoda in nadzora zbiranja, vključno s temi polji: format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel in partnerId.

Preverjanje pristnosti

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

Ključ API ustvarite na nadzorni plošči Sulvo v razdelku Nastavitve računa. Pri zahtevah za API računa Sulvo ga pošljite kot žeton Bearer.

Glava Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Obseg dovoljenj, potreben za izvoz poročil in prikaz seznama shranjenih poročil.

reports:write

Obseg dovoljenj, potreben za ustvarjanje, posodabljanje, zagon ali brisanje naprednih poročil.

inventory:write

Obseg dovoljenj, potreben za ustvarjanje in brisanje oglasnih enot. Račun mora biti odobren in imeti v lasti inventar.

Poročila

Končne točke za branje poročil

Zahteve GET za branje poročil uporabljajo osnovni naslov API-ja računa Sulvo. Datumske vrednosti brez časa se razumejo kot celoten interval dneva po UTC.

Zahteva za poročilo

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 povzetek uspešnosti. Podpira filtre date, domain, ad root in provider.
GET	/api/v1/reports/by-date-and-ad-unit	Dnevna uspešnost, razvrščena po oglasni enoti.
GET	/api/v1/reports/by-domain-and-ad-unit	Pregled uspešnosti po domeni in oglasni enoti.
GET	/api/v1/reports/bot-filtering	Poročilo o filtriranju botov za pregled kakovosti prometa računa.
GET	/api/v1/reports/bot-scores	Poročanje o ocenah botov po datumu in povezanih dimenzijah.
GET	/api/v1/reports/invalid-activity	Poročanje o neveljavni dejavnosti. Običajna poizvedba date/domain ni potrebna.
GET	/api/v1/reports/direct-bidder-analysis	Poročilo o neposrednem ponudniku. Zahteva directBidder, lahko pa vključuje tudi start in end.
GET	/api/v1/inventory/ad-units-by-domain	Inventar oglasnih enot, razvrščen po domeni.

Pogosti parametri poizvedbe: start, end, ponovljivi parameter domains, ponovljivi parameter adRoots in adProvider. Analiza neposrednega ponudnika zahteva tudi directBidder.

Napredna poročila

Ustvarite načrtovana ali takojšnja e-poštna poročila

Napredna poročila se lahko zaženejo takoj ali ponavljajo po urniku. Dostavijo se po e-pošti, namesto da bi se vrnila neposredno v odgovoru.

Shranite napredno poročilo

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 shranjena napredna poročila za preverjeni račun.
POST	/api/v2/reports/save-advanced-report	Ustvarite ali posodobite napredno poročilo. Zahteva reportType, toAddress, immediateRun in vsaj en cilj adRoots ali domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Izbrišite shranjeno napredno poročilo z vrednostjo id.

Vrste poročil

adUnit, dimensions, customData

Dimenzije

country, device, os

Pogostost

daily, weekly, biweekly, monthly

Inventar

Ustvarite in izbrišite odobrene oglasne enote

Za spremembe inventarja sta potrebna odobren račun Sulvo in ključ API, ki ga je ustvaril lastnik ter ima obseg inventory:write.

Ustvarite oglasno enoto

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	Ustvarite posamezno oglasno enoto z nastavitvami domain, type, size (izbirno), placement, custom name in focusedAd.
PUT	/api/v2/inventory/interstitial-units	Ustvarite namizne in/ali mobilne enote Interstitial za domeno.
PUT	/api/v2/inventory/auto-sticky-units	Ustvarite enote Sticky za prikazne oglase in/ali mobilne naprave za domeno.
DELETE	/api/v2/inventory/unit/{adId}	Izbrišite oglasno enoto, ki je v lasti preverjenega računa.

Podprte vrste oglasnih enot

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Napake

Obravnava napak

Neuspešni odgovori revizije s statusom, ki ni 2xx, in napake API-ja računa Sulvo vrnejo telesa JSON, namenjena odjemalcem agentov in CLI-ja.

401

Ključ API za klice API-ja računa manjka, ni veljaven ali je potekel. Javna končna točka revizije ključa ne zahteva.

403

Ključ je bil preverjen, vendar nima zahtevanega obsega dovoljenj, račun ni odobren ali pa vir pripada drugemu računu.

503 / 504

Storitev javne revizije je preobremenjena ali pa se je čas za revizijo iztekel. Poskusite znova pozneje in upoštevajte Retry-After, kadar je na voljo.

Ovojnica napake revizije

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

Bi raje uporabljali vnaprej pripravljenega odjemalca?

Paket npm in nastavitev MCP namesto Vas kličeta te končne točke ter združljivim odjemalcem AI omogočata enake postopke za revizije, poročila in inventar.

Oglejte si nastavitev