Документация за Publisher Revenue Audit API

Извършвайте публични проверки на приходите на издатели, извличайте отчетите на Sulvo и управлявайте одобрения инвентар на издателя чрез същия API, който използват CLI и MCP сървърът.

Хостван базов URL адрес

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 към базовия URL адрес на 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	Ежедневно обобщение на ефективността. Поддържа филтри по date, domain, ad root и provider.
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 клиенти същите работни процеси за одит, отчети и инвентар.

Разгледайте настройката