Documentație pentru Publisher Revenue Audit API

Rulați analize publice ale veniturilor editorilor, preluați rapoarte Sulvo și administrați inventarul aprobat al editorilor prin aceeași interfață API folosită de CLI și serverul MCP.

Adresă de bază găzduită

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsConfigurare CLI și MCP

Noțiuni de bază

URL-uri de bază

În mod intenționat, endpointul public de audit nu necesită autentificare. Rapoartele contului Sulvo și apelurile pentru inventar publicitar folosesc o cheie API generată în panoul de control.

API public de audit

POST

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

API pentru contul Sulvo

Cheie API Bearer

https://surge.sulvo.com/api

Endpoint MCP găzduit

MCP

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

Endpoint public

Rulați un audit al veniturilor

Folosiți acest endpoint pentru o analiză orientativă a informațiilor publice disponibile despre domeniul unui editor. Răspunsul nu dovedește pierderi de venituri și nu garantează o creștere. Verificați constatările față de raportarea editorului.

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

Câmp	Note
input.domain	Domeniu obligatoriu al editorului sau gazdă publică. Domeniile fără schemă sunt normalizate la HTTPS. Țintele private, adresele IP brute, gazdele interne și porturile nestandard sunt respinse.
input.vertical	Opțional. Acceptă news, sports, entertainment, technology, education, gaming sau other.
input.metrics	Context opțional din panoul editorului, precum rata de completare, vizibilitatea, CPM-ul mediu, venitul per sesiune, vizualizările lunare de pagini sau sesiunile lunare.
input.options	Controale opționale pentru rezultate și colectare, inclusiv format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel și partnerId.

Autentificare

Folosiți o cheie API Sulvo pentru API-urile contului

Generați o cheie API în panoul Sulvo, la Setări cont. Trimiteți-o ca token Bearer în solicitările către API-urile contului Sulvo.

Antet Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Necesar pentru exportul rapoartelor și listarea rapoartelor salvate.

reports:write

Necesar pentru a crea, actualiza, rula sau șterge rapoarte avansate.

inventory:write

Necesar pentru crearea și ștergerea unităților publicitare. Contul trebuie aprobat și trebuie să dețină inventarul.

Rapoarte

Endpointuri pentru citirea rapoartelor

Rapoartele de citire folosesc solicitări GET la adresa de bază a API-ului contului Sulvo. Valorile care conțin doar data sunt interpretate ca intervale pentru întreaga zi în UTC.

Solicitare de raport

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	Rezumat zilnic al performanței. Acceptă filtre pentru dată, domeniu, rădăcina reclamei și furnizor.
GET	/api/v1/reports/by-date-and-ad-unit	Performanță zilnică grupată după unitatea publicitară.
GET	/api/v1/reports/by-domain-and-ad-unit	Detalierea performanței după domeniu și unitate publicitară.
GET	/api/v1/reports/bot-filtering	Raport de filtrare a boților pentru evaluarea calității traficului contului.
GET	/api/v1/reports/bot-scores	Raportarea scorurilor boților după dată și dimensiuni conexe.
GET	/api/v1/reports/invalid-activity	Raportarea activității invalide. Nu este necesară o interogare standard după dată sau domeniu.
GET	/api/v1/reports/direct-bidder-analysis	Raportul ofertantului direct. Necesită directBidder și poate include start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventarul unităților publicitare grupat după domeniu.

Parametri de interogare uzuali: start, end, domains și adRoots, care pot fi repetați, precum și adProvider. Analiza ofertantului direct necesită și directBidder.

Rapoarte avansate

Creați rapoarte prin e-mail, programate sau imediate

Rapoartele avansate pot fi rulate imediat sau recurente, după un program. Sunt trimise prin e-mail în loc să fie returnate direct în răspuns.

Salvați raportul avansat

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	Listați rapoartele avansate salvate pentru contul autentificat.
POST	/api/v2/reports/save-advanced-report	Creați sau actualizați un raport avansat. Necesită reportType, toAddress, immediateRun și cel puțin o țintă adRoots sau domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Ștergeți un raport avansat salvat după ID.

Tipuri de raport

adUnit, dimensions, customData

Dimensiuni

country, device, os

Frecvență

daily, weekly, biweekly, monthly

Inventar publicitar

Creați și ștergeți unități publicitare aprobate

Modificările inventarului necesită un cont Sulvo aprobat și o cheie API creată de proprietar, cu scope inventory:write.

Creați o unitate publicitară

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ți o singură unitate publicitară cu domeniu, tip, dimensiune opțională, poziție, nume personalizat și setări focusedAd.
PUT	/api/v2/inventory/interstitial-units	Creați unități interstițiale pentru desktop și/sau mobil pentru un domeniu.
PUT	/api/v2/inventory/auto-sticky-units	Creați unități publicitare Display de tip Sticky și/sau unități mobile Sticky pentru un domeniu.
DELETE	/api/v2/inventory/unit/{adId}	Ștergeți o unitate publicitară deținută de contul autentificat.

Tipuri de unități publicitare acceptate

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Erori

Gestionarea erorilor

Răspunsurile de audit care nu sunt 2xx și erorile API-ului contului Sulvo returnează corpuri JSON concepute pentru clienți agent și CLI.

401

Cheia API lipsește, este invalidă sau a expirat pentru apelurile către API-ul contului. Endpointul public de audit nu necesită cheie.

403

Cheia a autentificat solicitarea, dar nu are domeniul de permisiuni necesar, contul nu este aprobat sau resursa aparține altui cont.

503 / 504

Serviciul public de audit este suprasolicitat sau auditul a expirat. Încercați mai târziu și respectați Retry-After, dacă este prezent.

Structura erorii de audit

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

Preferați un client la pachet?

Pachetul npm și configurarea MCP apelează aceste endpointuri în locul dvs. și oferă clienților IA compatibili aceleași fluxuri de lucru pentru audit, rapoarte și inventar.

Vedeți configurarea