Τεκμηρίωση API SSP
API πλατφόρμας πλευράς προσφοράς για πλατφόρμες προγραμματικής διαφήμισης
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 αιτήματα ανά λεπτό
Το όριο ρυθμού αιτημάτων εφαρμόζεται ανά διακριτικό SSP
PUT /online-advertisement/{PAID}/metrics
1.000 αιτήματα ανά λεπτό
Τα αιτήματα μετρώνται ανά διακριτικό SSP, χωριστά από το τελικό σημείο ετικέτας, ώστε η αναφορά μετρήσεων να μην εξαντλεί ποτέ τα αιτήματά σας για ετικέτες
/online-advertisement/{PAID}📊 Συμπαγής μορφή ετικέτας
Αυτό το τελικό σημείο επιστρέφει μια συμπαγή ετικέτα διαφάνειας, σύμφωνη με τους κανόνες της ΕΕ, κατάλληλη για εμφάνιση δίπλα σε διαδικτυακές διαφημίσεις. Λειτουργεί μόνο για διαφημίσεις με μέσο = "online".
Παράδειγμα αιτήματος
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Παράδειγμα απόκρισης
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Πεδία απόκρισης
Παράδειγμα χρήσης
Εμφάνιση της ετικέτας στην πλατφόρμα σας:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsΤο διακριτικό SSP σας χρειάζεται το δικαίωμα metrics:write. Ένας διαχειριστής το ενεργοποιεί στο διακριτικό που ήδη χρησιμοποιείτε, οπότε δεν εκδίδεται νέο διακριτικό.
Να στέλνετε τα σωρευτικά σύνολα από τη δημοσίευση της ανακοίνωσης, ποτέ τη μεταβολή από την τελευταία σας αποστολή. Κάθε αποστολή αντικαθιστά τα προηγούμενα στοιχεία, οπότε αν στείλετε ξανά τα ίδια σύνολα δεν αλλάζει τίποτα.
Μπορείτε να υποβάλετε αναφορά για οποιαδήποτε δημοσιευμένη ανακοίνωση, ανεξάρτητα από τον εκδότη στον οποίο ανήκει. Τα στοιχεία εμφανίζονται στη δημόσια ανακοίνωση διαφάνειάς της μαζί με την ημερομηνία της τελευταίας αναφοράς τους.
Παράδειγμα αιτήματος
curl -X PUT "https://polads.eu/api/v1/online-advertisement/ABC12/metrics" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"viewsCount": 15000, "engagementsCount": 320}'Πεδία αιτήματος
Και τα δύο πεδία είναι υποχρεωτικά, το καθένα ακέραιος αριθμός από 0 έως 2147483647.
Παράδειγμα απόκρισης
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Αποκρίσεις σφάλματος από αυτό το τελικό σημείο
401 INVALID_TOKEN
Η κεφαλίδα Authorization λείπει ή το διακριτικό είναι άγνωστο, έχει ανακληθεί ή είναι διακριτικό συνεργάτη. Και στις δύο περιπτώσεις επιστρέφεται ο κωδικός INVALID_TOKEN.
{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>",
"code": "INVALID_TOKEN"
}{
"error": "Invalid or revoked SSP API token.",
"code": "INVALID_TOKEN"
}403 INSUFFICIENT_SCOPE
Το διακριτικό είναι έγκυρο, αλλά δεν του έχει δοθεί το δικαίωμα metrics:write. Ζητήστε από τον διαχειριστή σας να το ενεργοποιήσει.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Καμία δημοσιευμένη ανακοίνωση δεν αντιστοιχεί σε αυτό το PA-ID. Όπως και στο τελικό σημείο ετικέτας, μια ανακοίνωση που δεν έχει ακόμη εγκριθεί από τον εκδότη της ή της οποίας η ημερομηνία έναρξης δημοσίευσης βρίσκεται ακόμη στο μέλλον επιστρέφει επίσης 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
Η ανακοίνωση βρίσκεται εκτός του πεδίου για το οποίο ορίζονται οι μετρήσεις αλληλεπίδρασης. Η σημείωση 15 του παραρτήματος II καλύπτει επιγραμμική ή εγγενή ανακοίνωση που χρησιμοποίησε τεχνικές στόχευσης ή τεχνικές παράδοσης διαφημίσεων και έχει αρχίσει να προβάλλεται. Δεν καταχωρίζεται τίποτα.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Το σώμα του αιτήματος δεν είναι έγκυρο JSON ή οι δύο τιμές μέτρησης λείπουν, είναι αρνητικές ή δεν είναι ακέραιες. Η απόκριση αναφέρει τι απέτυχε.
{
"error": "Invalid engagement metrics",
"code": "INVALID_METRICS",
"issues": [
{
"path": "viewsCount",
"message": "Too small: expected number to be >=0"
}
]
}{
"error": "Invalid request body",
"code": "INVALID_METRICS"
}429 RATE_LIMITED
Το όριο ανά διακριτικό ξεπεράστηκε. Η απόκριση περιλαμβάνει τις κεφαλίδες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Μορφή κεφαλίδας
Authorization: Bearer YOUR_SSP_TOKENΜορφή διακριτικού
Δεκαεξαδική συμβολοσειρά 64 χαρακτήρων (εντροπία 256 bit)
Διαχείριση διακριτικών
Η διαχείριση των διακριτικών SSP γίνεται μόνο από διαχειριστές συστήματος. Επικοινωνήστε με τον διαχειριστή σας για να λάβετε διακριτικό.
Δεν ισχύει κανένα πρόγραμμα συνδρομής
Ένα διακριτικό SSP εκδίδεται σε ενσωματωτή και όχι σε εκδότη, οπότε δεν συνδέεται με κανέναν λογαριασμό εκδότη και δεν υπάρχει πρόγραμμα προς έλεγχο. Σε αντίθεση με το API συνεργατών, εδώ τίποτα δεν εξαρτάται από συνδρομή. Ένα διακριτικό συνεργάτη απορρίπτεται σε αυτό το τελικό σημείο με κωδικό 401, και ένα διακριτικό SSP απορρίπτεται με τον ίδιο τρόπο στα τελικά σημεία συνεργατών.
Πότε το τελικό σημείο επιστρέφει 404
Η ανακοίνωση εντοπίζεται με τον ίδιο κανόνα ορατότητας που ισχύει για το δημόσιο μητρώο. Μια ανακοίνωση που δεν έχει ακόμη επιβεβαιωθεί, που δεν έχει ακόμη εγκριθεί από τον εκδότη της ή της οποίας η ημερομηνία έναρξης δημοσίευσης βρίσκεται ακόμη στο μέλλον επιστρέφει 404. Επομένως, ένας κωδικός 404 δεν αποδεικνύει ότι ένα PA-ID είναι λανθασμένο.
Το παραπάνω τελικό σημείο επιστρέφει το ΚΕΙΜΕΝΟ της ετικέτας σε μία γραμμή, για ετικέτα που σχεδιάζει η δική σας πλατφόρμα. Το σήμα επιστρέφει μια έτοιμη, διαδραστική ανακοίνωση, την οποία τοποθετείτε δίπλα στη διαφήμιση ως ενσωματωμένο πλαίσιο. Και τα δύο περιγράφουν την ίδια ανακοίνωση διαφάνειας.
Μία διεύθυνση URL ανά έκδοση
Τα χειριστήρια της επίδειξης αντιστοιχούν ένα προς ένα σε αυτές τις παραμέτρους, οπότε μπορείτε να επιλέξετε στη σελίδα επίδειξης και να αντιγράψετε τη διεύθυνση URL που βλέπετε.
# Σήμα γωνίας, μόνο το σύμβολο
GET https://polads.eu/badge/{PA-ID}
# Σήμα γωνίας με το κείμενό του
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Μόνιμα ορατή λωρίδα ετικέτας
GET https://polads.eu/badge/{PA-ID}?layout=labelΤι κάνει κάθε παράμετρος και τι σημαίνει η παράλειψή της
Το layout=label επιλέγει τη λωρίδα. Αν το παραλείψετε, εμφανίζεται το σήμα γωνίας. Το variant=labelled κάνει το κλειστό σήμα να εμφανίζει το κείμενό του. Αν το παραλείψετε, εμφανίζεται μόνο το σύμβολο. Τα w και h δηλώνουν τον χώρο όπου βρίσκεται το σήμα και καθορίζουν πώς προσαρμόζεται σε στενό χώρο. Αν τα παραλείψετε, το σήμα θεωρεί ότι έχει αρκετό χώρο, κάτι που ισχύει για τις τυπικές μορφές.
Το hover=0 αφορά την επίδειξη, όχι τη σελίδα σας
Επιβάλλει τη διάταξη χωρίς αιώρηση δείκτη, ώστε η επίδειξη να δείχνει την έκδοση αφής σε πρόγραμμα περιήγησης υπολογιστή. Το πραγματικό σήμα ελέγχει μόνο του τη συσκευή. Αν το ορίσετε σταθερά, στέλνετε λάθος έκδοση σε κάθε επισκέπτη του οποίου η συσκευή δεν ταιριάζει με αυτήν.
Ο ακροατής αλλαγής μεγέθους είναι υποχρεωτικός
Το σήμα γωνίας φορτώνει σε μέγεθος 32 επί 32, ώστε να καλύπτει όσο το δυνατόν λιγότερο από το διαφημιστικό υλικό, και όταν ανοίγει ζητά χώρο από τη σελίδα υποδοχής. Χωρίς τον ακροατή δεν μπορεί να ανοίξει καθόλου. Η λωρίδα ετικέτας προσαρμόζεται πιο ομαλά και περικόπτεται μόνο σε στενά πλάτη.
Διαθέσιμο μόνο για δημοσιευμένη ανακοίνωση
Το σήμα παρέχεται όταν η ανακοίνωση έχει επιβεβαιωθεί, έχει εγκριθεί από τον εκδότη και έχει παρέλθει η ημερομηνία έναρξης δημοσίευσής της. Ένα PA-ID σε αναμονή δημοσίευσης ή χωρίς έγκριση επιστρέφει 404 σκόπιμα, όχι λόγω σφάλματος.
Ανοίξτε τη διαδραστική επίδειξη και αντιγράψτε τον κώδικα ενσωμάτωσης
401 Μη εξουσιοδοτημένο
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Εσφαλμένο αίτημα
Η διαφήμιση βρέθηκε, αλλά το μέσο της δεν είναι online. Η απόκριση επιστρέφει την πραγματική τιμή του μέσου, για παράδειγμα print. Ένα PA-ID που λείπει ή είναι άγνωστο επιστρέφει 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Δεν βρέθηκε
{
"error": "Advertisement not found"
}429 Υπέρβαση ορίου αιτημάτων
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Αυτή είναι η έκδοση API v1, και κάθε απόκριση το δηλώνει σε κεφαλίδα X-API-Version. Οι ασύμβατες αλλαγές κυκλοφορούν σε νέα διαδρομή αντί να αλλάζουν αυτήν. Ένα τελικό σημείο v1 δεν θα απενεργοποιηθεί χωρίς κεφαλίδα Deprecation τουλάχιστον 90 ημέρες νωρίτερα, σύμφωνα με το RFC 8594.
Προδιαγραφή αναγνώσιμη από μηχανή
Το πλήρες έγγραφο OpenAPI 3.1 παρέχεται στο /api/docs. Στρέψτε το Postman, το Swagger UI ή μια γεννήτρια πελάτη κατευθείαν εκεί αντί να μεταγράψετε αυτή τη σελίδα.
https://polads.eu/api/docs