Doiciméadú API SSP

API ardáin ar thaobh an tsoláthair d’ardáin fógraíochta ríomhchláraithe

API, leagan 1

Comhartha iompróra SSP ag teastáil

Tréchur ard

Bun-URL

https://polads.eu/api/v1

Teorainn ráta

Tréchur ard d’ardáin fógraíochta ríomhchláraithe

GET /online-advertisement/{PAID}

10,000 iarratas in aghaidh an nóiméid

Teorainn ráta curtha i bhfeidhm in aghaidh gach comhartha SSP

PUT /online-advertisement/{PAID}/metrics

1,000 iarratas in aghaidh an nóiméid

Áirítear na hiarratais in aghaidh gach comhartha SSP, ar leithligh ón gcríochphointe lipéid, ionas nach n-ídíonn tuairisciú méadrachtaí d’iarratais lipéid choíche

GET

/online-advertisement/{PAID}

Faigh lipéad trédhearcachta formáidithe d’fhógraí ar líne

📊 Formáid lipéid dhlúth

Tugann an críochphointe seo lipéad trédhearcachta dlúth ar ais atá i gcomhréir le rialacha an AE agus atá oiriúnach le taispeáint in aice le fógraí ar líne. Ní oibríonn sé ach d’fhógraí a bhfuil medium = "online" acu.

Comhartha Bearer SSP

PA-ID

Iarratas samplach

curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Accept: application/json"

Freagra samplach

{
  "text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
  "link": "https://polads.eu/ABC12",
  "PAID": "ABC12"
}

Réimsí an fhreagra

text

string

Téacs lipéid formáidithe

link

string

URL an leathanaigh trédhearcachta

PAID

string

Aitheantóir na fógraíochta polaitiúla

Sampla úsáide

Taispeáin an lipéad ar d’ardán:

<a href="[link]" target="_blank" rel="noopener">
  [text]
</a>

Tuairiscigh méadrachtaí rannpháirtíochta

PUT

/online-advertisement/{PAID}/metrics

Tuairiscigh líon carnach na n-amharc agus na n-idirghníomhaíochtaí ar fhógra foilsithe a sheachaid tú

Teastaíonn an cead metrics:write ó do chomhartha SSP. Cuireann riarthóir an cead ar siúl don chomhartha atá in úsáid agat cheana, mar sin ní eisítear comhartha nua.

Seol na hiomláin reatha ón uair a foilsíodh an fógra, agus ná seol riamh an t-athrú ó do sheachadadh deireanach. Tagann gach seachadadh in ionad na bhfigiúirí a bhí roimhe, mar sin ní athraíonn aon rud má sheoltar na hiomláin chéanna arís.

Is féidir leat aon fhógra foilsithe a thuairisciú, is cuma cén foilsitheoir ar leis é. Taispeántar na figiúirí ar a fhógra trédhearcachta poiblí mar aon leis an dáta a tuairiscíodh iad den uair dheireanach.

Iarratas samplach

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}'

Réimsí an iarratais

viewsCount

integer

Líon na n-amharc ar an bhfógrán ó foilsíodh é

engagementsCount

integer

Líon na n-idirghníomhaíochtaí leis an bhfógrán (cliceanna, moltaí agus tráchtanna) ó foilsíodh é

Tá an dá réimse riachtanach, agus is slánuimhir ó 0 go 2147483647 gach ceann acu.

Freagra samplach

{
  "viewsCount": 15000,
  "engagementsCount": 320,
  "engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}

Freagraí earráide ón gcríochphointe seo

401 INVALID_TOKEN

Tá an ceanntásc Authorization ar iarraidh, nó tá an comhartha anaithnid, cúlghairthe nó ina chomhartha comhpháirtí. Bíonn an cód INVALID_TOKEN sa dá chás.

{
  "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

Tá an comhartha bailí ach níor tugadh an cead metrics:write dó. Iarr ar do riarthóir é a chur ar siúl.

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

404 NOT_FOUND

Níl aon fhógra foilsithe ag teacht leis an PA-ID sin. Mar a tharlaíonn ar an gcríochphointe lipéid, tugtar 404 ar ais freisin d’fhógra nach bhfuil faofa fós ag a fhoilsitheoir, nó a bhfuil dáta tosaigh a fhoilsithe fós amach anseo.

{
  "error": "Advertisement not found",
  "code": "NOT_FOUND"
}

409 METRICS_NOT_APPLICABLE

Tá an fógra lasmuigh den raon a bhfuil méadrachtaí rannpháirtíochta sainmhínithe ina leith. Cumhdaíonn nóta 15 d'Iarscríbhinn II fógra ar líne nó dúchasach inar úsáideadh teicnící spriocdhírithe nó teicnící seachadta fógráin agus atá tosaithe ag rith. Ní scríobhtar aon rud.

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

400 INVALID_METRICS

Níl corp an iarratais ina JSON bailí, nó tá an dá chomhaireamh ar iarraidh nó diúltach, nó ní slánuimhreacha iad. Liostaíonn an freagra cad a theip.

{
  "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

Sáraíodh an teorainn in aghaidh an chomhartha. Bíonn na ceanntásca X-RateLimit-Limit, X-RateLimit-Remaining agus X-RateLimit-Reset san fhreagra seo.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Fíordheimhniú

Formáid an cheanntáisc

Authorization: Bearer YOUR_SSP_TOKEN

Formáid an chomhartha

Teaghrán heicsidheachúlach 64 carachtar (eantrópacht 256 giotán)

Bainistiú comharthaí

Is iad riarthóirí córais amháin a bhainistíonn comharthaí SSP. Déan teagmháil le do riarthóir chun comhartha a fháil.

Riachtanais rochtana

Níl feidhm ag aon phlean síntiúis

Eisítear comhartha SSP chuig comhtháthóir seachas chuig foilsitheoir, mar sin ní bhaineann aon chuntas foilsitheora leis agus níl aon phlean le seiceáil. Murab ionann agus API na gcomhpháirtithe, níl aon rud anseo ag brath ar shíntiús. Diúltaítear do chomhartha comhpháirtí ar an gcríochphointe seo le 401, agus diúltaítear do chomhartha SSP ar chríochphointí na gcomhpháirtithe ar an gcaoi chéanna.

Nuair a thugann an críochphointe 404 ar ais

Réitítear an fógra de réir na rialach infheictheachta céanna a bhaineann leis an gclár poiblí. Tugtar 404 ar ais d’fhógra nach bhfuil deimhnithe fós, nach bhfuil faofa fós ag a fhoilsitheoir, nó a bhfuil dáta tosaigh a fhoilsithe fós amach anseo. Mar sin, ní cruthúnas é 404 go bhfuil PA-ID mícheart.

Suaitheantas trédhearcachta

An nochtadh céanna, curtha i láthair d’fhógrán atá á sheachadadh

Tugann an críochphointe thuas TÉACS an lipéid aon líne ar ais, le haghaidh lipéid a tharraingíonn d’ardán féin. Tugann an suaitheantas fógra idirghníomhach rindreáilte ar ais, a chuireann tú in aice leis an bhfógrán mar iframe. Déanann an dá cheann cur síos ar an bhfógra trédhearcachta céanna.

URL amháin do gach leagan

Freagraíonn gach rialtán sa taispeántas do pharaiméadar amháin díobh seo, mar sin is féidir leat do rogha a dhéanamh ar leathanach an taispeántais agus an URL a fheiceann tú a chóipeáil.

# Suaitheantas cúinne, an marc amháin
GET https://polads.eu/badge/{PA-ID}

# Suaitheantas cúinne a thaispeánann a théacs
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stiall lipéid a bhíonn le feiceáil i gcónaí
GET https://polads.eu/badge/{PA-ID}?layout=label

Cad a dhéanann gach paraiméadar, agus cad is brí lena fhágáil ar lár

Roghnaíonn layout=label an stiall. Fág ar lár é chun an suaitheantas cúinne a fháil. Le variant=labelled taispeánann an suaitheantas dúnta a théacs. Fág ar lár é chun an marc amháin a fháil. Dearbhaíonn w agus h an spás ina suíonn an suaitheantas agus socraíonn siad conas a oiriúnaíonn sé do spás cúng. Fág ar lár iad agus glacann an suaitheantas leis go bhfuil spás aige, rud atá ceart do na formáidí caighdeánacha.

Is don taispeántas é hover=0, ní do do leathanach

Cuireann sé an leagan amach gan foluain i bhfeidhm ionas gur féidir leis an taispeántas an leagan tadhaill a thaispeáint i mbrabhsálaí deisce. Seiceálann an fíor-shuaitheantas an gléas é féin. Má shocraíonn tú an luach go buan, seolfaidh tú an leagan mícheart chuig gach cuairteoir nach n-oireann a ghléas don socrú sin.

Tá gá leis an éisteoir athraithe méide

Lódálann an suaitheantas cúinne ag 32 faoi 32 ionas go gclúdaíonn sé an méid is lú is féidir den ábhar cruthaitheach, agus ansin iarrann sé spás ar an leathanach óstach nuair a osclaíonn sé. Gan an t-éisteoir ní féidir leis oscailt ar chor ar bith. Oiriúnaíonn an stiall lipéid níos séimhe, agus ní bhearrtar í ach nuair atá an leithead cúng.

Ar fáil d’fhógra foilsithe amháin

Cuirtear an suaitheantas ar fáil a luaithe a bhíonn an fógra deimhnithe, faofa ag an bhfoilsitheoir agus a dháta tosaigh foilsithe caite. Tugann PA-ID atá faoi chosc foilsithe nó nach bhfuil faofa 404 ar ais d’aon ghnó, ní de bharr earráide.

Oscail an taispeántas idirghníomhach agus cóipeáil an cód leabaithe

Freagraí earráide

Tugann gach earráid corp JSON ar ais ina bhfuil teachtaireacht earráide, agus bíonn ceanntásc X-API-Version ag gach freagra. Ní thugann an críochphointe lipéid réimse cóid inléite ag meaisín ar ais, mar sin bunaigh do mheaitseáil ar a stádas HTTP seachas ar an gcorp. Bíonn cód ag earráidí an chríochphointe méadrachtaí, áfach, agus tá siad liostaithe thuas leis an gcríochphointe sin.

401 Gan údar

{
  "error": "Invalid or revoked SSP API token."
}

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}

400 Iarratas neamhbhailí

Fuarthas an fógra, ach níl a mheán online. Cuireann an freagra fíorluach an mheáin ar ais, mar shampla print. Cuireann PA-ID atá ar iarraidh nó anaithnid 404 ar ais ina ionad.

{
  "error": "This endpoint is only for online advertisements",
  "medium": "print"
}

404 Gan aimsiú

{
  "error": "Advertisement not found"
}

429 Sáraíodh an teorainn ráta

{
  "error": "Rate limit exceeded",
  "limit": 10000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Leaganú agus díchoimisiúnú

Is é seo leagan v1 den API, agus luann gach freagra é sin i gceanntásc X-API-Version. Foilsítear athruithe a bhriseann comhoiriúnacht faoi chosán nua seachas an ceann seo a athrú. Ní mhúchfar críochphointe v1 gan ceanntásc Deprecation a sheoladh 90 lá ar a laghad roimh ré, de réir RFC 8594.

Sonraíocht inléite ag meaisín

Tá an doiciméad iomlán OpenAPI 3.1 ar fáil ag /api/docs. Dírigh Postman, Swagger UI nó gineadóir cliaint air go díreach seachas an leathanach seo a thras-scríobh.

https://polads.eu/api/docs

An bhfuil tú ag comhtháthú mar chomhpháirtí meán nó foilsitheora? Léigh doiciméadú API na gcomhpháirtithe

Doiciméadú API SSP

API ardáin ar thaobh an tsoláthair d’ardáin fógraíochta ríomhchláraithe

API, leagan 1

Comhartha iompróra SSP ag teastáil

Tréchur ard

Bun-URL

https://polads.eu/api/v1

Teorainn ráta

Tréchur ard d’ardáin fógraíochta ríomhchláraithe

GET /online-advertisement/{PAID}

10,000 iarratas in aghaidh an nóiméid

Teorainn ráta curtha i bhfeidhm in aghaidh gach comhartha SSP

PUT /online-advertisement/{PAID}/metrics

1,000 iarratas in aghaidh an nóiméid

Áirítear na hiarratais in aghaidh gach comhartha SSP, ar leithligh ón gcríochphointe lipéid, ionas nach n-ídíonn tuairisciú méadrachtaí d’iarratais lipéid choíche

GET

/online-advertisement/{PAID}

Faigh lipéad trédhearcachta formáidithe d’fhógraí ar líne

📊 Formáid lipéid dhlúth

Comhartha Bearer SSP

PA-ID

Iarratas samplach

curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Accept: application/json"

Freagra samplach

{
  "text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
  "link": "https://polads.eu/ABC12",
  "PAID": "ABC12"
}

Réimsí an fhreagra

text

string

Téacs lipéid formáidithe

link

string

URL an leathanaigh trédhearcachta

PAID

string

Aitheantóir na fógraíochta polaitiúla

Sampla úsáide

Taispeáin an lipéad ar d’ardán:

<a href="[link]" target="_blank" rel="noopener">
  [text]
</a>

Tuairiscigh méadrachtaí rannpháirtíochta

PUT

/online-advertisement/{PAID}/metrics

Tuairiscigh líon carnach na n-amharc agus na n-idirghníomhaíochtaí ar fhógra foilsithe a sheachaid tú

Teastaíonn an cead metrics:write ó do chomhartha SSP. Cuireann riarthóir an cead ar siúl don chomhartha atá in úsáid agat cheana, mar sin ní eisítear comhartha nua.

Iarratas samplach

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}'

Réimsí an iarratais

viewsCount

integer

Líon na n-amharc ar an bhfógrán ó foilsíodh é

engagementsCount

integer

Líon na n-idirghníomhaíochtaí leis an bhfógrán (cliceanna, moltaí agus tráchtanna) ó foilsíodh é

Tá an dá réimse riachtanach, agus is slánuimhir ó 0 go 2147483647 gach ceann acu.

Freagra samplach

{
  "viewsCount": 15000,
  "engagementsCount": 320,
  "engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}

Freagraí earráide ón gcríochphointe seo

401 INVALID_TOKEN

Tá an ceanntásc Authorization ar iarraidh, nó tá an comhartha anaithnid, cúlghairthe nó ina chomhartha comhpháirtí. Bíonn an cód INVALID_TOKEN sa dá chás.

{
  "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

Tá an comhartha bailí ach níor tugadh an cead metrics:write dó. Iarr ar do riarthóir é a chur ar siúl.

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

404 NOT_FOUND

{
  "error": "Advertisement not found",
  "code": "NOT_FOUND"
}

409 METRICS_NOT_APPLICABLE

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

400 INVALID_METRICS

Níl corp an iarratais ina JSON bailí, nó tá an dá chomhaireamh ar iarraidh nó diúltach, nó ní slánuimhreacha iad. Liostaíonn an freagra cad a theip.

{
  "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

Sáraíodh an teorainn in aghaidh an chomhartha. Bíonn na ceanntásca X-RateLimit-Limit, X-RateLimit-Remaining agus X-RateLimit-Reset san fhreagra seo.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Fíordheimhniú

Formáid an cheanntáisc

Authorization: Bearer YOUR_SSP_TOKEN

Formáid an chomhartha

Teaghrán heicsidheachúlach 64 carachtar (eantrópacht 256 giotán)

Bainistiú comharthaí

Is iad riarthóirí córais amháin a bhainistíonn comharthaí SSP. Déan teagmháil le do riarthóir chun comhartha a fháil.

Riachtanais rochtana

Níl feidhm ag aon phlean síntiúis

Nuair a thugann an críochphointe 404 ar ais

Suaitheantas trédhearcachta

An nochtadh céanna, curtha i láthair d’fhógrán atá á sheachadadh

URL amháin do gach leagan

Freagraíonn gach rialtán sa taispeántas do pharaiméadar amháin díobh seo, mar sin is féidir leat do rogha a dhéanamh ar leathanach an taispeántais agus an URL a fheiceann tú a chóipeáil.

# Suaitheantas cúinne, an marc amháin
GET https://polads.eu/badge/{PA-ID}

# Suaitheantas cúinne a thaispeánann a théacs
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stiall lipéid a bhíonn le feiceáil i gcónaí
GET https://polads.eu/badge/{PA-ID}?layout=label

Cad a dhéanann gach paraiméadar, agus cad is brí lena fhágáil ar lár

Is don taispeántas é hover=0, ní do do leathanach

Tá gá leis an éisteoir athraithe méide

Ar fáil d’fhógra foilsithe amháin

Oscail an taispeántas idirghníomhach agus cóipeáil an cód leabaithe

Freagraí earráide

401 Gan údar

{
  "error": "Invalid or revoked SSP API token."
}

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}

400 Iarratas neamhbhailí

Fuarthas an fógra, ach níl a mheán online. Cuireann an freagra fíorluach an mheáin ar ais, mar shampla print. Cuireann PA-ID atá ar iarraidh nó anaithnid 404 ar ais ina ionad.

{
  "error": "This endpoint is only for online advertisements",
  "medium": "print"
}

404 Gan aimsiú

{
  "error": "Advertisement not found"
}

429 Sáraíodh an teorainn ráta

{
  "error": "Rate limit exceeded",
  "limit": 10000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Leaganú agus díchoimisiúnú

Sonraíocht inléite ag meaisín

Tá an doiciméad iomlán OpenAPI 3.1 ar fáil ag /api/docs. Dírigh Postman, Swagger UI nó gineadóir cliaint air go díreach seachas an leathanach seo a thras-scríobh.

https://polads.eu/api/docs

An bhfuil tú ag comhtháthú mar chomhpháirtí meán nó foilsitheora? Léigh doiciméadú API na gcomhpháirtithe