Documentação da API SSP
API de plataforma do lado da oferta para plataformas de publicidade programática
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 pedidos por minuto
Limite de pedidos aplicado por token SSP
PUT /online-advertisement/{PAID}/metrics
1.000 pedidos por minuto
Contabilizados por token SSP, separadamente do ponto final de rótulos, pelo que a comunicação de métricas nunca consome os seus pedidos de rótulos
/online-advertisement/{PAID}📊 Formato de rótulo compacto
Este ponto final devolve um rótulo de transparência compacto, conforme com a legislação da UE, adequado para apresentação junto de anúncios em linha. Só funciona para anúncios com medium = "online".
Exemplo de pedido
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Exemplo de resposta
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Campos da resposta
Exemplo de utilização
Apresente o rótulo na sua plataforma:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsO seu token SSP necessita da permissão metrics:write. Um administrador ativa-a no token que já utiliza, pelo que não é emitido nenhum token novo.
Envie os totais acumulados desde a publicação do aviso, nunca a variação desde o seu último envio. Cada envio substitui os valores anteriores, pelo que voltar a enviar os mesmos totais não altera nada.
Pode comunicar os valores de qualquer aviso publicado, seja qual for o editor a que pertença. Os valores aparecem no respetivo aviso de transparência público, com a data da última comunicação.
Exemplo de pedido
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}'Campos do pedido
Ambos os campos são obrigatórios e cada um deve ser um número inteiro de 0 a 2147483647.
Exemplo de resposta
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Respostas de erro deste ponto final
401 INVALID_TOKEN
O cabeçalho Authorization está em falta, ou o token é desconhecido, foi revogado ou é um token de parceiro. Em ambos os casos, a resposta inclui o código 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
O token é válido, mas não lhe foi atribuída a permissão metrics:write. Peça ao seu administrador que a ative.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Nenhum aviso publicado corresponde a esse PA-ID. Tal como no ponto final de rótulos, um aviso que o seu editor ainda não tenha aprovado, ou cuja data de início de publicação ainda esteja no futuro, também devolve 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}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.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}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.
{
"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
O limite por token foi excedido. A resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Formato do cabeçalho
Authorization: Bearer YOUR_SSP_TOKENFormato do token
Sequência hexadecimal de 64 caracteres (entropia de 256 bits)
Gestão de tokens
Os tokens SSP são geridos apenas pelos administradores de sistema. Contacte o seu administrador para obter um token.
Não se aplica nenhum plano de subscrição
Um token SSP é emitido a um integrador e não a um editor, pelo que não está associado a nenhuma conta de editor e não há plano a verificar. Ao contrário da API de parceiros, nada aqui depende de uma subscrição. Um token de parceiro é rejeitado neste ponto final com 401, e um token SSP é rejeitado da mesma forma nos pontos finais de parceiros.
Quando o ponto final devolve 404
O aviso é obtido segundo a mesma regra de visibilidade aplicada no registo público. Um aviso que ainda não esteja confirmado, que o seu editor ainda não tenha aprovado ou cuja data de início de publicação ainda esteja no futuro devolve 404. Assim, um 404 não prova que um PA-ID esteja errado.
O ponto final acima devolve o TEXTO do rótulo numa só linha, para um rótulo desenhado pela sua própria plataforma. O distintivo devolve um aviso interativo já composto, que coloca junto ao anúncio como iframe. Ambos descrevem o mesmo aviso de transparência.
Um URL por versão
Os controlos da demonstração correspondem um a um a estes parâmetros, pelo que pode escolher na página de demonstração e copiar o URL que vê.
# Distintivo de canto, apenas a marca
GET https://polads.eu/badge/{PA-ID}
# Distintivo de canto com o respetivo texto
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Faixa do rótulo sempre visível
GET https://polads.eu/badge/{PA-ID}?layout=labelO que faz cada parâmetro e o que significa omiti-lo
layout=label seleciona a faixa. Se o omitir, obtém o distintivo de canto. variant=labelled faz com que o distintivo fechado mostre o seu texto. Se o omitir, obtém apenas a marca. w e h declaram o espaço onde o distintivo se insere e determinam como se adapta quando há pouco espaço. Se os omitir, o distintivo assume que tem espaço suficiente, o que é adequado para os formatos padrão.
hover=0 é para a demonstração, não para a sua página
Força a apresentação para dispositivos sem ponteiro, para que a demonstração possa mostrar a versão tátil num navegador de computador. O distintivo real verifica o dispositivo por si próprio. Se fixar este valor no código, envia a versão errada a todos os visitantes cujo dispositivo não corresponda.
O recetor de eventos de redimensionamento é obrigatório
O distintivo de canto carrega com 32 por 32 para cobrir o mínimo possível do anúncio e, ao abrir, pede espaço à página anfitriã. Sem o recetor, não consegue sequer abrir. A faixa do rótulo adapta-se de forma mais suave e só é cortada em larguras reduzidas.
Disponível apenas para um aviso publicado
O distintivo é disponibilizado quando o aviso está confirmado, aprovado pelo editor e já ultrapassou a sua data de início de publicação. Um PA-ID sob embargo ou não aprovado devolve 404 propositadamente, e não por erro.
Abrir a demonstração interativa e copiar o código de incorporação
401 Não autorizado
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Pedido inválido
O anúncio foi encontrado, mas o seu meio não é online. A resposta devolve o valor real do meio, por exemplo print. Um PA-ID em falta ou desconhecido devolve 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Não encontrado
{
"error": "Advertisement not found"
}429 Limite de pedidos excedido
{
"error": "Rate limit exceeded",
"limit": 10000,
"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. Um ponto final v1 não 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 é disponibilizado em /api/docs. Aponte o Postman, o Swagger UI ou um gerador de clientes diretamente para ele, em vez de transcrever esta página.
https://polads.eu/api/docs