Perguntas sobre a API

Registe-se e confirme o seu email. A primeira página depois de iniciar sessão, «Ligar pela API», cria a sua chave clk_live_….

A chave é mostrada uma única vez, logo após ser criada, por isso copie-a nesse momento: guardamos apenas o seu hash. Uma conta pode ter até 10 chaves ativas. Uma chave de que já não precisa é revogada na mesma página e deixa de funcionar de imediato.

A API está em https://api.consent.link/v3 e fala JSON. Envie a chave em cada pedido no cabeçalho Authorization: Bearer clk_live_… (o cabeçalho X-AUTH-TOKEN da nossa antiga API v2 também funciona). Um pedido sem uma chave válida recebe 401 unauthenticated.

Chame a API apenas a partir do seu servidor. Quem tiver a chave pode criar links e ler o seu histórico com todos os dados dos visitantes.

Todos de relance. Cada caminho vem depois de https://api.consent.link; as chaves públicas para verificar os tokens de decisão estão em https://api.consent.link/.well-known/jwks.json.

Envie POST /v3/links com o destino. A resposta é 201 com o link: short é o endereço a colocar nos seus anúncios, publicações e emails, id é o seu código. Só destination é obrigatório.

Os links são criados apenas pela API, nunca na área de cliente: cada destino é verificado quando o link é criado, o que mantém o phishing de fora.

• destination: para onde vai o visitante depois de decidir. Obrigatório.
• type: a indicação na página de consentimento, uma de ad, sponsored, affiliate, none. Sem ele, a indicação escolhida em «Aparência».
• template: o texto da página, o id de um modelo da nossa biblioteca (a tabela abaixo). Sem ele, o modelo escolhido em «Aparência».
• name: um nome seu para o link, até 255 caracteres, mostrado na área de cliente.
• external_id: um id seu, por exemplo de uma publicação ou de uma campanha, até 255 caracteres. Pode filtrar os links por ele; não pode ser alterado depois.
• metadata: um objeto JSON seu, guardado e devolvido tal como está.

A resposta traz também resolved_destination (para um tracker ou um link curto, ver abaixo), status (active, disabled ou blocked), mode (live ou test) e created_at; warnings, só quando há algo a avisar.

Um endereço absoluto http ou https num nome de domínio público, até 2048 caracteres: sem endereços IP, sem nome de utilizador nem palavra-passe, sem espaços nem barras invertidas. Guardamo-lo byte a byte.

Cada endereço novo é verificado na nossa lista de bloqueio e no Google Web Risk, e um endereço perigoso é recusado com 422 destination_blocked. Se mais tarde um endereço se revelar perigoso, o link é bloqueado: deixa de abrir, já não pode ser alterado e o seu webhook recebe link.blocked.

Quando o host do destino é o endereço de clique de uma rede de afiliados ou de um encurtador de links, como awin1.com, sjv.io, prf.hn, admitad.com, amzn.to, bit.ly (subdomínios incluídos), seguimos nós mesmos os seus redirecionamentos: quando o link é criado, também em lote, e quando PATCH altera o seu destination. São até 5 redirecionamentos em poucos segundos. O endereço onde a cadeia sai dos trackers para outro site é guardado, byte a byte, como resolved_destination. Nunca consultamos outros destinos, e o resolved_destination deles fica null.

destination fica exatamente como o enviou. Com consentimento, o visitante vai para lá, através do tracker. Sem consentimento, vai diretamente para resolved_destination, sem passar pelo tracker e sem os identificadores de cliques em anúncios.

Se não for possível seguir a cadeia (o tracker não redireciona, demora demasiado, redireciona vezes demais, leva a um endereço interno ou bloqueado, ou nunca sai dos trackers), o link é criado na mesma, mas por agora uma recusa passa pelo tracker. Cada resposta que mostra o link traz então warnings com o código tracker_unresolved, e a página do link na área de cliente também o indica. Tentamos de novo em segundo plano, esperando 5 minutos, 1 hora entre as tentativas; quando resulta, resolved_destination é preenchido e o aviso desaparece. Depois da última tentativa, verifique o endereço e envie-o de novo com PATCH. Quando não há nada a avisar, a resposta não traz warnings.

Os nossos pedidos aos trackers levam o User-Agent Consent.link-Resolver/1 (+https://consent.link/faq/api).

Envie o cabeçalho Idempotency-Key com POST /v3/links e POST /v3/links/bulk: de 1 a 255 caracteres ASCII imprimíveis, por exemplo um UUID ou um id seu da publicação. Uma repetição com a mesma chave e o mesmo corpo dentro de 24 horas devolve os links já criados, com o cabeçalho Idempotent-Replayed: true, e não cria nada.

A mesma chave com outro corpo é recusada com 422 idempotency_key_reused. Se o primeiro pedido ainda estiver em curso, a repetição recebe 409 idempotency_in_progress: espere um momento e envie-o de novo.

Sim: POST /v3/links/bulk com {"links": [ … ]}, até 500 links por pedido, cada um com os mesmos campos de um link individual. A resposta é 201 com data, os links pela ordem em que os enviou.

É tudo ou nada: se um elemento for inválido, nada é criado e o erro indica-o, por exemplo links.3.destination.

PATCH /v3/links/{id} apenas com os campos a alterar: destination, type, template, name, metadata. null limpa um campo opcional, metadata é substituído por inteiro e external_id fica como foi criado. A página de consentimento mostra a alteração de imediato. Um destino novo é verificado como o de um link novo e, se estiver noutro domínio, os consentimentos anteriores com «Não perguntar novamente» para o domínio antigo deixam de deixar passar os visitantes.

DELETE /v3/links/{id} desativa o link: deixa de abrir e já não pode ser alterado nem reativado, enquanto os seus registos ficam no histórico. Crie um link novo se voltar a precisar dele.

GET /v3/links lista os seus links, os mais recentes primeiro, 50 por página (até 100 com limit). Filtros: status, mode, type, template, external_id, domain, e from e to para a data de criação (2026-10-31 ou 2026-10-31T14:00:00Z). Para a página seguinte, passe next_cursor da resposta como cursor; null significa que não há mais páginas.

GET /v3/links/{id} devolve um link com stats desde a sua criação: shown, granted, denied, left (saiu da página sem decidir), reused e withdrawn. Os números vão alguns minutos atrás do histórico.

A página que configura em «Aparência» na área de cliente: o modelo de texto da nossa biblioteca, os destinatários dos dados, a indicação, o link para a sua política de privacidade e, no Business, o seu logótipo e a sua cor. Os type e template do próprio link têm prioridade sobre a aparência. Quando publica uma versão nova, as páginas dos seus links mudam em menos de um minuto.

O idioma é escolhido a partir do navegador do visitante: inglês, espanhol, alemão, francês, italiano, português ou russo. Escolhe um modelo, não palavras: os textos vêm da nossa biblioteca, por isso não pode escrever os seus.

Enquanto nada for publicado em «Aparência», a página não mostra o link para a sua política de privacidade nem os destinatários dos dados. Os links são criados mesmo assim, e as respostas a POST /v3/links, POST /v3/links/bulk e PATCH /v3/links/{id} trazem o cabeçalho Consent-Link-Warning: design_unpublished enquanto a configuração do link não tiver uma versão publicada.

Guarde vários perfis da página em «Aparência» ou pela API, cada um com o seu próprio id, como black-friday, e indique um ao criar um link: "profile": "black-friday" em POST /v3/links ou num elemento da criação em massa. Sem profile, o link recebe o seu perfil predefinido.

Um link mantém o seu perfil: se mais tarde outro perfil passar a ser o predefinido, os links antigos não mudam. PATCH /v3/links/{id} com profile muda um link de perfil, e "profile": null passa-o para o predefinido desse momento. Um id desconhecido dá 422 no campo profile. O objeto do link mostra o seu profile, e GET /v3/links?profile=black-friday lista os links de um perfil. Quantos perfis pode ter depende do plano: 1 no Free, 5 no Pro, 50 no Business, incluindo o predefinido.

GET /v3/profiles lista-os, o predefinido primeiro. POST /v3/profiles cria um com id e policy_url (obrigatórios) e, se quiser, name, template, vendors, type, remember, brand_name e default. É publicado de imediato. PATCH /v3/profiles/{id} altera-o: os campos da página publicam logo uma versão nova; name e "default": true sozinhos não publicam nada.

DELETE /v3/profiles/{id} elimina um perfil que não seja o predefinido (409 profile_is_default) e não tenha links ativos (409 profile_in_use). Criar um acima do limite do plano, ou usar um que ficou acima do limite depois de baixar de plano, dá 402 profiles_limit_reached. As alterações precisam de uma chave real.

Com consentimento, o visitante vai para o seu destino exatamente como o indicou. Sem consentimento, utm_* e os seus outros parâmetros também ficam, e só são retirados os identificadores de cliques em anúncios: gclid, gbraid, wbraid, fbclid, msclkid, ttclid, twclid, li_fat_id. Em ambos os casos acrescentamos um parâmetro, cl_ct, o token de decisão.

Só contam os parâmetros do próprio destino: o que for acrescentado ao link curto (https://consent.link/nk7Qa?utm_source=…) não é passado. Coloque em destination tudo o que o seu site precisa, ou crie um link por campanha.

Cada redirecionamento a partir da página de consentimento leva cl_ct, um token assinado (JWT, ES256) que vale 10 minutos. Verifique-o a partir do seu servidor com POST /v3/consents/verify: a resposta traz a decisão, e cada token só pode ser verificado uma vez, por isso um endereço copiado não serve de nada. Leia o token e depois retire-o do endereço.

O que contém: decision (granted ou denied), purposes (o que o visitante permitiu), cid (o registo no histórico), sid (o pseudónimo do visitante na sua conta, o mesmo em todos os seus links), cexp (até quando vale o consentimento, em tempo Unix), link, mode, iat e exp. Nada de IP, navegador ou outros dados pessoais. Um visitante que já aceitou e deixou marcado «Não perguntar novamente» passa diretamente, com granted.

Também pode verificar a assinatura por si, com as chaves em https://api.consent.link/.well-known/jwks.json e qualquer biblioteca JWT: verifique exp e que link é um dos seus links. A sua própria verificação não sabe se um token já foi usado; o método da API sabe. Erros: 422 token_invalid, 422 token_expired, 409 token_used.

Crie um webhook: POST /v3/webhooks com url e os events que quiser (a tabela abaixo). O endereço tem de ser https num nome de host público. A resposta traz secret (whsec_…) para verificar as assinaturas: é mostrado uma única vez, por isso guarde-o. Uma conta pode ter até 10 webhooks ativos.

O registo de entregas, o botão «Tentar novamente» e a ativação ou desativação de um webhook estão na área de cliente, em «Conta» → «Webhooks».

Cada evento é um POST com um corpo JSON: id (evt_…), type, created_at, mode e data. Um registo de consentimento em data.consent tem id, link, decision, purposes, scope (domain se o visitante deixou marcado «Não perguntar novamente», caso contrário link), sid, dest_domain, country, notice_version, created_at e expires_at. Nunca um IP, um navegador ou um cookie.

Cada pedido leva os cabeçalhos Consent-Event, Consent-Delivery e Consent-Signature: t=1793712000,v1=5f3a…. v1 é o HMAC-SHA256 em hexadecimal do texto t, um ponto e o corpo bruto do pedido, com o segredo do seu webhook como chave.

Calcule-o sobre o corpo tal como chegou (antes de interpretar o JSON), compare em tempo constante e recuse um t que se afaste mais de cinco minutos do seu relógio, para que um pedido gravado não possa ser repetido.

Uma entrega conta quando o seu servidor responde 2xx em 10 segundos; os redirecionamentos não são seguidos. Caso contrário, tentamos de novo, esperando 1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas entre as tentativas, 6 tentativas ao todo. Depois da última, a entrega é marcada como falhada e fica no registo, onde «Tentar novamente» a envia de novo até 3 dias depois do evento.

Por isso responda depressa e faça o trabalho depois. O mesmo evento pode chegar mais de uma vez, por exemplo depois de um tempo de espera esgotado: ignore os id que já processou. Os eventos nem sempre chegam pela ordem em que aconteceram.

Os visitantes veem e retiram os seus consentimentos em «Meus consentimentos». Se um visitante lhe pedir a si, retire-o em nome dele: POST /v3/consents/{id}/withdraw, sem corpo, com o id do registo granted ou reused dele. Funciona para qualquer consentimento ainda em vigor, seja qual for a profundidade do histórico que o seu plano mostra. A resposta é 201 com o novo registo withdrawn, cujo first_consent_id é o consentimento retirado. Um registo que não é um consentimento em vigor (recusado, já retirado ou expirado) recebe 409 consent_not_in_force; um que não pode ler recebe 404, como em GET /v3/consents/{id}.

Os dois caminhos dão o mesmo resultado: um registo withdrawn no histórico, consent.withdrawn para o seu webhook com data.withdraws, o id do consentimento retirado, e a partir daí os seus links voltam a perguntar a esse visitante. Uma retirada fecha todos os consentimentos que o visitante deu antes para esse domínio, e não conta para o seu limite.

Deixe de usar os dados do visitante do seu lado: encontre-os por sid ou pelo id do registo.

Um consentimento vale 6 meses a partir do momento em que foi dado: expires_at no registo, cexp no token de decisão. Um registo reused traz o expires_at do consentimento que reutiliza. Depois disso, os seus links voltam a perguntar ao visitante.

Quando um consentimento granted expira sem ter sido retirado, o seu webhook recebe consent.expired com data.consent, o registo, e data.expired_at. Verificamos uma vez por hora, por isso chega na hora seguinte a expires_at, uma vez por consentimento. Os registos reused não têm evento próprio: cobre-os o do consentimento que reutilizam. O evento vai só para webhooks com consent.expired em events. Cada expiração é anunciada uma só vez, mesmo que nenhum webhook a esperasse nessa altura: não volta a ser enviada mais tarde.

Coloque o nosso script no <head>, antes do GTM e do gtag: https://consent.link/js/consent.js. Define os valores predefinidos do Consent Mode v2 (tudo recusado exceto functionality_storage e security_storage, com wait_for_update de 500 ms), lê cl_ct do endereço, verifica a assinatura com as chaves de https://api.consent.link/.well-known/jwks.json no próprio navegador e atualiza o consentimento.

A decisão fica guardada no cookie cl_consent do seu domínio: até cexp para um consentimento e 180 dias para uma recusa, por isso as páginas seguintes não precisam de banner. Depois da verificação, cl_ct sai da barra de endereço; os outros parâmetros ficam. O script não nos envia nada.

Se regista a decisão do seu lado, verifique também o token a partir do seu servidor com POST /v3/consents/verify: o script não sabe se o token já foi usado.

Descarregue o modelo consent-link.tpl; no GTM abra Modelos → Novo → ⋮ → Importar e guarde. Crie uma etiqueta a partir dele com o acionador «Consent Initialization – All Pages» («Inicialização do consentimento – Todas as páginas»).

A etiqueta define os valores predefinidos, aplica a decisão guardada no cookie cl_consent e carrega o script, que verifica um cl_ct novo. Assim não precisa de pôr também o script no <head>.

As purposes do token concedem estes sinais. O que não é concedido fica recusado; uma recusa (denied) recusa tudo exceto os dois sempre concedidos.

Não mostre um segundo banner a quem já decidiu na nossa página. O script dá a decisão em window.consentLink.decision (granted, denied ou null) e window.consentLink.has('stats'); window.consentLink.ready resolve-se quando o token do endereço foi verificado. Há também o evento consentlink:update em document e consent_link_update no dataLayer. Carregue o nosso script antes do script do banner.

Cookiebot: passe a decisão com Cookiebot.submitCustomConsent e o banner dele não aparece. O OneTrust não tem uma função pública para registar o consentimento a partir do site, por isso carregue o script dele só quando não houver decisão. Com outros banners, o mesmo: passe as finalidades pela API deles ou não carregue o banner.

GET /v3/consents lista os registos, os mais recentes primeiro, com os filtros decision (granted, denied, reused, withdrawn), link, country (DE), from, to e a mesma paginação dos links. GET /v3/consents/{id} devolve um registo com as suas provas (endereço IP, navegador, idioma, o hash do texto da página, quando a página foi mostrada e quanto tempo o visitante demorou) e o seu lugar na cadeia de hashes, chain.

Uma recusa guarda apenas a decisão, a hora, o link e o país, por isso o seu evidence é null. A API dá os dados completos; a área de cliente esconde uma parte até ativar o início de sessão em dois passos. Até onde pode ver para trás depende do plano (a tabela em «Planos e limites»).

GET /v3/consents/{id}/proof devolve o registo em PDF: a decisão, quem, o que foi mostrado, os hashes e como verificá-los. Está no idioma da sua área de cliente. Disponível no Pro e no Business (402 plan_required no Free), até 20 por minuto. Se o PDF não puder ser gerado neste momento, a resposta é 503 unavailable com Retry-After.

Cada registo granted traz evidence.snapshot_hash: o SHA-256 da página de consentimento tal como o visitante a viu, em HTML. Um mesmo instantâneo serve todos os visitantes da mesma página, ou seja, a mesma versão de aspeto e de texto, idioma e tipo de link. GET /v3/consents/{id}/snapshot devolve esse HTML com o hash no cabeçalho X-Snapshot-Hash, e GET /v3/consents/{id}/snapshot.png uma captura de ecrã. Para ambos valem as regras de GET /v3/consents/{id}, incluindo até onde o seu plano mostra o histórico.

Para a verificar, calcule o SHA-256 do HTML exatamente como o recebeu: é igual a snapshot_hash, e o hash do próprio registo na cadeia cobre snapshot_hash, por isso a página não pode ser trocada depois. O que muda de uma visita para outra está fixo no instantâneo: o host do destino aparece como example.com, a assinatura do formulário está vazia e a sua action é #. O endereço real está em dest_domain e evidence.destination.

Os registos reused, as recusas e os registos anteriores aos instantâneos têm snapshot_hash null, e o seu instantâneo responde 404 not_found («This record has no page snapshot.»). Logo a seguir a uma decisão os ficheiros podem ainda estar a ser escritos: 404 not_found com «The page snapshot is not ready yet.» quer dizer que tente de novo daqui a pouco. O HTML chega em segundos, a captura de ecrã um pouco depois. A página do registo na área de cliente e a prova em PDF também mostram a captura e o hash.

POST /v3/exports com os filtros de GET /v3/consents (decision, link, country, from, to) responde logo 202 com o id da exportação. O ficheiro é gerado em segundo plano: recebe o webhook export.ready, ou consulta GET /v3/exports/{id} até status ser ready, e depois descarrega GET /v3/exports/{id}/file. A exportação traz também rows e o sha256 do ficheiro.

Os ficheiros são guardados 7 dias (depois disso, 410 export_expired). Podem estar em curso até 3 exportações ao mesmo tempo (429 too_many_exports). Pro e Business.

GET /v3/stats/summary dá shown, granted, denied, left, reused e withdrawn para os dias UTC de from a to (2026-10-31, ambos incluídos; por omissão os últimos 30 dias, no máximo 366 dias, até onde o seu plano mostra o histórico). Acrescente link para um só link. GET /v3/stats/daily dá os mesmos números dia a dia e, no Pro e no Business, por país com by=country. Os bots nunca contam.

GET /v3/usage mostra os consentimentos deste período, o seu limit, o que resta (remaining) e o início e o fim do período.

A API, os webhooks e a página de consentimento em sete idiomas estão em todos os planos. Os planos diferem nos consentimentos por mês, em até onde o histórico é mostrado para trás, no ritmo de pedidos e nas funções extra. Preços em euros, sem IVA.

Só contam as novas aceitações: as recusas, as visitas repetidas com «Não perguntar novamente», e os bots não contam. Aos 80 % e aos 100 % do limite recebe um email e o webhook usage.warning.

Depois de esgotado o limite, os novos links reais são recusados com 402 limit_reached. Tudo o resto continua a funcionar: os links existentes continuam a perguntar e a registar, os webhooks e os tokens chegam como sempre e nada fica escondido. A criação de links reabre no início do período seguinte (no Free no dia 1 do mês, nos planos pagos no dia do pagamento) ou logo após subir de plano.

Por conta, todas as chaves em conjunto: 60 por minuto no Free, 300 no Pro, 1.000 no Business. Acima disso, a resposta é 429 rate_limited com um cabeçalho Retry-After; os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining mostram em que ponto está. Alguns métodos têm ainda um limite próprio: provas em PDF 20 por minuto, novas exportações 10, transferências de exportações 30.

Sempre com a mesma forma: o estado HTTP e um corpo JSON com um code estável e uma message em inglês. Atue com base no code; a mensagem pode ser reformulada. Campos inválidos dão 422 validation_failed com fields: cada campo com os seus problemas.

Crie uma chave nova em «Ligar pela API», passe o seu servidor para ela e depois revogue a antiga: deixa de funcionar de imediato. Revogar uma chave não afeta os seus links, o histórico nem os webhooks.

Guarde as chaves nas variáveis de ambiente do seu servidor, nunca num navegador, numa app móvel ou num repositório público. Se o segredo de um webhook puder ter sido divulgado, desative esse webhook na área de cliente e crie um novo.