Publisher Revenue Audit API

Atlikite viešą leidėjo pajamų patikrą, gaukite Sulvo ataskaitas ir tvarkykite patvirtintus leidėjo reklamos plotus naudodami tą pačią API, kuria veikia CLI ir MCP serveris.

Talpinamas pagrindinis API adresas

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI ir MCP sąranka

Pagrindai

Pagrindiniai adresai

Viešasis audito galinis taškas sąmoningai veikia be autentifikavimo. Sulvo paskyros ataskaitoms ir reklamos plotų užklausoms reikia valdymo skydelyje sugeneruoto API rakto.

Viešojo audito API

POST

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

Sulvo paskyros API

Bearer API raktas

https://surge.sulvo.com/api

Talpinamas MCP galinis taškas

MCP

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

Viešasis galinis taškas

Atlikite pajamų auditą

Naudokite šį galinį tašką orientacinei viešų duomenų patikrai pagal leidėjo domeną. Atsakymas neįrodo prarastų pajamų ir negarantuoja jų padidėjimo. Radinius patikrinkite pagal leidėjo ataskaitų duomenis.

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

Laukas	Pastabos
input.domain	Privalomas leidėjo domenas arba viešasis serverio adresas. Domenai be protokolo automatiškai papildomi HTTPS. Privatūs adresai, tiesioginiai IP adresai, vidiniai serveriai ir nestandartiniai prievadai atmetami.
input.vertical	Pasirenkama. Priimamos reikšmės: news, sports, entertainment, technology, education, gaming arba other.
input.metrics	Pasirenkama paskyros valdymo skydelio informacija, kurią pateikia leidėjas, pavyzdžiui, užpildymo rodiklis, matomumas, vidutinis CPM, pajamos per seansą, mėnesio puslapių peržiūros arba mėnesio seansai.
input.options	Pasirenkami išvesties ir duomenų rinkimo nustatymai, įskaitant format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel ir partnerId.

Autentifikavimas

Paskyros API naudokite Sulvo API raktą

Sugeneruokite API raktą Sulvo valdymo skydelio paskyros nustatymuose. Siųskite jį kaip Bearer žetoną su Sulvo paskyros API užklausomis.

Authorization antraštė

Authorization: Bearer $SULVO_API_KEY

reports:read

Reikalinga ataskaitoms eksportuoti ir išsaugotų ataskaitų sąrašui gauti.

reports:write

Reikalinga išplėstinėms ataskaitoms kurti, atnaujinti, vykdyti arba ištrinti.

inventory:write

Reikalinga reklamos vienetams kurti ir ištrinti. Paskyra turi būti patvirtinta ir jai turi priklausyti šie reklamos plotai.

Ataskaitos

Ataskaitų gavimo galiniai taškai

Ataskaitų peržiūros užklausoms naudojamas GET metodas su Sulvo paskyros API pagrindiniu adresu. Vien datos reikšmės laikomos visos UTC paros ribomis.

Ataskaitos užklausa

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	Dienos efektyvumo suvestinė. Galima filtruoti pagal datą, domeną, ad root ir teikėją.
GET	/api/v1/reports/by-date-and-ad-unit	Dienos efektyvumo duomenys, suskirstyti pagal reklamos vienetą.
GET	/api/v1/reports/by-domain-and-ad-unit	Domeno ir reklamos vienetų efektyvumo išskaidymas.
GET	/api/v1/reports/bot-filtering	Botų filtravimo ataskaita paskyros srauto kokybei įvertinti.
GET	/api/v1/reports/bot-scores	Botų įverčių ataskaita pagal datą ir susijusius pjūvius.
GET	/api/v1/reports/invalid-activity	Netinkamos veiklos ataskaita. Standartinių datos ar domeno užklausos parametrų nereikia.
GET	/api/v1/reports/direct-bidder-analysis	Tiesioginio siūlytojo ataskaita. Reikalingas directBidder parametras; taip pat galima nurodyti start ir end.
GET	/api/v1/inventory/ad-units-by-domain	Reklamos vienetų sąrašas pagal domeną.

Bendrieji užklausos parametrai: start, end, kartojamas domains, kartojamas adRoots ir adProvider. Tiesioginio siūlytojo analizei taip pat būtinas directBidder.

Išplėstinės ataskaitos

Kurkite suplanuotas arba iškart siunčiamas ataskaitas el. paštu

Išplėstines ataskaitas galima vykdyti iškart arba periodiškai pagal tvarkaraštį. Jos siunčiamos el. paštu, o ne pateikiamos tiesiogiai atsakyme.

Išsaugoti išplėstinę ataskaitą

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	Pateikiamas autentifikuotos paskyros išsaugotų išplėstinių ataskaitų sąrašas.
POST	/api/v2/reports/save-advanced-report	Sukuriama arba atnaujinama išplėstinė ataskaita. Reikalingi reportType, toAddress, immediateRun ir bent vienas taikinys viename iš laukų adRoots arba domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Ištrinama išsaugota išplėstinė ataskaita pagal id.

Ataskaitų tipai

adUnit, dimensions, customData

Pjūviai

country, device, os

Dažnumas

daily, weekly, biweekly, monthly

Reklamos plotai

Kurti ir ištrinti patvirtintus reklamos vienetus

Norint keisti reklamos plotų duomenis, reikia patvirtintos Sulvo paskyros ir savininko sukurto API rakto, turinčio inventory:write prieigos teisę.

Sukurti reklamos vienetą

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	Sukurkite vieną reklamos vienetą ir nurodykite domain, type, placement, custom name bei focusedAd nustatymus; size laukas pasirenkamas.
PUT	/api/v2/inventory/interstitial-units	Sukuriami staliniams kompiuteriams ir (arba) mobiliesiems įrenginiams skirti tarpiniai reklamos vienetai domenui.
PUT	/api/v2/inventory/auto-sticky-units	Domenui sukurkite lipnius vaizdinės reklamos ir (arba) lipnius mobiliuosius reklamos vienetus.
DELETE	/api/v2/inventory/unit/{adId}	Ištrinamas autentifikuotai paskyrai priklausantis reklamos vienetas.

Palaikomi reklamos vienetų tipai

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Klaidos

Klaidų apdorojimas

Į audito užklausas, kurios grąžina ne 2xx atsakymą, ir į Sulvo paskyros API klaidas atsakoma JSON turiniu, pritaikytu agentų ir CLI klientams.

401

Paskyros API užklausose API rakto nėra, jis netinkamas arba nebegalioja. Viešajam audito galiniam taškui rakto nereikia.

403

Raktas autentifikuotas, bet neturi reikiamos prieigos teisės, paskyra nepatvirtinta arba išteklius priklauso kitai paskyrai.

503 / 504

Viešojo audito paslauga perkrauta arba skirtas audito laikas baigėsi. Bandykite vėliau ir, jei pateikta, laikykitės Retry-After reikšmės.

Audito klaidos duomenys

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

Norėtumėte paruošto kliento?

Naudojant npm paketą ir MCP sąranką, šie galiniai taškai iškviečiami už jus, o suderinami DI klientai gali naudotis tomis pačiomis audito, ataskaitų ir reklamos plotų darbo eigomis.

Peržiūrėti sąranką