Documentación de Publisher Revenue Audit API

Ejecute análisis públicos de ingresos de editores, consulte informes de Sulvo y gestione el inventario aprobado de editores a través de la misma API que utilizan la CLI y el servidor MCP.

Base alojada

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsConfiguración de CLI y MCP

Conceptos básicos

URL base

El endpoint de auditoría pública no requiere autenticación por diseño. Los informes de cuenta y las llamadas de inventario de Sulvo utilizan una clave de API generada desde el panel de control.

API de auditoría pública

POST

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

API de cuenta de Sulvo

Clave de API Bearer

https://surge.sulvo.com/api

Endpoint MCP alojado

MCP

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

Endpoint público

Ejecutar una auditoría de ingresos

Utilice este endpoint para realizar un análisis orientativo de la evidencia pública de un dominio de editor. La respuesta no demuestra una pérdida de ingresos ni garantiza un aumento; valide los hallazgos con los informes del lado del 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
      }
    }
  }'

Campo	Notas
input.domain	Obligatorio. Dominio del editor o host público. Los dominios sin esquema se normalizan a HTTPS. Se rechazan los destinos privados, las direcciones IP directas, los hosts internos y los puertos no estándar.
input.vertical	Opcional. Acepta news, sports, entertainment, technology, education, gaming u other.
input.metrics	Contexto opcional del panel de control proporcionado por el editor, como fill rate, viewability, CPM medio, ingresos por sesión, páginas vistas mensuales o sesiones mensuales.
input.options	Controles opcionales de salida y recopilación, incluidos format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel y partnerId.

Autenticación

Utilice una clave de API de Sulvo para las API de cuenta

Genere una clave de API en Configuración de cuenta, dentro del panel de control de Sulvo. Envíela como token Bearer en las solicitudes a las API de cuenta de Sulvo.

Cabecera Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Obligatorio para exportar informes y enumerar los informes guardados.

reports:write

Obligatorio para crear, actualizar, ejecutar o eliminar informes avanzados.

inventory:write

Obligatorio para crear y eliminar unidades publicitarias. La cuenta debe estar aprobada y ser propietaria del inventario.

Informes

Consultar los endpoints de informes

Los informes de solo lectura utilizan solicitudes GET en la URL base de la API de cuenta de Sulvo. Las fechas sin hora se interpretan como límites de días UTC completos.

Solicitud de 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	Resumen diario del rendimiento. Admite filtros por fecha, dominio, ad root y proveedor.
GET	/api/v1/reports/by-date-and-ad-unit	Rendimiento diario agrupado por unidad publicitaria.
GET	/api/v1/reports/by-domain-and-ad-unit	Desglose del rendimiento por dominio y unidad publicitaria.
GET	/api/v1/reports/bot-filtering	Informe de filtrado de bots para revisar la calidad del tráfico de la cuenta.
GET	/api/v1/reports/bot-scores	Informes de puntuación de bots por fecha y dimensiones relacionadas.
GET	/api/v1/reports/invalid-activity	Informes de actividad no válida. No se requiere la consulta estándar de fecha/dominio.
GET	/api/v1/reports/direct-bidder-analysis	Informe de bidder directo. Requiere directBidder y puede incluir start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventario de unidades publicitarias agrupado por dominio.

Parámetros de consulta habituales: start, end, domains repetible, adRoots repetible y adProvider. El análisis de bidders directos también requiere directBidder.

Informes avanzados

Crear informes por correo programados o inmediatos

Los informes avanzados pueden ejecutarse de inmediato o repetirse según una programación. Se envían por correo electrónico en lugar de incluirse directamente en la respuesta.

Guardar informe avanzado

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	Enumerar los informes avanzados guardados para la cuenta autenticada.
POST	/api/v2/reports/save-advanced-report	Crear o actualizar un informe avanzado. Requiere reportType, toAddress, immediateRun y al menos un destino adRoots o domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Eliminar un informe avanzado guardado por id.

Tipos de informe

adUnit, dimensions, customData

Dimensiones

country, device, os

Frecuencia

daily, weekly, biweekly, monthly

Inventario

Crear y eliminar unidades publicitarias aprobadas

Para modificar el inventario se necesita una cuenta de Sulvo aprobada y una clave de API creada por el propietario con el scope inventory:write.

Crear unidad publicitaria

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	Cree una unidad publicitaria con domain, type, size opcional, placement, custom name y los ajustes focusedAd.
PUT	/api/v2/inventory/interstitial-units	Cree en un dominio unidades intersticiales para ordenador, móvil o ambos.
PUT	/api/v2/inventory/auto-sticky-units	Cree en un dominio unidades sticky para display, móvil o ambos.
DELETE	/api/v2/inventory/unit/{adId}	Eliminar una unidad publicitaria propiedad de la cuenta autenticada.

Tipos de unidad publicitaria compatibles

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Errores

Gestión de errores

Las respuestas de auditoría distintas de 2xx y los errores de las API de cuenta de Sulvo devuelven cuerpos JSON diseñados para clientes de agentes y de la CLI.

401

La clave de API falta, no es válida o ha caducado para las llamadas a las API de cuenta. El endpoint de auditoría pública no requiere una clave.

403

La clave se ha autenticado, pero no tiene el scope requerido, la cuenta no está aprobada o el recurso pertenece a otra cuenta.

503 / 504

El servicio de auditoría pública está saturado o se ha agotado el tiempo de espera. Vuelva a intentarlo más tarde y respete Retry-After si aparece.

Estructura del error de auditoría

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

¿Prefiere un cliente empaquetado?

El paquete npm y la configuración de MCP llaman a estos endpoints por usted y ofrecen a los clientes de IA compatibles los mismos flujos de trabajo de auditoría, informes e inventario.

Ver la configuración