Yayıncı Gelir Denetimi API’si

Herkese açık yayıncı gelir taramalarını çalıştırın, Sulvo raporlarını alın ve onaylı yayıncı envanterini CLI ile MCP sunucusunun da kullandığı aynı API arayüzü üzerinden yönetin.

Barındırılan temel URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsCLI ve MCP kurulumu

Temel bilgiler

Temel URL’ler

Herkese açık denetim uç noktası bilerek kimlik doğrulaması olmadan çalışır. Sulvo hesap raporları ve envanter çağrıları için kontrol panelinde oluşturulan bir API anahtarı kullanılır.

Herkese açık denetim API’si

POST

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

Sulvo hesap API’si

Bearer API anahtarı

https://surge.sulvo.com/api

Barındırılan MCP uç noktası

MCP

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

Herkese açık uç nokta

Gelir denetimi çalıştırın

Bu uç nokta, bir yayıncı alan adı için herkese açık kanıtlara dayalı bir ön tarama sağlar. Yanıt, gelir kaybının kanıtı veya garantili bir artış anlamına gelmez. Bulguları yayıncı tarafı raporlarıyla doğrulayın.

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

Alan	Notlar
input.domain	Zorunlu yayıncı alan adı veya herkese açık ana makine adı. Şema içermeyen alan adları HTTPS olarak standartlaştırılır. Özel hedefler, ham IP adresleri, dahili ana makine adları ve standart dışı bağlantı noktaları reddedilir.
input.vertical	İsteğe bağlıdır. news, sports, entertainment, technology, education, gaming veya other değerlerini kabul eder.
input.metrics	Doluluk oranı, görüntülenebilirlik, ortalama CPM, oturum başına gelir, aylık sayfa görüntüleme sayısı veya aylık oturum sayısı gibi yayıncının sağladığı isteğe bağlı kontrol paneli verileri.
input.options	İsteğe bağlı çıktı ve veri toplama denetimleri arasında format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel ve partnerId yer alır.

Kimlik doğrulama

Hesap API’leri için Sulvo API anahtarı kullanın

Sulvo kontrol panelinde Hesap Ayarları bölümünden bir API anahtarı oluşturun. Sulvo hesap API’si isteklerinde bu anahtarı Bearer belirteci olarak gönderin.

Authorization başlığı

Authorization: Bearer $SULVO_API_KEY

reports:read

Rapor dışa aktarımları ve kayıtlı raporların listelenmesi için gereklidir.

reports:write

Gelişmiş rapor oluşturmak, güncellemek, çalıştırmak veya silmek için gereklidir.

inventory:write

Reklam birimi oluşturmak ve silmek için gereklidir. Hesap onaylı olmalı ve envanterin sahibi olmalıdır.

Raporlar

Rapor uç noktalarını okuyun

Okuma amaçlı raporlar, Sulvo hesap API’sinin temel adresinde GET istekleri kullanır. Yalnızca tarih içeren değerler, UTC gününün tamamını kapsayan sınırlar olarak yorumlanır.

Rapor isteği

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	Günlük performans özeti. date, domain, ad root ve provider filtrelerini destekler.
GET	/api/v1/reports/by-date-and-ad-unit	Reklam birimine göre gruplandırılmış günlük performans.
GET	/api/v1/reports/by-domain-and-ad-unit	Alan adı ve reklam birimine göre performans dökümü.
GET	/api/v1/reports/bot-filtering	Hesap trafiğinin kalitesini incelemek için bot filtreleme raporu.
GET	/api/v1/reports/bot-scores	Tarih ve ilgili boyutlara göre bot puanı raporlaması.
GET	/api/v1/reports/invalid-activity	Geçersiz etkinlik raporlaması. Tarih veya alan adı içeren standart bir sorgu gerekmez.
GET	/api/v1/reports/direct-bidder-analysis	Doğrudan teklif veren raporu. directBidder gereklidir; start ve end parametreleri de eklenebilir.
GET	/api/v1/inventory/ad-units-by-domain	Alan adına göre gruplandırılmış reklam birimi envanteri.

Yaygın sorgu parametreleri: start, end, birden çok kez kullanılabilen domains ve adRoots ile adProvider. Doğrudan teklif veren analizi için ayrıca directBidder gerekir.

Gelişmiş raporlar

Zamanlanmış veya anında e-posta raporları oluşturun

Gelişmiş raporlar hemen çalıştırılabilir veya bir zamanlamaya göre yinelenebilir. Raporlar API yanıtında doğrudan döndürülmek yerine e-posta ile iletilir.

Gelişmiş raporu kaydedin

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	Kimliği doğrulanmış hesap için kayıtlı gelişmiş raporları listeleyin.
POST	/api/v2/reports/save-advanced-report	Gelişmiş bir rapor oluşturun veya güncelleyin. reportType, toAddress ve immediateRun alanları ile en az bir adRoots veya domains hedefi gerekir.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Kayıtlı bir gelişmiş raporu id değerine göre silin.

Rapor türleri

adUnit, dimensions, customData

Boyutlar

country, device, os

Sıklık

daily, weekly, biweekly, monthly

Envanter

Onaylı reklam birimleri oluşturun ve silin

Envanterde değişiklik yapmak için onaylı bir Sulvo hesabı ve inventory:write iznine sahip, hesap sahibinin oluşturduğu bir API anahtarı gerekir.

Reklam birimi oluşturun

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	Tek bir reklam birimi oluşturmak için domain, type, isteğe bağlı size, placement, özel ad ve focusedAd ayarlarını kullanın.
PUT	/api/v2/inventory/interstitial-units	Bir alan adı için masaüstü, mobil veya her iki platforma yönelik geçiş reklamı birimleri oluşturun.
PUT	/api/v2/inventory/auto-sticky-units	Bir alan adı için yapışkan görüntülü reklam birimleri, yapışkan mobil reklam birimleri veya her ikisini oluşturun.
DELETE	/api/v2/inventory/unit/{adId}	Kimliği doğrulanmış hesabın sahip olduğu bir reklam birimini silin.

Desteklenen reklam birimi türleri

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Hatalar

Hata yönetimi

2xx olmayan denetim yanıtları ve Sulvo hesap API’sindeki hatalar, yapay zekâ ajanları ve CLI istemcileri için tasarlanmış JSON gövdeleri döndürür.

401

Hesap API’si isteklerinde API anahtarı eksik, geçersiz veya süresi dolmuş. Herkese açık denetim uç noktası anahtar gerektirmez.

403

Anahtarla kimlik doğrulaması yapıldı ancak gerekli izin yok, hesap onaylı değil veya kaynak başka bir hesaba ait.

503 / 504

Herkese açık denetim hizmeti aşırı yük altındaysa veya denetim zaman aşımına uğradıysa daha sonra yeniden deneyin. Retry-After varsa bu başlığa uyun.

Denetim hata yanıtı

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

Hazır bir istemciyi mi tercih edersiniz?

Bu uç noktaları sizin yerinize çağıran npm paketi ve MCP kurulumu, uyumlu yapay zekâ istemcilerine aynı denetim, raporlama ve envanter iş akışlarını sunar.

Kurulumu görüntüleyin