Ingresos del editor: API de auditoría

Ejecute evaluaciones públicas de ingresos de editores, obtenga informes de Sulvo y gestione el inventario aprobado de los editores mediante la misma interfaz de API que usan la CLI y el servidor MCP.

URL base alojada

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

Conceptos básicos

URLs base

El endpoint público de auditoría se mantiene sin autenticación a propósito. Las llamadas a informes de cuenta y de inventario de Sulvo usan una clave de API generada desde el panel.

API pública de auditoría

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

Ejecute una auditoría de ingresos

Use este endpoint para obtener una evaluación orientativa del dominio de un editor basada en evidencia pública. 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	Dominio obligatorio de un 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	Opcional. Contexto del panel proporcionado por el editor, como la tasa de relleno, la visibilidad, el CPM promedio, los ingresos por sesión, las vistas de página al mes o las sesiones mensuales.
input.options	Opcional. Controles de salida y recopilación, como format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel y partnerId.

Autenticación

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

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

Encabezado Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Obligatorio para exportar informes y consultar la lista de 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

Consulte los endpoints de informes

Los endpoints de lectura de informes usan solicitudes GET en la URL base de la API de cuenta de Sulvo. Los valores que solo contienen una fecha se interpretan como los límites de un día completo en UTC.

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 de rendimiento. Admite filtros por fecha, dominio, raíz publicitaria 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	Informe de actividad no válida. No requiere una consulta estándar por fecha o dominio.
GET	/api/v1/reports/direct-bidder-analysis	Informe de postores directos. 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 comunes: start, end, domains (repetible), adRoots (repetible) y adProvider. El análisis de postores directos también requiere directBidder.

Informes avanzados

Cree informes por correo electrónico programados o de ejecución inmediata

Los informes avanzados pueden ejecutarse de inmediato o repetirse según una programación. Se envían por correo electrónico en lugar de devolverse 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	Mostrar los informes avanzados guardados de 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 su id.

Tipos de informe

adUnit, dimensions, customData

Dimensiones

country, device, os

Frecuencia

daily, weekly, biweekly, monthly

Inventario

Cree y elimine unidades publicitarias aprobadas

Para escribir en el inventario se necesita una cuenta de Sulvo aprobada y una clave de API creada por el titular, con el permiso 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	Crear una unidad publicitaria con domain, type, size opcional, placement, nombre personalizado y opciones focusedAd.
PUT	/api/v2/inventory/interstitial-units	Crear unidades intersticiales para computadoras de escritorio, dispositivos móviles o ambos tipos de dispositivo en un dominio.
PUT	/api/v2/inventory/auto-sticky-units	Crear unidades publicitarias Sticky para display, para dispositivos móviles o para ambos en un dominio.
DELETE	/api/v2/inventory/unit/{adId}	Eliminar una unidad publicitaria que pertenezca a la cuenta autenticada.

Tipos de unidades publicitarias admitidos

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Errores

Manejo de errores

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

401

La clave de API no se proporcionó, no es válida o venció para las llamadas a la API de cuenta. El endpoint público de auditoría no requiere una clave.

403

La clave autenticó la solicitud, pero no tiene el permiso requerido, la cuenta no está aprobada o el recurso pertenece a otra cuenta.

503 / 504

El servicio público de auditoría está saturado o la auditoría agotó el tiempo de espera. Vuelva a intentarlo más tarde y respete Retry-After si aparece.

Estructura de error de auditoría

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

¿Prefiere un cliente empaquetado?

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

Ver la configuración