Auditoria de receita de publishers pela API

Execute análises públicas de receita de publishers, consulte relatórios da Sulvo e gerencie o inventário aprovado de publishers pela mesma API usada pela CLI e pelo servidor MCP.

URL base hospedada

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

Noções básicas

URLs base

O endpoint público de auditoria não exige autenticação. As chamadas de relatórios da conta Sulvo e de inventário usam uma chave de API gerada no painel.

API pública de auditoria

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 hospedado

MCP

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

Endpoint público

Executar uma auditoria de receita

Use este endpoint para uma análise indicativa, baseada em evidências públicas, do domínio de um publisher. A resposta não comprova perda de receita nem garante aumento; valide os resultados com os relatórios do lado do 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	Observações
input.domain	Domínio obrigatório do publisher ou host público. Domínios sem esquema são normalizados para HTTPS. Destinos privados, endereços IP literais, 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 publisher, como taxa de preenchimento, visibilidade, CPM médio, receita por sessão, visualizações de página mensais ou sessões mensais.
input.options	Controles opcionais de saída e coleta, incluindo format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel e partnerId.

Autenticação

Usar uma chave de API da Sulvo nas APIs da conta

Gere uma chave de API no painel da Sulvo em Account Settings. Envie-a como token Bearer nas solicitações à API da conta Sulvo.

Cabeçalho de autorização

Authorization: Bearer $SULVO_API_KEY

reports:read

Obrigatório para exportar relatórios e listar relatórios salvos.

reports:write

Obrigatório para criar, atualizar, executar ou excluir relatórios avançados.

inventory:write

Obrigatório para criar e excluir blocos de anúncios. A conta precisa estar aprovada e ser proprietária do inventário.

Relatórios

Consultar endpoints de relatórios

As consultas de relatórios usam solicitações GET na URL base da API da conta Sulvo. Valores que contêm apenas datas são interpretados como limites de dias UTC completos.

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

Parâmetros de consulta comuns: start, end, domains repetível, adRoots repetível e adProvider. A análise de compradores diretos também exige directBidder.

Relatórios avançados

Criar relatórios por e-mail agendados ou imediatos

Os relatórios avançados podem ser executados imediatamente ou de forma recorrente em uma agenda. Eles são enviados por e-mail, em vez de retornados na resposta.

Salvar 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 salvos para a conta autenticada.
POST	/api/v2/reports/save-advanced-report	Criar ou atualizar um relatório avançado. Exige reportType, toAddress, immediateRun e pelo menos um destino em adRoots ou domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Excluir um relatório avançado salvo pelo id.

Tipos de relatório

adUnit, dimensions, customData

Dimensões

country, device, os

Frequência

daily, weekly, biweekly, monthly

Inventário

Criar e excluir blocos de anúncios aprovados

Para gravar alterações no inventário, é necessária uma conta Sulvo aprovada e uma chave de API criada pelo proprietário com o escopo inventory:write.

Criar bloco de anúncios

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 um único bloco de anúncios com domain, type, size opcional, placement, nome personalizado e configurações focusedAd.
PUT	/api/v2/inventory/interstitial-units	Criar blocos intersticiais para desktop e/ou dispositivos móveis em um domínio.
PUT	/api/v2/inventory/auto-sticky-units	Criar blocos de display fixos e/ou blocos fixos para dispositivos móveis em um domínio.
DELETE	/api/v2/inventory/unit/{adId}	Excluir um bloco de anúncios pertencente à conta autenticada.

Tipos de bloco de anúncios compatíveis

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Erros

Tratamento de erros

Respostas de auditoria diferentes de 2xx e falhas na API da conta Sulvo retornam corpos JSON projetados para clientes de agentes e CLI.

401

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

403

A chave foi autenticada, mas não tem o escopo 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 a auditoria excedeu o tempo limite. Tente novamente mais tarde e respeite Retry-After quando estiver presente.

Envelope de erro da auditoria

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

Prefere um cliente empacotado?

O pacote npm e a configuração do MCP chamam esses endpoints para você e oferecem os mesmos fluxos de auditoria, relatórios e inventário para clientes de IA compatíveis.

Ver configuração