Documentação da API para parceiros
API de dados sobre anúncios de cariz político para parceiros de comunicação social e editores
https://polads.eu/api/v1Todos os pontos de extremidade exigem autenticação com token Bearer de parceiro
GET /advertisement-full/{PAID}
1,000 pedidos por minuto
GET /advertisement/{PAID}
1,000 pedidos por minuto
O limite de pedidos é aplicado por token de parceiro em todos os pontos de extremidade
Plano Pro, verificado em cada pedido
A API de parceiros faz parte do plano Pro, tanto para leituras como para escritas. Não existe nenhum suplemento de API a adquirir à parte. O plano é verificado em cada pedido, e não registado no momento em que o token é criado, pelo que uma subscrição caducada bloqueia o acesso logo na chamada seguinte com 403 PRO_PLAN_REQUIRED, e a renovação repõe-no de forma igualmente imediata.
Âmbitos
Qualquer token de parceiro permite leitura. A comunicação de métricas de interação exige também o âmbito metrics:write. Os âmbitos são escolhidos quando o token é emitido e não podem ser alterados posteriormente: para os alterar, revogue o token e emita um novo.
Apenas tokens de parceiro
Estes pontos de extremidade rejeitam um token SSP com 401, e o ponto de extremidade SSP rejeita um token de parceiro da mesma forma. Os dois tipos de acesso são credenciais distintas, não dois níveis de permissão de uma mesma credencial.
GET /advertisement/{PAID} obtém o aviso através da mesma regra de visibilidade do registo público. Um aviso que ainda não tenha sido confirmado, que o editor ainda não tenha aprovado ou cuja data de início de publicação ainda seja futura devolve 404 aqui, exatamente como no registo. O mesmo se aplica ao ponto de extremidade SSP.
O endpoint do registo completo é deliberadamente diferente
GET /advertisement-full/{PAID} está limitado aos seus próprios anúncios, pelo que responde também a um anúncio que ainda não atingiu a data de início. Enquanto editor, é a si que cabe examinar esse anúncio antes de ser publicado, pelo que ocultá-lo contrariaria a sua finalidade.
/advertisement-full/{PAID}Limitado aos seus próprios anúncios. O PA-ID de outro editor, um anúncio autopublicado sem editor e um identificador inexistente devolvem todos o mesmo 404, e a resposta não os distingue.
⚠️ Aviso: dados sensíveis nos termos do RGPD
Este endpoint devolve TODOS os campos, incluindo endereços de e-mail, números de telefone e moradas completas. Utilize este endpoint apenas se tiver uma necessidade comercial legítima e acordos de tratamento de dados adequados em vigor.
curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Campos do anunciante:
companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country
Campos da campanha:
name, totalValue, medium, isOngoing, startDate, endDate
Anunciantes e entidades controladoras:
Todos os campos, incluindo e-mails, telefones e moradas completas
/advertisement/{PAID}/metricsEste ponto final requer uma chave com o âmbito Leitura e escrita. A API de parceiros está incluída no plano Pro.
Só pode comunicar métricas de anúncios publicados através da sua própria conta.
O anúncio pertence a outro editor. Nada é escrito.
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}'Informações básicas
Conformidade e financiamento
Direcionamento
Informação jurídica e metadados
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
Nenhum token ativo corresponde à credencial Bearer, ou o token foi revogado. Um cabeçalho Authorization em falta ou mal formado também devolve 401, mas apenas o ponto final de métricas o identifica com este código. Um token SSP num ponto final de parceiro recebe a mesma resposta.
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
O token é válido, mas o respetivo editor não tem o plano Pro. Isto é verificado antes do âmbito, pelo que um token só de leitura pertencente a um editor sem o plano Pro indica o plano e não o âmbito.
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
O token é válido e tem o plano Pro, mas não tem o âmbito metrics:write necessário para comunicar métricas.
PUT /advertisement/{PAID}/metrics{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}403 FORBIDDEN
O anúncio pertence a outro editor. Nada é escrito.
PUT /advertisement/{PAID}/metrics{
"error": "This advertisement belongs to a different publisher.",
"code": "FORBIDDEN"
}400 INVALID_METRICS
O corpo do pedido não é JSON válido, ou as duas contagens estão em falta, são negativas ou não são números inteiros. A resposta indica o que falhou.
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
O aviso está fora do âmbito para o qual as métricas de interação estão definidas. A nota 15 do anexo II abrange um aviso em linha ou nativo que tenha utilizado técnicas de direcionamento ou técnicas de distribuição de anúncios e que já tenha começado a ser difundido. Nada é gravado.
PUT /advertisement/{PAID}/metrics{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}404 NOT_FOUND
Nenhum aviso corresponde a esse PA-ID, ou ainda não está visível para si. Consulte a secção acima antes de concluir que o identificador está errado.
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
O limite por token foi excedido. A resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e 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"
}Esta é a versão v1 da API, e todas as respostas o indicam num cabeçalho X-API-Version. As alterações incompatíveis são publicadas num novo caminho, em vez de alterarem este. Nenhum ponto final v1 será desativado sem um cabeçalho Deprecation enviado com pelo menos 90 dias de antecedência, em conformidade com o RFC 8594.
Especificação legível por máquina
O documento OpenAPI 3.1 completo está disponível em /api/docs. Aponte o Postman, o Swagger UI ou um gerador de clientes diretamente para esse endereço, em vez de transcrever esta página.
https://polads.eu/api/docs