API Audit Pendapatan Penayang

Jalankan pemeriksaan awal pendapatan penayang berdasarkan bukti publik, ambil laporan Sulvo, dan kelola inventaris iklan penayang yang disetujui melalui antarmuka API yang sama dengan yang digunakan CLI dan server MCP.

URL dasar yang dihosting

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsPenyiapan CLI dan MCP

Dasar

URL dasar

Endpoint audit publik sengaja tidak memerlukan autentikasi. Panggilan laporan akun dan inventaris Sulvo menggunakan kunci API yang dibuat di dasbor.

API audit publik

POST

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

API akun Sulvo

Kunci API Bearer

https://surge.sulvo.com/api

Endpoint MCP yang dihosting

MCP

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

Endpoint publik

Jalankan audit pendapatan

Gunakan endpoint ini untuk pemeriksaan indikatif berbasis bukti publik atas domain penayang. Responsnya bukan bukti kehilangan pendapatan atau jaminan peningkatan. Validasi temuan dengan laporan dari sisi penayang.

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

Kolom	Catatan
input.domain	Wajib: domain penayang atau host publik. Domain tanpa awalan dinormalisasi ke HTTPS. Target privat, alamat IP mentah, host internal, dan port nonstandar ditolak.
input.vertical	Opsional. Menerima news, sports, entertainment, technology, education, gaming, atau other.
input.metrics	Opsional. Konteks dasbor yang diberikan penayang, seperti fill rate, viewability, CPM rata-rata, pendapatan per sesi, jumlah tampilan halaman bulanan, atau sesi bulanan.
input.options	Opsional. Kontrol output dan pengumpulan, termasuk format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel, dan partnerId.

Autentikasi

Gunakan kunci API Sulvo untuk API akun

Buat kunci API di dasbor Sulvo pada Pengaturan Akun. Kirimkan kunci tersebut sebagai token Bearer dalam permintaan ke API akun Sulvo.

Header Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Diwajibkan untuk ekspor laporan dan daftar laporan tersimpan.

reports:write

Diwajibkan untuk membuat, memperbarui, menjalankan, atau menghapus laporan lanjutan.

inventory:write

Diwajibkan untuk membuat dan menghapus unit iklan. Akun harus disetujui dan memiliki inventaris iklan tersebut.

Laporan

Endpoint untuk membaca laporan

Permintaan untuk membaca laporan menggunakan metode GET pada URL dasar API akun Sulvo. Nilai yang hanya mencantumkan tanggal diartikan sebagai rentang satu hari penuh dalam UTC.

Permintaan laporan

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	Ringkasan performa harian. Mendukung filter tanggal, domain, akar iklan, dan penyedia.
GET	/api/v1/reports/by-date-and-ad-unit	Performa harian yang dikelompokkan berdasarkan unit iklan.
GET	/api/v1/reports/by-domain-and-ad-unit	Rincian performa berdasarkan domain dan unit iklan.
GET	/api/v1/reports/bot-filtering	Laporan pemfilteran bot untuk meninjau kualitas lalu lintas akun.
GET	/api/v1/reports/bot-scores	Pelaporan skor bot berdasarkan tanggal dan dimensi terkait.
GET	/api/v1/reports/invalid-activity	Pelaporan aktivitas tidak valid. Tidak diperlukan kueri tanggal atau domain standar.
GET	/api/v1/reports/direct-bidder-analysis	Laporan bidder langsung. Memerlukan directBidder dan dapat menyertakan start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventaris unit iklan yang dikelompokkan berdasarkan domain.

Parameter kueri umum: start, end, domains yang dapat diulang, adRoots yang dapat diulang, dan adProvider. Analisis bidder langsung juga memerlukan directBidder.

Laporan lanjutan

Buat laporan email terjadwal atau langsung

Laporan lanjutan dapat langsung dijalankan atau dijadwalkan berulang. Laporan dikirim melalui email, bukan dikembalikan langsung dalam respons.

Simpan laporan lanjutan

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	Tampilkan daftar laporan lanjutan tersimpan untuk akun yang diautentikasi.
POST	/api/v2/reports/save-advanced-report	Buat atau perbarui laporan lanjutan. Memerlukan reportType, toAddress, immediateRun, dan setidaknya satu target adRoots atau domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Hapus laporan lanjutan tersimpan berdasarkan id.

Jenis laporan

adUnit, dimensions, customData

Dimensi

country, device, os

Frekuensi

daily, weekly, biweekly, monthly

Inventaris iklan

Buat dan hapus unit iklan yang disetujui

Perubahan inventaris memerlukan akun Sulvo yang disetujui dan kunci API yang dibuat pemilik akun dengan scope inventory:write.

Buat unit iklan

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	Buat satu unit iklan dengan domain, jenis, ukuran opsional, penempatan, nama khusus, dan pengaturan focusedAd.
PUT	/api/v2/inventory/interstitial-units	Buat unit iklan interstisial untuk desktop dan/atau perangkat seluler pada suatu domain.
PUT	/api/v2/inventory/auto-sticky-units	Buat unit iklan display Sticky dan/atau unit iklan seluler Sticky untuk suatu domain.
DELETE	/api/v2/inventory/unit/{adId}	Hapus unit iklan milik akun yang diautentikasi.

Jenis unit iklan yang didukung

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Kesalahan

Penanganan kesalahan

Respons audit non-2xx dan kegagalan API akun Sulvo mengembalikan isi JSON yang dirancang untuk klien agen dan CLI.

401

Kunci API tidak ada, tidak valid, atau sudah kedaluwarsa untuk panggilan API akun. Endpoint audit publik tidak memerlukan kunci.

403

Kunci berhasil diautentikasi tetapi tidak memiliki scope yang diwajibkan, akun belum disetujui, atau resource dimiliki akun lain.

503 / 504

Layanan audit publik kelebihan beban atau waktu audit habis. Coba lagi nanti dan ikuti nilai header Retry-After jika tersedia.

Struktur respons kesalahan audit

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

Lebih suka klien siap pakai?

Paket npm dan penyiapan MCP memanggil endpoint ini untuk Anda serta menyediakan alur kerja audit, laporan, dan inventaris yang sama bagi klien AI yang kompatibel.

Lihat panduan penyiapan