Kiadói bevételi audit API

Futtasson nyilvános kiadói bevételi előszűréseket, kérje le a Sulvo-jelentéseket, és kezelje a jóváhagyott kiadói hirdetési készletet ugyanazon az API-felületen keresztül, amelyet a CLI és az MCP-szerver is használ.

Hosztolt alap-URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI- és MCP-beállítás

Alapok

Alap URL-ek

A nyilvános auditvégpont szándékosan nem igényel hitelesítést. A Sulvo-fiók jelentéseihez és készlettel kapcsolatos API-hívásaihoz a vezérlőpulton létrehozott API-kulcs szükséges.

Nyilvános audit API

POST

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

Sulvo-fiók API

Bearer API-kulcs

https://surge.sulvo.com/api

Hosztolt MCP-végpont

MCP

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

Nyilvános végpont

Bevételi audit futtatása

Ezt a végpontot a kiadói domain nyilvánosan elérhető adatai alapján történő, tájékoztató jellegű előszűrésre használja. A válasz nem bizonyítja a bevételkiesést, és nem garantál bevételnövekedést; az eredményeket ellenőrizze a kiadói oldali jelentések alapján.

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

Mező	Megjegyzések
input.domain	Kötelező kiadói domain vagy nyilvános hoszt. Az önállóan megadott domainneveket HTTPS-re alakítja. A privát célpontokat, a nyers IP-címeket, a belső hosztokat és a nem szabványos portokat elutasítja.
input.vertical	Nem kötelező. A következő értékek fogadhatók el: news, sports, entertainment, technology, education, gaming vagy other.
input.metrics	Nem kötelező, a kiadó által megadott vezérlőpulti adatok, például fill rate, láthatóság, átlagos CPM, munkamenetenkénti bevétel, havi oldalmegtekintések vagy havi munkamenetek.
input.options	Nem kötelező kimeneti és adatgyűjtési beállítások, többek között format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel és partnerId.

Hitelesítés

A Sulvo-fiók API-jaihoz használjon API-kulcsot

Hozzon létre API-kulcsot a Sulvo vezérlőpultján, a Fiókbeállítások alatt. A Sulvo-fiók API-kéréseiben Bearer tokenként küldje el.

Authorization fejléc

Authorization: Bearer $SULVO_API_KEY

reports:read

A jelentések exportálásához és a mentett jelentések listázásához szükséges.

reports:write

Haladó jelentések létrehozásához, frissítéséhez, futtatásához vagy törléséhez szükséges.

inventory:write

Hirdetési egységek létrehozásához és törléséhez szükséges. A fióknak jóváhagyottnak kell lennie, és a készletnek a fiók tulajdonában kell állnia.

Jelentések

Jelentésvégpontok lekérése

A jelentések lekérésekor a GET-kérések a Sulvo-fiók API-alapcímét használják. A csak dátumot tartalmazó értékek teljes UTC-napra érvényes időhatárként értelmeződnek.

Jelentéskérés

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	Napi teljesítmény-összesítő. Szűrhető date, domain, ad root és provider szerint.
GET	/api/v1/reports/by-date-and-ad-unit	Napi teljesítmény hirdetési egység szerint csoportosítva.
GET	/api/v1/reports/by-domain-and-ad-unit	Teljesítménybontás domain és hirdetési egység szerint.
GET	/api/v1/reports/bot-filtering	Botforgalom-szűrési jelentés a fiók forgalmi minőségének áttekintéséhez.
GET	/api/v1/reports/bot-scores	Botpontszám-jelentés dátum és kapcsolódó dimenziók szerint.
GET	/api/v1/reports/invalid-activity	Érvénytelen aktivitások jelentése. Nincs szükség a szokásos date/domain lekérdezési paraméterekre.
GET	/api/v1/reports/direct-bidder-analysis	Közvetlen ajánlattevői jelentés. A directBidder megadása kötelező; a start és end paraméterek is megadhatók.
GET	/api/v1/inventory/ad-units-by-domain	Domain szerint csoportosított hirdetési egységek készlete.

Gyakori lekérdezési paraméterek: start, end, ismételhető domains, ismételhető adRoots és adProvider. A közvetlen ajánlattevő elemzéséhez a directBidder megadása is szükséges.

Haladó jelentések

Ütemezett vagy azonnali e-mail-jelentések létrehozása

A haladó jelentések azonnal lefuttathatók, vagy ütemezetten ismétlődhetnek. E-mailben érkeznek meg, nem pedig közvetlenül a válasz részeként.

Haladó jelentés mentése

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	A hitelesített fiók mentett haladó jelentéseinek listázása.
POST	/api/v2/reports/save-advanced-report	Haladó jelentés létrehozása vagy frissítése. A reportType, toAddress és immediateRun megadása, valamint legalább egy adRoots vagy domains célpont szükséges.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Mentett haladó jelentés törlése az id alapján.

Jelentéstípusok

adUnit, dimensions, customData

Dimenziók

country, device, os

Gyakoriság

daily, weekly, biweekly, monthly

Készlet

Jóváhagyott hirdetési egységek létrehozása és törlése

A készlet módosításához jóváhagyott Sulvo-fiók és a fiók tulajdonosa által létrehozott, inventory:write jogosultsági körrel rendelkező API-kulcs szükséges.

Hirdetési egység létrehozása

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	Egyetlen hirdetési egység létrehozása domain, type, opcionális size, placement, custom name és focusedAd beállításokkal.
PUT	/api/v2/inventory/interstitial-units	Asztali és/vagy mobil közbeiktatott hirdetési egységek létrehozása egy domainhez.
PUT	/api/v2/inventory/auto-sticky-units	Sticky display és/vagy sticky mobil hirdetési egységek létrehozása egy domainhez.
DELETE	/api/v2/inventory/unit/{adId}	A hitelesített fiók tulajdonában lévő hirdetési egység törlése.

Támogatott hirdetési egységtípusok

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Hibák

Hibakezelés

A nem 2xx auditválaszok és a Sulvo-fiók API-hibái olyan JSON-törzseket adnak vissza, amelyeket automatizált ügynökök és CLI-kliensek számára alakítottak ki.

401

A fiók API-hívásaihoz hiányzik, érvénytelen vagy lejárt az API-kulcs. A nyilvános auditvégponthoz nem szükséges kulcs.

403

Az API-kulcs hitelesítése sikerült, de nem rendelkezik a szükséges jogosultsági körrel, a fiók nincs jóváhagyva, vagy az erőforrás egy másik fiókhoz tartozik.

503 / 504

A nyilvános audit szolgáltatás túlterhelt, vagy az audit időtúllépés miatt megszakadt. Próbálja újra később, és ha a Retry-After fejléc jelen van, tartsa be annak értékét.

Audit hibaválasz-struktúra

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

Inkább egy csomagként telepíthető klienst választana?

Az npm-csomag és az MCP-beállítás Ön helyett hívják meg ezeket a végpontokat, és a kompatibilis AI-kliensek számára is elérhetővé teszik ugyanazokat az audit-, jelentés- és készletkezelési munkafolyamatokat.

Beállítás megtekintése