L’API de Publisher Revenue Audit

Feu avaluacions públiques orientatives dels ingressos dels editors, obteniu els informes de Sulvo i gestioneu l’inventari aprovat dels editors mitjançant la mateixa interfície de l’API que fan servir la CLI i el servidor MCP.

URL base allotjada

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsConfiguració de la CLI i l’MCP

Conceptes bàsics

URL base

L’endpoint públic d’auditoria no requereix autenticació per disseny. Les sol·licituds d’informes i d’inventari del compte de Sulvo fan servir una clau de l’API generada al tauler.

API pública d’auditoria

POST

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

API del compte de Sulvo

Clau d’API de tipus Bearer

https://surge.sulvo.com/api

Endpoint MCP allotjat

MCP

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

Endpoint públic

Feu una auditoria d’ingressos

Feu servir aquest endpoint per obtenir una avaluació orientativa basada en proves públiques d’un domini d’editor. La resposta no demostra una pèrdua d’ingressos ni garanteix un augment; valideu els resultats amb els vostres informes com a editor.

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

Camp	Notes
input.domain	Cal indicar un domini d’un editor o un host públic. Els dominis sense esquema s’ajusten a HTTPS. Es rebutgen les destinacions privades, les adreces IP en brut, els hosts interns i els ports no estàndard.
input.vertical	Opcional. Accepta els valors news, sports, entertainment, technology, education, gaming o other.
input.metrics	Opcional. Context del tauler proporcionat per l’editor, com ara la taxa d’ompliment, la visibilitat, el CPM mitjà, els ingressos per sessió, les visualitzacions de pàgina mensuals o les sessions mensuals.
input.options	Controls opcionals de sortida i recollida, com ara format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel i partnerId.

Autenticació

Feu servir una clau de l’API de Sulvo per a les API del compte

Genereu una clau de l’API al tauler de Sulvo, a la secció «Configuració del compte». Envieu-la com a token Bearer a les sol·licituds de l’API del compte de Sulvo.

Capçalera Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Necessari per exportar informes i llistar informes desats.

reports:write

Necessari per crear, actualitzar, executar o suprimir informes avançats.

inventory:write

Necessari per crear i suprimir unitats publicitàries. El compte ha d’estar aprovat i ser titular de l’inventari.

Informes

Consulteu els endpoints d’informes

Els endpoints de lectura d’informes fan servir sol·licituds GET a la URL base de l’API del compte de Sulvo. Els valors que només indiquen una data s’interpreten com els límits del dia complet en UTC.

Sol·licitud d’informe

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	Resum diari del rendiment. Admet els filtres date, domain, ad root i provider.
GET	/api/v1/reports/by-date-and-ad-unit	Rendiment diari agrupat per unitat publicitària.
GET	/api/v1/reports/by-domain-and-ad-unit	Desglossament del rendiment per domini i unitat publicitària.
GET	/api/v1/reports/bot-filtering	Informe de filtratge de bots per revisar la qualitat del trànsit del compte.
GET	/api/v1/reports/bot-scores	Informes de puntuació de bots per data i dimensions relacionades.
GET	/api/v1/reports/invalid-activity	Informe d’activitat no vàlida. No cal cap consulta estàndard per data ni domini.
GET	/api/v1/reports/direct-bidder-analysis	Informe de licitadors directes. Requereix directBidder i pot incloure start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventari d’unitats publicitàries agrupat per domini.

Paràmetres de consulta habituals: start, end, domains (repetible), adRoots (repetible) i adProvider. L’anàlisi de licitadors directes també requereix directBidder.

Informes avançats

Creeu informes per correu electrònic, programats o immediats

Els informes avançats es poden executar immediatament o repetir-se segons una programació. Es lliuren per correu electrònic en lloc d’incloure’s directament a la resposta.

Desa l’informe avançat

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	Llisteu els informes avançats desats del compte autenticat.
POST	/api/v2/reports/save-advanced-report	Creeu o actualitzeu un informe avançat. Requereix reportType, toAddress, immediateRun i com a mínim un objectiu adRoots o domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Suprimiu un informe avançat desat mitjançant id.

Tipus d’informe

adUnit, dimensions, customData

Dimensions

country, device, os

Freqüència

daily, weekly, biweekly, monthly

Inventari

Creeu i suprimiu unitats publicitàries aprovades

Les operacions d’escriptura de l’inventari requereixen un compte de Sulvo aprovat i una clau de l’API creada pel titular del compte amb l’àmbit inventory:write.

Crea una unitat publicitària

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	Creeu una unitat publicitària amb domain, type, size opcional, placement, custom name i els paràmetres de focusedAd.
PUT	/api/v2/inventory/interstitial-units	Creeu unitats intersticials per a escriptori, mòbil o tots dos, per a un domini.
PUT	/api/v2/inventory/auto-sticky-units	Creeu unitats de display fixes, unitats mòbils fixes o totes dues per a un domini.
DELETE	/api/v2/inventory/unit/{adId}	Suprimiu una unitat publicitària propietat del compte autenticat.

Tipus d’unitat publicitària admesos

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Errors

Gestió d’errors

Les respostes d’auditoria diferents de 2xx i els errors de l’API del compte de Sulvo retornen cossos JSON pensats per a agents i clients de la CLI.

401

La clau de l’API falta, no és vàlida o ha caducat per a les crides a l’API del compte. L’endpoint públic d’auditoria no requereix cap clau.

403

La clau s’ha autenticat, però no té l’àmbit requerit, el compte no està aprovat o el recurs pertany a un altre compte.

503 / 504

El servei públic d’auditoria està saturat o l’auditoria ha superat el temps d’espera. Torneu-ho a provar més tard i respecteu Retry-After quan aparegui.

Estructura de la resposta d’error d’auditoria

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

Preferiu un client empaquetat?

El paquet npm i la configuració de l’MCP invoquen aquests endpoints en lloc vostre i ofereixen els mateixos fluxos de treball d’auditoria, informes i inventari a clients d’IA compatibles.

Vegeu la guia