Audit Hasil Iklan Penerbit API

Jalankan semakan hasil iklan penerbit awam, dapatkan laporan Sulvo dan urus inventori penerbit yang diluluskan melalui API yang juga digunakan oleh CLI dan pelayan MCP.

URL asas yang dihoskan

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

Asas

URL asas

Endpoint audit awam sengaja tidak memerlukan pengesahan. Laporan akaun Sulvo dan permintaan inventori menggunakan kunci API yang dijana melalui papan pemuka.

API audit awam

POST

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

API akaun Sulvo

Kunci API Bearer

https://surge.sulvo.com/api

Endpoint MCP yang dihoskan

MCP

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

Endpoint awam

Jalankan audit hasil

Gunakan endpoint ini untuk semakan indikatif berdasarkan bukti awam bagi domain penerbit. Respons ini bukan bukti kehilangan hasil atau peningkatan yang dijamin; sahkan dapatan dengan laporan pihak penerbit.

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

Medan	Nota
input.domain	Domain penerbit atau hos awam diperlukan. Domain tanpa skema ditetapkan kepada HTTPS. Sasaran peribadi, alamat IP mentah, hos dalaman dan port bukan standard akan ditolak.
input.vertical	Pilihan. Menerima news, sports, entertainment, technology, education, gaming atau other.
input.metrics	Pilihan. Konteks papan pemuka yang dibekalkan penerbit, seperti kadar pengisian iklan, kebolehlihatan, purata CPM, hasil bagi setiap sesi, paparan halaman bulanan atau sesi bulanan.
input.options	Pilihan. Kawalan output dan pengumpulan, termasuk format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel dan partnerId.

Pengesahan

Gunakan kunci API Sulvo untuk API akaun

Jana kunci API dalam papan pemuka Sulvo di bawah Tetapan Akaun. Sertakannya sebagai token Bearer dalam permintaan API akaun Sulvo.

Pengepala Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Diperlukan untuk eksport laporan dan senarai laporan tersimpan.

reports:write

Diperlukan untuk mencipta, mengemas kini, menjalankan atau memadam laporan lanjutan.

inventory:write

Diperlukan untuk mencipta dan memadam unit iklan. Akaun mesti diluluskan dan memiliki inventori tersebut.

Laporan

Endpoint untuk membaca laporan

Permintaan GET untuk membaca laporan menggunakan URL asas API akaun Sulvo. Nilai tarikh sahaja ditafsirkan sebagai julat 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 prestasi harian. Menyokong penapis tarikh, domain, akar unit iklan dan penyedia.
GET	/api/v1/reports/by-date-and-ad-unit	Prestasi harian yang dikelompokkan mengikut unit iklan.
GET	/api/v1/reports/by-domain-and-ad-unit	Pecahan prestasi mengikut domain dan unit iklan.
GET	/api/v1/reports/bot-filtering	Laporan penapisan bot untuk menyemak kualiti trafik akaun.
GET	/api/v1/reports/bot-scores	Pelaporan skor bot mengikut tarikh dan dimensi berkaitan.
GET	/api/v1/reports/invalid-activity	Pelaporan aktiviti tidak sah. Parameter pertanyaan tarikh/domain standard tidak diperlukan.
GET	/api/v1/reports/direct-bidder-analysis	Laporan pembida langsung. Memerlukan directBidder dan boleh menyertakan start/end.
GET	/api/v1/inventory/ad-units-by-domain	Inventori unit iklan yang dikelompokkan mengikut domain.

Parameter pertanyaan umum: start, end, domains yang boleh diulang, adRoots yang boleh diulang dan adProvider. Analisis pembida langsung juga memerlukan directBidder.

Laporan lanjutan

Cipta laporan e-mel berjadual atau serta-merta

Laporan lanjutan boleh dijalankan serta-merta atau berulang mengikut jadual. Laporan dihantar melalui e-mel dan bukannya dipulangkan terus dalam respons API.

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	Senaraikan laporan lanjutan tersimpan untuk akaun yang disahkan.
POST	/api/v2/reports/save-advanced-report	Cipta atau kemas kini laporan lanjutan. Memerlukan reportType, toAddress, immediateRun dan sekurang-kurangnya satu sasaran adRoots atau domains.
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	Padam laporan lanjutan tersimpan mengikut id.

Jenis laporan

adUnit, dimensions, customData

Dimensi

country, device, os

Kekerapan

daily, weekly, biweekly, monthly

Inventori

Cipta dan padam unit iklan yang diluluskan

Operasi tulis inventori memerlukan akaun Sulvo yang diluluskan dan kunci API yang dijana oleh pemilik dengan skop inventory:write.

Cipta 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	Cipta satu unit iklan dengan domain, type, size pilihan, placement, name tersuai dan tetapan focusedAd.
PUT	/api/v2/inventory/interstitial-units	Cipta unit iklan interstisial untuk komputer meja dan/atau peranti mudah alih bagi satu domain.
PUT	/api/v2/inventory/auto-sticky-units	Cipta unit iklan paparan melekat dan/atau unit mudah alih melekat bagi satu domain.
DELETE	/api/v2/inventory/unit/{adId}	Padam unit iklan yang dimiliki oleh akaun yang disahkan.

Jenis unit iklan yang disokong

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Ralat

Pengendalian ralat

Respons audit bukan 2xx dan kegagalan API akaun Sulvo memulangkan isi respons JSON yang direka untuk klien ejen dan CLI.

401

Kunci API tiada, tidak sah atau sudah tamat tempoh untuk panggilan API akaun. Endpoint audit awam tidak memerlukan kunci.

403

Kunci berjaya mengesahkan akaun tetapi tidak mempunyai skop yang diperlukan, akaun belum diluluskan atau sumber tersebut milik akaun lain.

503 / 504

Perkhidmatan audit awam sesak atau audit tamat masa. Cuba lagi kemudian dan patuhi Retry-After jika disertakan.

Struktur respons ralat audit

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

Lebih suka klien yang disediakan dalam pakej?

Pakej npm dan persediaan MCP memanggil endpoint ini untuk anda dan menyediakan aliran kerja audit, laporan dan inventori yang sama kepada klien AI yang serasi.

Lihat persediaan