Doiciméadú API do Chomhpháirtithe

API sonraí fógrán polaitiúil do chomhpháirtithe sna meáin agus d'fhoilsitheoirí

API v1

Comhartha iompróra comhpháirtí ag teastáil

I gcomhréir le GDPR

Bun-URL

https://polads.eu/api/v1

Tá fíordheimhniú le comhartha iompróra comhpháirtí ag teastáil do gach críochphointe

Teorannú ráta

Tá an teorainn ráta chéanna ag gach críochphointe comhpháirtí in aghaidh an chomhartha iompróra

GET /advertisement-full/{PAID}

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

GET /advertisement/{PAID}

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

Cuirtear an teorainn ráta i bhfeidhm in aghaidh an chomhartha comhpháirtí ar fud na gcríochphointí go léir

Riachtanais rochtana

An méid nach mór a bheith ag comhartha comhpháirtí sula bhfreagróidh aon chríochphointe

Plean Pro, seiceáilte arís ar gach iarratas

Is cuid den phlean Pro é API na gcomhpháirtithe, le haghaidh léamh agus scríobh araon. Níl aon bhreiseán API ar leith le ceannach. Léitear an plean ar gach aon iarratas seachas é a thaifeadadh nuair a chruthaítear an comhartha, mar sin má théann síntiús in éag stoptar an rochtain ar an gcéad ghlao eile le 403 PRO_PLAN_REQUIRED, agus nuair a athnuaitear é tugtar an rochtain ar ais díreach chomh tapa céanna.

Scóipeanna

Is féidir le gach comhartha comhpháirtí léamh. Chun méadrachtaí rannpháirtíochta a thuairisciú, teastaíonn an scóip metrics:write freisin. Roghnaítear na scóipeanna nuair a ghintear an comhartha agus ní féidir iad a athrú ina dhiaidh sin: chun iad a athrú, cúlghair an comhartha agus gin ceann nua.

Comharthaí comhpháirtí amháin

Diúltaíonn na críochphointí seo do chomhartha SSP le 401, agus diúltaíonn an críochphointe SSP do chomhartha comhpháirtí ar an gcaoi chéanna. Is dintiúir ar leith iad an dá shraith, ní dhá leibhéal ceadanna ar an dintiúr céanna.

Nuair a thugann críochphointe 404 ar ais

Ní cruthúnas é 404 go bhfuil PA-ID mícheart

Aimsíonn GET /advertisement/{PAID} an fógra de réir na rialach infheictheachta céanna a bhaineann leis an gclár poiblí. Fógra nach bhfuil deimhnithe fós, nach bhfuil ceadaithe ag a fhoilsitheoir fós, nó a bhfuil dáta tosaithe an fhoilsithe fós amach anseo, tugann sé 404 ar ais anseo díreach mar a dhéanann sé ar an gclár. Baineann an rud céanna leis an gcríochphointe SSP.

Tá críochphointe an taifid iomláin difriúil d'aon ghnó

Tá GET /advertisement-full/{PAID} teoranta do na fógraí atá agat féin, mar sin tugann sé freagra fiú i gcás fógra nach bhfuil a dháta tosaithe bainte amach fós. Is tusa an foilsitheoir a chaithfidh an fógra sin a scrúdú sula dtosóidh sé, mar sin ní bheadh aon chiall le é a choinneáil siar uait.

GET

/advertisement-full/{PAID}

Faigh sonraí iomlána fógraí, lena n-áirítear GACH réimse atá íogair faoin GDPR (tá comhartha Bearer ag teastáil)

Teoranta do na fógraí atá agat féin. Tugann PA-ID foilsitheora eile, fógra féinfhoilsithe nach bhfuil foilsitheoir aige, agus aitheantóir nach ann dó an 404 céanna ar ais, agus ní dhéanann an freagra aon idirdhealú eatarthu.

⚠️ Rabhadh: sonraí atá íogair faoin GDPR

Cuireann an críochphointe seo GACH réimse ar ais, lena n-áirítear ríomhphoist, uimhreacha gutháin agus seoltaí iomlána. Ná húsáid an críochphointe seo ach amháin má tá riachtanas gnó dlisteanach agat agus má tá comhaontuithe cuí próiseála sonraí i bhfeidhm agat.

Comhartha Bearer

PA-ID

Iarratas Samplach

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

Ábhar an Fhreagra (GAN SCAGADH)

Réimsí an Fhógróra:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Réimsí an Fheachtais:

name, totalValue, medium, isOngoing, startDate, endDate

Fógróirí agus Rialaitheoirí:

Gach réimse, lena n-áirítear ríomhphoist, uimhreacha gutháin agus seoltaí iomlána

Tuairiscigh méadrachtaí rannpháirtíochta

PUT

/advertisement/{PAID}/metrics

Seol líon na n-amharc agus líon na rannpháirtíochta tar éis an fhoilsithe maidir le d'fhógraí féin.

Teastaíonn eochair leis an leibhéal rochtana Léamh agus scríobh don chríochphointe seo. Tá API na gcomhpháirtithe san áireamh sa phlean Pro.

Ní féidir leat méadrachtaí a thuairisciú ach amháin d'fhógraí a foilsíodh trí do chuntas féin.

Baineann an fógra le foilsitheoir eile. Ní scríobhtar aon rud.

Iarratas Samplach

curl -X PUT "https://polads.eu/api/v1/advertisement/ABC12/metrics" \
  -H "Authorization: Bearer YOUR_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewsCount": 15000, "engagementsCount": 320}'

Réimsí atá ar fáil

Réimsí sonraí a thugann an API ar ais, mar aon lena gcineálacha

Buneolas

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Comhlíonadh agus maoiniú

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Spriocdhíriú

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Dlí agus meiteashonraí

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

léiríonn sé réimse roghnach a d'fhéadfadh a bheith gan luach nó folamh

Samplaí cóid

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Freagraí earráide

Cuireann gach earráid corp JSON ar ais le teachtaireacht earráide, agus iompraíonn gach freagra ceanntásc X-API-Version. Gabhann cód inléite ag meaisín leis na diúltuithe mar gheall ar chomhartha neamhbhailí agus ar an bplean, agus le hearráidí bailíochtaithe an chríochphointe metrics féin. Is é an teachtaireacht amháin a thagann ar ais nuair a bhíonn ceanntásc Authorization ar iarraidh, le hearráid 404 nó 429 ó chríochphointe léimh agus le haon earráid inmheánach freastalaí.

401 INVALID_TOKEN

Níl aon chomhartha gníomhach ag teacht leis an dintiúr Bearer, nó tá an comhartha cúlghairthe. Freagraítear le 401 freisin nuair a bhíonn ceanntásc Authorization ar iarraidh nó míchumtha, ach is é an críochphointe metrics amháin a chuireann an cód seo leis. Faigheann comhartha SSP ar chríochphointe comhpháirtí an freagra céanna.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid or revoked partner API token.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

403 PRO_PLAN_REQUIRED

Tá an comhartha bailí ach níl a fhoilsitheoir ar an bplean Pro. Seiceáiltear é seo roimh an scóip, mar sin tuairiscíonn comhartha léite amháin a bhaineann le foilsitheoir nach bhfuil ar an bplean Pro an plean seachas an scóip.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics

{
  "error": "The Pro plan is required to use the partner API.",
  "code": "PRO_PLAN_REQUIRED"
}

403 INSUFFICIENT_SCOPE

Tá an comhartha bailí agus ar an bplean Pro, ach níl an scóip metrics:write aige, atá riachtanach chun méadrachtaí a thuairisciú.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Baineann an fógra le foilsitheoir eile. Ní scríobhtar aon rud.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

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.

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid engagement metrics",
  "code": "INVALID_METRICS",
  "issues": [
    {
      "path": "viewsCount",
      "message": "Too small: expected number to be >=0"
    }
  ]
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid request body",
  "code": "INVALID_METRICS"
}

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.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Níl aon fhógra a mheaitseálann an PA-ID sin, nó níl sé infheicthe duit fós. Léigh an chuid thuas sula nglacann tú leis go bhfuil an t-aitheantóir mícheart.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}

{
  "error": "Advertisement not found"
}

GET /advertisement-full/{PAID}

{
  "error": "Advertisement not found or not yet confirmed"
}

429 RATE_LIMITED

Sáraíodh an teorainn in aghaidh an chomhartha. Iompraíonn an freagra X-RateLimit-Limit, X-RateLimit-Remaining agus X-RateLimit-Reset.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Rate limit exceeded",
  "limit": 1000,
  "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 ar chosán nua seachas an cosán 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

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

https://polads.eu/api/docs

An bhfuil tú ag comhtháthú mar ardán ar thaobh an tsoláthair? Léigh doiciméadú an API SSP

Doiciméadú API do Chomhpháirtithe

API sonraí fógrán polaitiúil do chomhpháirtithe sna meáin agus d'fhoilsitheoirí

API v1

Comhartha iompróra comhpháirtí ag teastáil

I gcomhréir le GDPR

Bun-URL

https://polads.eu/api/v1

Tá fíordheimhniú le comhartha iompróra comhpháirtí ag teastáil do gach críochphointe

Teorannú ráta

Tá an teorainn ráta chéanna ag gach críochphointe comhpháirtí in aghaidh an chomhartha iompróra

GET /advertisement-full/{PAID}

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

GET /advertisement/{PAID}

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

Cuirtear an teorainn ráta i bhfeidhm in aghaidh an chomhartha comhpháirtí ar fud na gcríochphointí go léir

Riachtanais rochtana

An méid nach mór a bheith ag comhartha comhpháirtí sula bhfreagróidh aon chríochphointe

Plean Pro, seiceáilte arís ar gach iarratas

Scóipeanna

Comharthaí comhpháirtí amháin

Nuair a thugann críochphointe 404 ar ais

Ní cruthúnas é 404 go bhfuil PA-ID mícheart

Tá críochphointe an taifid iomláin difriúil d'aon ghnó

GET

/advertisement-full/{PAID}

Faigh sonraí iomlána fógraí, lena n-áirítear GACH réimse atá íogair faoin GDPR (tá comhartha Bearer ag teastáil)

⚠️ Rabhadh: sonraí atá íogair faoin GDPR

Comhartha Bearer

PA-ID

Iarratas Samplach

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

Ábhar an Fhreagra (GAN SCAGADH)

Réimsí an Fhógróra:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Réimsí an Fheachtais:

name, totalValue, medium, isOngoing, startDate, endDate

Fógróirí agus Rialaitheoirí:

Gach réimse, lena n-áirítear ríomhphoist, uimhreacha gutháin agus seoltaí iomlána

Tuairiscigh méadrachtaí rannpháirtíochta

PUT

/advertisement/{PAID}/metrics

Seol líon na n-amharc agus líon na rannpháirtíochta tar éis an fhoilsithe maidir le d'fhógraí féin.

Teastaíonn eochair leis an leibhéal rochtana Léamh agus scríobh don chríochphointe seo. Tá API na gcomhpháirtithe san áireamh sa phlean Pro.

Ní féidir leat méadrachtaí a thuairisciú ach amháin d'fhógraí a foilsíodh trí do chuntas féin.

Baineann an fógra le foilsitheoir eile. Ní scríobhtar aon rud.

Iarratas Samplach

curl -X PUT "https://polads.eu/api/v1/advertisement/ABC12/metrics" \
  -H "Authorization: Bearer YOUR_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewsCount": 15000, "engagementsCount": 320}'

Réimsí atá ar fáil

Réimsí sonraí a thugann an API ar ais, mar aon lena gcineálacha

Buneolas

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Comhlíonadh agus maoiniú

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Spriocdhíriú

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Dlí agus meiteashonraí

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

léiríonn sé réimse roghnach a d'fhéadfadh a bheith gan luach nó folamh

Samplaí cóid

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Freagraí earráide

401 INVALID_TOKEN

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid or revoked partner API token.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

403 PRO_PLAN_REQUIRED

GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics

{
  "error": "The Pro plan is required to use the partner API.",
  "code": "PRO_PLAN_REQUIRED"
}

403 INSUFFICIENT_SCOPE

Tá an comhartha bailí agus ar an bplean Pro, ach níl an scóip metrics:write aige, atá riachtanach chun méadrachtaí a thuairisciú.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Baineann an fógra le foilsitheoir eile. Ní scríobhtar aon rud.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

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.

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid engagement metrics",
  "code": "INVALID_METRICS",
  "issues": [
    {
      "path": "viewsCount",
      "message": "Too small: expected number to be >=0"
    }
  ]
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid request body",
  "code": "INVALID_METRICS"
}

409 METRICS_NOT_APPLICABLE

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Níl aon fhógra a mheaitseálann an PA-ID sin, nó níl sé infheicthe duit fós. Léigh an chuid thuas sula nglacann tú leis go bhfuil an t-aitheantóir mícheart.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}

{
  "error": "Advertisement not found"
}

GET /advertisement-full/{PAID}

{
  "error": "Advertisement not found or not yet confirmed"
}

429 RATE_LIMITED

Sáraíodh an teorainn in aghaidh an chomhartha. Iompraíonn an freagra X-RateLimit-Limit, X-RateLimit-Remaining agus X-RateLimit-Reset.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

Leaganú agus díchoimisiúnú

Sonraíocht inléite ag meaisín

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

https://polads.eu/api/docs

An bhfuil tú ag comhtháthú mar ardán ar thaobh an tsoláthair? Léigh doiciméadú an API SSP