API ελέγχου εσόδων εκδοτών

Εκτελέστε δημόσιους ελέγχους εσόδων εκδοτών, ανακτήστε αναφορές Sulvo και διαχειριστείτε εγκεκριμένο διαφημιστικό απόθεμα εκδοτών μέσω του ίδιου API που χρησιμοποιούν το CLI και ο διακομιστής MCP.

Φιλοξενούμενο βασικό URL

https://publisher-revenue-audit.sulvo.com/v1/publisher-revenue-auditsΡύθμιση CLI και MCP

Βασικά

Βασικά URL

Το δημόσιο endpoint audit δεν απαιτεί σκόπιμα έλεγχο ταυτότητας. Οι αναφορές λογαριασμού Sulvo και οι κλήσεις αποθέματος χρησιμοποιούν κλειδί API που δημιουργείται στον πίνακα ελέγχου.

Δημόσιο API audit

POST

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

API λογαριασμού Sulvo

Κλειδί API Bearer

https://surge.sulvo.com/api

Φιλοξενούμενο endpoint MCP

MCP

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

Δημόσιο endpoint

Εκτέλεση audit εσόδων

Χρησιμοποιήστε αυτό το endpoint για ενδεικτικό έλεγχο δημόσια διαθέσιμων στοιχείων ενός τομέα εκδότη. Η απάντηση δεν αποτελεί απόδειξη απώλειας εσόδων ούτε εγγυημένης αύξησης. Επαληθεύστε τα ευρήματα με τις αναφορές της πλευράς του εκδότη.

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	Υποχρεωτικό. Τομέας εκδότη ή δημόσιος host. Οι τομείς χωρίς σχήμα μετατρέπονται σε HTTPS. Ιδιωτικοί προορισμοί, ακατέργαστες διευθύνσεις IP, εσωτερικοί host και μη τυπικές θύρες απορρίπτονται.
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, στην ενότητα Account Settings. Στείλτε το ως Bearer token στα αιτήματα API λογαριασμού Sulvo.

Κεφαλίδα Authorization

Authorization: Bearer $SULVO_API_KEY

reports:read

Απαιτείται για εξαγωγή αναφορών και εμφάνιση αποθηκευμένων αναφορών.

reports:write

Απαιτείται για δημιουργία, ενημέρωση, εκτέλεση ή διαγραφή σύνθετων αναφορών.

inventory:write

Απαιτείται για δημιουργία και διαγραφή διαφημιστικών μονάδων. Ο λογαριασμός πρέπει να έχει εγκριθεί και να κατέχει το απόθεμα.

Αναφορές

Endpoint ανάγνωσης αναφορών

Οι αναφορές ανάγνωσης χρησιμοποιούν αιτήματα 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	Αναφορά φιλτραρίσματος bot για έλεγχο ποιότητας επισκεψιμότητας λογαριασμού.
GET	/api/v1/reports/bot-scores	Αναφορά βαθμολογίας bot ανά ημερομηνία και σχετικές διαστάσεις.
GET	/api/v1/reports/invalid-activity	Αναφορά μη έγκυρης δραστηριότητας. Δεν απαιτείται τυπικό ερώτημα ημερομηνίας/τομέα.
GET	/api/v1/reports/direct-bidder-analysis	Αναφορά άμεσου bidder. Απαιτεί directBidder και μπορεί να περιλαμβάνει start/end.
GET	/api/v1/inventory/ad-units-by-domain	Απόθεμα διαφημιστικών μονάδων ομαδοποιημένο ανά τομέα.

Συνήθεις παράμετροι ερωτήματος: start, end, επαναλαμβανόμενα domains, επαναλαμβανόμενα adRoots και adProvider. Η ανάλυση άμεσων bidders απαιτεί επίσης directBidder.

Σύνθετες αναφορές

Δημιουργήστε προγραμματισμένες αναφορές email ή εκτελέστε τις αμέσως

Οι σύνθετες αναφορές μπορούν να εκτελεστούν αμέσως ή να επαναλαμβάνονται βάσει προγράμματος. Παραδίδονται μέσω email αντί να επιστρέφονται ενσωματωμένα στην απόκριση.

Αποθήκευση σύνθετης αναφοράς

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 που δημιουργήθηκε από τον κάτοχο με scope 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	Δημιουργήστε παρεμβαλλόμενες μονάδες για desktop ή/και κινητά για έναν τομέα.
PUT	/api/v2/inventory/auto-sticky-units	Δημιουργήστε σταθερές μονάδες display ή/και σταθερές μονάδες για κινητά για έναν τομέα.
DELETE	/api/v2/inventory/unit/{adId}	Διαγράψτε διαφημιστική μονάδα που ανήκει στον πιστοποιημένο λογαριασμό.

Υποστηριζόμενοι τύποι διαφημιστικών μονάδων

displaynative_multisticky_displaysticky_mobilesticky_display_customsticky_mobile_customsticky_videointerstitial_desktopinterstitial_mobileofferwall

Σφάλματα

Διαχείριση σφαλμάτων

Αποκρίσεις audit εκτός 2xx και αποτυχίες API λογαριασμού Sulvo επιστρέφουν σώματα JSON σχεδιασμένα για agent και πελάτες CLI.

401

Το κλειδί API λείπει, είναι άκυρο ή έχει λήξει για κλήσεις API λογαριασμού. Το δημόσιο endpoint audit δεν απαιτεί κλειδί.

403

Το κλειδί πιστοποιήθηκε, αλλά δεν έχει το απαιτούμενο scope, ο λογαριασμός δεν έχει εγκριθεί ή ο πόρος ανήκει σε διαφορετικό λογαριασμό.

503 / 504

Η δημόσια υπηρεσία audit είναι υπερφορτωμένη ή έληξε το χρονικό όριο του audit. Δοκιμάστε ξανά αργότερα και τηρήστε το Retry-After, εφόσον υπάρχει.

Δομή σφάλματος audit

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

Προτιμάτε ένα πρόγραμμα-πελάτη διαθέσιμο ως πακέτο;

Το πακέτο npm και η ρύθμιση MCP καλούν αυτά τα endpoint για εσάς και παρέχουν στους συμβατούς AI πελάτες τις ίδιες ροές εργασίας audit, αναφορών και αποθέματος.

Προβολή ρύθμισης