API: аудит доходів видавця

Запускайте публічну перевірку доходів видавця, отримуйте звіти Sulvo й керуйте схваленим рекламним інвентарем видавця через той самий інтерфейс API, що й CLI та сервер MCP.

Базова адреса сервера

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: 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.

Розширені звіти

Створюйте заплановані або негайні звіти з доставкою електронною поштою

Розширені звіти можна запускати одразу або регулярно за розкладом. Їх надсилають електронною поштою, а не повертають у відповіді API.

Зберегти розширений звіт

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, власну назву й налаштування 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 виконують ці запити за вас і надають сумісним клієнтам ШІ ті самі сценарії аудиту, звітності та роботи з рекламним інвентарем.

Переглянути налаштування