ตรวจสอบรายได้ผู้เผยแพร่ผ่าน API

เรียกใช้การตรวจสอบรายได้สาธารณะของผู้เผยแพร่ ดึงรายงานจาก Sulvo และจัดการพื้นที่โฆษณาของผู้เผยแพร่ที่ได้รับอนุมัติผ่าน API ชุดเดียวกับที่ CLI และเซิร์ฟเวอร์ MCP ใช้

ฐาน API ที่โฮสต์ไว้

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsตั้งค่า CLI และ MCP

ข้อมูลพื้นฐาน

URL พื้นฐาน

จุดปลายทางการตรวจสอบสาธารณะไม่ต้องยืนยันตัวตนตามที่ออกแบบไว้ ส่วนคำขอรายงานบัญชีและพื้นที่โฆษณาของ Sulvo ใช้คีย์ API ที่สร้างจากแดชบอร์ด

API ตรวจสอบสาธารณะ

POST

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

API บัญชี Sulvo

คีย์ API แบบ Bearer

https://surge.sulvo.com/api

จุดปลายทาง MCP ที่โฮสต์ไว้

MCP

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

จุดปลายทางสาธารณะ

เรียกใช้การตรวจสอบรายได้

ใช้จุดปลายทางนี้เพื่อตรวจคัดกรองโดเมนผู้เผยแพร่จากหลักฐานสาธารณะเพื่อประเมินแนวโน้ม ผลตอบกลับไม่ใช่หลักฐานยืนยันการสูญเสียรายได้หรือการเพิ่มขึ้นที่รับประกันไว้ ให้ตรวจสอบผลตรวจกับรายงานฝั่งผู้เผยแพร่

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

ฟิลด์	หมายเหตุ
input.domain	ต้องระบุโดเมนผู้เผยแพร่หรือโฮสต์สาธารณะ ระบบจะเติม HTTPS ให้โดเมนที่ไม่ได้ระบุโปรโตคอล ปฏิเสธปลายทางส่วนตัว หมายเลข IP ที่ระบุโดยตรง โฮสต์ภายใน และพอร์ตที่ไม่เป็นมาตรฐาน
input.vertical	ไม่บังคับ รับค่า news, sports, entertainment, technology, education, gaming หรือ other
input.metrics	ไม่บังคับ ใช้บริบทจากแดชบอร์ดที่ผู้เผยแพร่ระบุ เช่น อัตราการเติมโฆษณา การมองเห็นโฆษณา CPM เฉลี่ย รายได้ต่อเซสชัน จำนวนการเปิดดูหน้าเว็บต่อเดือน หรือเซสชันต่อเดือน
input.options	ไม่บังคับ ควบคุมผลลัพธ์และการเก็บข้อมูล เช่น format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel และ partnerId

การยืนยันตัวตน

ใช้คีย์ API ของ Sulvo สำหรับ API บัญชี

สร้างคีย์ API ในแดชบอร์ด Sulvo ที่การตั้งค่าบัญชี แล้วส่งเป็นโทเค็น Bearer ในคำขอ API บัญชีของ Sulvo

ส่วนหัว Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

ต้องใช้เพื่อส่งออกรายงานและแสดงรายการรายงานที่บันทึกไว้

reports:write

ต้องใช้เพื่อสร้าง อัปเดต เรียกใช้ หรือลบรายงานขั้นสูง

inventory:write

ต้องใช้เพื่อสร้างและลบหน่วยโฆษณา บัญชีต้องได้รับอนุมัติและเป็นเจ้าของพื้นที่โฆษณา

รายงาน

จุดปลายทางสำหรับอ่านรายงาน

คำขออ่านรายงานใช้ GET ภายใต้ API พื้นฐานของบัญชี Sulvo ค่าวันที่อย่างเดียวจะถูกตีความเป็นช่วงเวลาตลอดทั้งวันตาม UTC

คำขอรายงาน

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	สรุปประสิทธิภาพรายวัน กรองตามวันที่ โดเมน รากโฆษณา และผู้ให้บริการได้
GET	/api/v1/reports/by-date-and-ad-unit	จัดกลุ่มประสิทธิภาพรายวันตามหน่วยโฆษณา
GET	/api/v1/reports/by-domain-and-ad-unit	รายละเอียดประสิทธิภาพตามโดเมนและหน่วยโฆษณา
GET	/api/v1/reports/bot-filtering	รายงานการกรองบอทสำหรับตรวจสอบคุณภาพทราฟฟิกของบัญชี
GET	/api/v1/reports/bot-scores	รายงานคะแนนบอทตามวันที่และมิติข้อมูลที่เกี่ยวข้อง
GET	/api/v1/reports/invalid-activity	รายงานกิจกรรมที่ไม่ถูกต้อง ไม่ต้องระบุวันที่หรือโดเมนตามรูปแบบมาตรฐาน
GET	/api/v1/reports/direct-bidder-analysis	รายงานผู้เสนอราคาโดยตรง ต้องระบุ directBidder และระบุ start หรือ end ได้
GET	/api/v1/inventory/ad-units-by-domain	รายการหน่วยโฆษณาในพื้นที่โฆษณา จัดกลุ่มตามโดเมน

พารามิเตอร์คำขอทั่วไป: start, end, domains ที่ระบุซ้ำได้, adRoots ที่ระบุซ้ำได้ และ adProvider การวิเคราะห์ผู้เสนอราคาโดยตรงต้องระบุ directBidder ด้วย

รายงานขั้นสูง

สร้างรายงานทางอีเมลตามกำหนดเวลาหรือเรียกใช้ทันที

เรียกใช้รายงานขั้นสูงได้ทันทีหรือตั้งเวลาให้ทำซ้ำ ระบบส่งรายงานทางอีเมลแทนการส่งกลับมาในคำตอบโดยตรง

บันทึกรายงานขั้นสูง

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	แสดงรายการรายงานขั้นสูงที่บันทึกไว้ของบัญชีที่ยืนยันตัวตนแล้ว
POST	/api/v2/reports/save-advanced-report	สร้างหรืออัปเดตรายงานขั้นสูง ต้องระบุ reportType, toAddress, immediateRun และเป้าหมายอย่างน้อยหนึ่งรายการจาก adRoots หรือ domains
DELETE	/api/v2/reports/delete-advanced-report/{reportId}	ลบรายงานขั้นสูงที่บันทึกไว้ตาม id

ประเภทรายงาน

adUnit, dimensions, customData

มิติข้อมูล

country, device, os

ความถี่

daily, weekly, biweekly, monthly

พื้นที่โฆษณา

สร้างและลบหน่วยโฆษณาที่ได้รับอนุมัติ

การเขียนข้อมูลพื้นที่โฆษณาต้องใช้บัญชี Sulvo ที่ได้รับอนุมัติและคีย์ API ที่เจ้าของบัญชีสร้าง พร้อมขอบเขตสิทธิ์ inventory:write

สร้างหน่วยโฆษณา

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	สร้างหน่วยโฆษณาหนึ่งรายการด้วย domain, type, size ที่ไม่บังคับ, placement, custom name และการตั้งค่า focusedAd
PUT	/api/v2/inventory/interstitial-units	สร้างหน่วยโฆษณาคั่นหน้าสำหรับเดสก์ท็อป หรือมือถือ หรือทั้งสองแบบ สำหรับโดเมนหนึ่งรายการ
PUT	/api/v2/inventory/auto-sticky-units	สร้างหน่วยโฆษณาดิสเพลย์แบบติดหน้าจอ หรือหน่วยโฆษณามือถือแบบติดหน้าจอ สำหรับโดเมนหนึ่งรายการ
DELETE	/api/v2/inventory/unit/{adId}	ลบหน่วยโฆษณาที่บัญชีซึ่งยืนยันตัวตนแล้วเป็นเจ้าของ

ประเภทหน่วยโฆษณาที่รองรับ

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

ข้อผิดพลาด

การจัดการข้อผิดพลาด

คำตอบการตรวจสอบที่ไม่ใช่ 2xx และความล้มเหลวของ API บัญชี Sulvo จะส่งเนื้อหา JSON ที่ออกแบบมาสำหรับไคลเอนต์เอเจนต์และ CLI

401

คีย์ API สำหรับคำขอ API บัญชีขาดหายไป ไม่ถูกต้อง หรือหมดอายุ จุดปลายทางการตรวจสอบสาธารณะไม่ต้องใช้คีย์

403

ยืนยันตัวตนด้วยคีย์แล้ว แต่ขาดขอบเขตสิทธิ์ที่จำเป็น บัญชียังไม่ได้รับอนุมัติ หรือทรัพยากรเป็นของบัญชีอื่น

503 / 504

บริการตรวจสอบสาธารณะมีคำขอมากเกินไป หรือการตรวจสอบหมดเวลา ลองใหม่ภายหลังและปฏิบัติตาม Retry-After หากมี

รูปแบบข้อมูลข้อผิดพลาดการตรวจสอบ

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

ต้องการใช้ไคลเอนต์แบบแพ็กเกจหรือไม่

แพ็กเกจ npm และการตั้งค่า MCP เรียกใช้จุดปลายทางเหล่านี้ให้คุณ และเปิดให้ไคลเอนต์ AI ที่รองรับใช้ขั้นตอนการตรวจสอบ รายงาน และพื้นที่โฆษณาแบบเดียวกัน

ดูวิธีตั้งค่า