Chuyển đến nội dung
Chạy chẩn đoán miễn phí
Tìm kiếm Sulvo
Gợi ý để bắt đầu6 trang

Tìm thấy 6 trang.

↑↓ để khám phá↵ để mở

API kiểm toán doanh thu nhà xuất bản

Chạy bài kiểm tra công khai về doanh thu nhà xuất bản, lấy báo cáo Sulvo và quản lý khoảng không quảng cáo đã được phê duyệt qua cùng API mà CLI và máy chủ MCP sử dụng.

URL cơ sở được lưu trữ

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsHướng dẫn thiết lập CLI và MCP

Thông tin cơ bản

URL cơ sở

Endpoint kiểm toán công khai được thiết kế để không yêu cầu xác thực. Các yêu cầu về báo cáo tài khoản Sulvo và khoảng không quảng cáo dùng khóa API được tạo trong trang tổng quan.

API kiểm toán công khai

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

API tài khoản Sulvo

Khóa API dạng Bearer
https://surge.sulvo.com/api

Endpoint MCP được lưu trữ

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

Endpoint công khai

Chạy kiểm toán doanh thu

Dùng endpoint này để chạy bài kiểm tra sơ bộ dựa trên bằng chứng công khai về tên miền của nhà xuất bản. Phản hồi không chứng minh doanh thu bị mất hay mức tăng được đảm bảo. Hãy đối chiếu kết quả với báo cáo phía nhà xuất bả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
      }
    }
  }'
TrườngGhi chú
input.domainTên miền nhà xuất bản hoặc máy chủ công khai là bắt buộc. Tên miền không kèm giao thức sẽ được chuẩn hóa thành HTTPS. Các đích riêng tư, địa chỉ IP thô, máy chủ nội bộ và cổng không chuẩn sẽ bị từ chối.
input.verticalKhông bắt buộc. Chấp nhận news, sports, entertainment, technology, education, gaming hoặc other.
input.metricsKhông bắt buộc. Ngữ cảnh trong trang tổng quan do nhà xuất bản cung cấp, chẳng hạn như tỷ lệ lấp đầy, khả năng hiển thị, CPM trung bình, doanh thu mỗi phiên, lượt xem trang hàng tháng hoặc số phiên hàng tháng.
input.optionsCác tùy chọn không bắt buộc để kiểm soát đầu ra và việc thu thập dữ liệu, gồm format, compact, maxPages, includeEvidence, enableBrowser, includeScreenshots, enablePageSpeed, pageSpeedStrategy, concurrency, whiteLabel và partnerId.

Xác thực

Dùng khóa API Sulvo cho API tài khoản

Tạo khóa API trong trang tổng quan Sulvo, tại mục Cài đặt tài khoản. Gửi khóa này dưới dạng Bearer token trong các yêu cầu đến API tài khoản Sulvo.

Header Authorization
Authorization: Bearer $SULVO_API_KEY

reports:read

Bắt buộc để xuất báo cáo và liệt kê báo cáo đã lưu.

reports:write

Bắt buộc để tạo, cập nhật, chạy hoặc xóa báo cáo nâng cao.

inventory:write

Bắt buộc để tạo và xóa đơn vị quảng cáo. Tài khoản phải được phê duyệt và sở hữu khoảng không quảng cáo đó.

Báo cáo

Đọc dữ liệu từ endpoint báo cáo

Các yêu cầu đọc báo cáo dùng GET trong API tài khoản Sulvo. Giá trị chỉ có ngày được hiểu là phạm vi trọn ngày theo UTC.

Yêu cầu báo cáo
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"
MethodPathNotes
GET/api/v1/reports/by-dateTóm tắt hiệu suất hàng ngày. Hỗ trợ bộ lọc date, domain, ad root và provider.
GET/api/v1/reports/by-date-and-ad-unitHiệu suất hàng ngày, được nhóm theo đơn vị quảng cáo.
GET/api/v1/reports/by-domain-and-ad-unitPhân tích hiệu suất theo tên miền và đơn vị quảng cáo.
GET/api/v1/reports/bot-filteringBáo cáo lọc bot để đánh giá chất lượng lưu lượng truy cập trong tài khoản.
GET/api/v1/reports/bot-scoresBáo cáo điểm bot theo ngày và các chiều dữ liệu liên quan.
GET/api/v1/reports/invalid-activityBáo cáo hoạt động không hợp lệ. Không cần truy vấn ngày hoặc tên miền theo tiêu chuẩn.
GET/api/v1/reports/direct-bidder-analysisBáo cáo về bên đặt giá trực tiếp. Bắt buộc có directBidder, có thể gồm start và end.
GET/api/v1/inventory/ad-units-by-domainCác đơn vị quảng cáo trong khoảng không quảng cáo, được nhóm theo tên miền.

Tham số truy vấn thường dùng: start, end, domains có thể lặp lại, adRoots có thể lặp lại và adProvider. Phân tích bên đặt giá trực tiếp cũng yêu cầu directBidder.

Báo cáo nâng cao

Tạo báo cáo qua email theo lịch hoặc gửi ngay

Báo cáo nâng cao có thể chạy ngay hoặc lặp lại theo lịch. Báo cáo được gửi qua email thay vì trả về trực tiếp trong phản hồi.

Lưu báo cáo nâng cao
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"
  }'
MethodPathNotes
GET/api/v2/reports/advanced-reportsLiệt kê các báo cáo nâng cao đã lưu cho tài khoản được xác thực.
POST/api/v2/reports/save-advanced-reportTạo hoặc cập nhật báo cáo nâng cao. Bắt buộc có reportType, toAddress, immediateRun và ít nhất một đích adRoots hoặc domains.
DELETE/api/v2/reports/delete-advanced-report/{reportId}Xóa báo cáo nâng cao đã lưu theo id.

Loại báo cáo

adUnit, dimensions, customData

Chiều dữ liệu

country, device, os

Tần suất

daily, weekly, biweekly, monthly

Khoảng không quảng cáo

Tạo và xóa đơn vị quảng cáo đã được phê duyệt

Thao tác ghi vào khoảng không quảng cáo yêu cầu tài khoản Sulvo đã được phê duyệt và khóa API do chủ tài khoản tạo, có quyền inventory:write.

Tạo đơn vị quảng cáo
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 }
  }'
MethodPathNotes
PUT/api/v2/inventory/unitTạo một đơn vị quảng cáo với domain, type, size không bắt buộc, placement, custom name và thiết lập focusedAd.
PUT/api/v2/inventory/interstitial-unitsTạo đơn vị quảng cáo xen kẽ cho máy tính để bàn và/hoặc thiết bị di động của một tên miền.
PUT/api/v2/inventory/auto-sticky-unitsTạo đơn vị quảng cáo hiển thị cố định và/hoặc đơn vị quảng cáo di động cố định cho một tên miền.
DELETE/api/v2/inventory/unit/{adId}Xóa đơn vị quảng cáo thuộc sở hữu của tài khoản đã xác thực.

Các loại đơn vị quảng cáo được hỗ trợ

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Lỗi

Xử lý lỗi

Phản hồi kiểm toán có mã HTTP ngoài nhóm 2xx và lỗi API tài khoản Sulvo đều trả về nội dung JSON dành cho agent và ứng dụng CLI.

401

Khóa API bị thiếu, không hợp lệ hoặc hết hạn khi gọi API tài khoản. Endpoint kiểm toán công khai không yêu cầu khóa.

403

Khóa đã xác thực nhưng thiếu phạm vi quyền bắt buộc, tài khoản chưa được phê duyệt hoặc tài nguyên thuộc tài khoản khác.

503 / 504

Dịch vụ kiểm toán công khai đang quá tải hoặc thời gian chờ kiểm toán đã hết. Hãy thử lại sau và làm theo Retry-After nếu có.

Cấu trúc phản hồi lỗi kiểm toán
{
  "error": {
    "code": "audit_capacity_exceeded",
    "message": "Audit capacity is currently exhausted. Retry later."
  }
}

Muốn dùng bộ công cụ đóng gói sẵn?

Gói npm và hướng dẫn thiết lập MCP gọi các endpoint này thay bạn, đồng thời cung cấp cùng quy trình kiểm toán, báo cáo và khoảng không quảng cáo cho các ứng dụng AI tương thích.

Xem hướng dẫn thiết lập