Publisher Revenue Audit API

Faça análises públicas da receita de editores, consulte os relatórios da Sulvo e gira o inventário de anúncios de editores aprovados através da mesma API usada pela CLI e pelo servidor MCP.

Base alojada

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsConfiguração da CLI e do MCP

Noções básicas

URLs base

O endpoint público de auditoria foi concebido para não exigir autenticação. Os relatórios de conta da Sulvo e as chamadas de inventário usam uma chave de API gerada no painel.

API de auditoria pública

POST

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

API da conta Sulvo

Chave de API Bearer

https://surge.sulvo.com/api

Endpoint MCP alojado

MCP

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

Endpoint público

Faça uma auditoria de receita

Use este endpoint para uma análise orientativa, baseada em evidências públicas, do domínio de um editor. A resposta não comprova uma perda de receita nem garante um aumento. Valide os resultados com os relatórios do lado do 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	Domínio de um editor ou host público, obrigatório. Os domínios sem esquema são normalizados para HTTPS. Destinos privados, endereços IP simples, hosts internos e portas fora do padrão são rejeitados.
input.vertical	Opcional. Aceita news, sports, entertainment, technology, education, gaming ou other.
input.metrics	Contexto opcional do painel, fornecido pelo editor, como taxa de preenchimento, visibilidade, CPM médio, receita por sessão, visualizações de página mensais ou sessões mensais.
input.options	Controlos opcionais de saída e recolha, incluindo format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel e partnerId.

Autenticação

Use uma chave de API da Sulvo para as APIs de conta

Gere uma chave de API no painel da Sulvo, em Definições da conta. Envie-a como token Bearer nos pedidos à API da conta Sulvo.

Cabeçalho de autorização

Authorization: Bearer $SULVO_API_KEY

reports:read

Necessário para exportar relatórios e consultar a lista de relatórios guardados.

reports:write

Necessário para criar, atualizar, executar ou eliminar relatórios avançados.

inventory:write

Necessário para criar e eliminar unidades de anúncio. A conta tem de estar aprovada e ser proprietária do inventário.

Relatórios

Consultar endpoints de relatórios

Os endpoints de consulta de relatórios usam pedidos GET na base da API da conta Sulvo. As datas sem hora são interpretadas como limites de um dia UTC completo.

Pedido de relatório

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	Resumo diário do desempenho. Aceita filtros por data, domínio, raiz de anúncios e fornecedor.
GET	/api/v1/reports/by-date-and-ad-unit	Desempenho diário agrupado por unidade de anúncio.
GET	/api/v1/reports/by-domain-and-ad-unit	Discriminação do desempenho por domínio e unidade de anúncio.
GET	/api/v1/reports/bot-filtering	Relatório de filtragem de bots para analisar a qualidade do tráfego da conta.
GET	/api/v1/reports/bot-scores	Relatório de pontuações de bots por data e dimensões relacionadas.
GET	/api/v1/reports/invalid-activity	Relatório de atividade inválida. Não requer uma consulta padrão por data ou domínio.
GET	/api/v1/reports/direct-bidder-analysis	Relatório de licitadores diretos. Requer directBidder e pode incluir start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventário de unidades de anúncio agrupado por domínio.

Parâmetros de consulta comuns: start, end, domains (pode repetir-se), adRoots (pode repetir-se) e adProvider. A análise de licitadores diretos também requer directBidder.

Relatórios avançados

Criar relatórios por e-mail, agendados ou imediatos

Os relatórios avançados podem ser executados de imediato ou voltar a ser executados segundo um agendamento. São enviados por e-mail, em vez de apresentados na resposta.

Guardar relatório avançado

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	Listar os relatórios avançados guardados para a conta autenticada.
POST	/api/v2/reports/save-advanced-report	Criar ou atualizar um relatório avançado. Requer reportType, toAddress, immediateRun e pelo menos um destino em adRoots ou domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Eliminar um relatório avançado guardado pelo respetivo id.

Tipos de relatório

adUnit, dimensions, customData

Dimensões

country, device, os

Frequência

daily, weekly, biweekly, monthly

Inventário

Criar e eliminar unidades de anúncio aprovadas

As alterações ao inventário exigem uma conta da Sulvo aprovada e uma chave de API gerada pelo titular da conta, com o âmbito inventory:write.

Criar unidade de anúncio

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	Criar uma unidade de anúncio com domínio, tipo, tamanho opcional, espaço publicitário, nome personalizado e definições de focusedAd.
PUT	/api/v2/inventory/interstitial-units	Criar unidades intersticiais para desktop e/ou dispositivos móveis num domínio.
PUT	/api/v2/inventory/auto-sticky-units	Criar unidades sticky de display e/ou unidades sticky para dispositivos móveis num domínio.
DELETE	/api/v2/inventory/unit/{adId}	Eliminar uma unidade de anúncio pertencente à conta autenticada.

Tipos de unidade de anúncio suportados

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Erros

Tratamento de erros

As respostas de auditoria que não sejam 2xx e as falhas da API de conta Sulvo devolvem corpos JSON concebidos para clientes de agentes de IA e da CLI.

401

A chave de API está em falta, é inválida ou expirou para chamadas à API da conta. O endpoint público de auditoria não requer chave.

403

A chave foi autenticada, mas não tem o âmbito necessário, a conta não está aprovada ou o recurso pertence a outra conta.

503 / 504

O serviço público de auditoria está sobrecarregado ou o tempo limite da auditoria foi excedido. Tente novamente mais tarde e respeite Retry-After quando estiver presente.

Estrutura do erro de auditoria

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

Prefere um cliente distribuído como pacote?

O pacote npm e a configuração MCP fazem estes pedidos em seu nome e disponibilizam os mesmos fluxos de auditoria, relatórios e inventário a clientes de IA compatíveis.

Ver a configuração