Documentazione di Publisher Revenue Audit API

Esegui controlli pubblici sui ricavi dei publisher, recupera i report Sulvo e gestisci l’inventario approvato dei publisher tramite la stessa API usata dalla CLI e dal server MCP.

URL di base ospitato

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsConfigurazione di CLI e MCP

Nozioni di base

URL di base

L’endpoint di audit pubblico, per scelta, non richiede l’autenticazione. I report dell’account Sulvo e le richieste di inventario usano una chiave API generata dalla dashboard.

API di audit pubblico

POST

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

API dell’account Sulvo

Chiave API Bearer

https://surge.sulvo.com/api

Endpoint MCP ospitato

MCP

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

Endpoint pubblico

Esegui un audit dei ricavi

Usa questo endpoint per un controllo indicativo dei dati pubblici relativi al dominio di un publisher. La risposta non prova una perdita di ricavi né garantisce un aumento. Convalida i risultati con i report lato publisher.

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

Campo	Note
input.domain	Dominio del publisher o host pubblico obbligatorio. I domini senza protocollo vengono convertiti automaticamente in HTTPS. Destinazioni private, IP grezzi, host interni e porte non standard vengono rifiutati.
input.vertical	Facoltativo. Accetta news, sports, entertainment, technology, education, gaming o other.
input.metrics	Contesto facoltativo fornito dal publisher tramite dashboard, ad esempio fill rate, viewability, CPM medio, ricavi per sessione, pageview mensili o sessioni mensili.
input.options	Controlli facoltativi per output e raccolta dati, tra cui format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel e partnerId.

Autenticazione

Usa una chiave API Sulvo per le API dell’account

Genera una chiave API nella dashboard Sulvo, in Account Settings. Inviala come token Bearer nelle richieste alle API dell’account Sulvo.

Header Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Obbligatorio per esportare i report e visualizzare l’elenco dei report salvati.

reports:write

Obbligatorio per creare, aggiornare, eseguire o eliminare report avanzati.

inventory:write

Obbligatorio per creare ed eliminare unità pubblicitarie. L’account deve essere approvato e possedere l’inventario.

Report

Endpoint di lettura dei report

Le richieste GET per leggere i report usano la base dell’API dell’account Sulvo. I valori che indicano solo una data vengono interpretati come limiti dell’intera giornata in UTC.

Richiesta report

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	Riepilogo delle prestazioni giornaliere. Supporta filtri per data, dominio, ad root e provider.
GET	/api/v1/reports/by-date-and-ad-unit	Prestazioni giornaliere raggruppate per unità pubblicitaria.
GET	/api/v1/reports/by-domain-and-ad-unit	Dettaglio delle prestazioni per dominio e unità pubblicitaria.
GET	/api/v1/reports/bot-filtering	Report sul filtraggio dei bot per valutare la qualità del traffico dell’account.
GET	/api/v1/reports/bot-scores	Report sui punteggi dei bot per data e dimensioni correlate.
GET	/api/v1/reports/invalid-activity	Report sulle attività non valide. Non è richiesta una query standard per data o dominio.
GET	/api/v1/reports/direct-bidder-analysis	Report sui bidder diretti. Richiede directBidder e può includere start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventario delle unità pubblicitarie raggruppato per dominio.

Parametri di query comuni: start, end, domains ripetibile, adRoots ripetibile e adProvider. L’analisi dei bidder diretti richiede anche directBidder.

Report avanzati

Crea report email programmati o immediati

I report avanzati possono essere eseguiti subito o ripetersi secondo una pianificazione. Vengono inviati via email anziché restituiti direttamente nella risposta.

Salva report avanzato

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	Elenca i report avanzati salvati per l’account autenticato.
POST	/api/v2/reports/save-advanced-report	Crea o aggiorna un report avanzato. Richiede reportType, toAddress, immediateRun e almeno una destinazione tra adRoots e domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Elimina un report avanzato salvato tramite id.

Tipi di report

adUnit, dimensions, customData

Dimensioni

country, device, os

Frequenza

daily, weekly, biweekly, monthly

Inventario

Crea ed elimina unità pubblicitarie approvate

Le operazioni di scrittura dell’inventario richiedono un account Sulvo approvato e una chiave API creata dal proprietario con lo scope inventory:write.

Crea unità pubblicitaria

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	Crea una singola unità pubblicitaria con le impostazioni domain, type, size facoltativo, placement, custom name e focusedAd.
PUT	/api/v2/inventory/interstitial-units	Crea unità interstitial desktop e/o mobile per un dominio.
PUT	/api/v2/inventory/auto-sticky-units	Crea unità sticky display e/o mobile per un dominio.
DELETE	/api/v2/inventory/unit/{adId}	Elimina un’unità pubblicitaria di proprietà dell’account autenticato.

Tipi di unità pubblicitarie supportati

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Errori

Gestione degli errori

Le risposte di audit con stato diverso da 2xx e gli errori delle API dell’account Sulvo restituiscono corpi JSON progettati per client agent e CLI.

401

La chiave API manca, non è valida o è scaduta per le richieste alle API dell’account. L’endpoint di audit pubblico non richiede una chiave.

403

La chiave è stata autenticata ma non ha lo scope richiesto, l’account non è approvato oppure la risorsa appartiene a un altro account.

503 / 504

Il servizio di audit pubblico è sovraccarico oppure l’audit è scaduto. Riprova più tardi e rispetta Retry-After, se presente.

Struttura dell’errore di audit

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

Preferisci un client già pronto?

Il pacchetto npm e la configurazione MCP chiamano questi endpoint per te ed espongono gli stessi flussi di lavoro per audit, report e inventario ai client IA compatibili.

Vedi la configurazione