Domande sull’API

Registrati e conferma la tua email. La prima pagina dopo l’accesso, «Collegati tramite API», crea la tua chiave clk_live_….

La chiave viene mostrata una sola volta, subito dopo la creazione, quindi copiala in quel momento: ne conserviamo solo l’hash. Un account può avere fino a 10 chiavi attive. Una chiave che non ti serve più si revoca nella stessa pagina e smette subito di funzionare.

L’API si trova su https://api.consent.link/v3 e parla JSON. Invia la chiave con ogni richiesta nell’intestazione Authorization: Bearer clk_live_… (funziona anche l’intestazione X-AUTH-TOKEN della nostra vecchia API v2). Una richiesta senza una chiave valida riceve 401 unauthenticated.

Chiama l’API solo dal tuo server. Chi possiede la chiave può creare link e leggere il tuo registro con tutti i dati dei visitatori.

Tutti a colpo d’occhio. Ogni percorso va dopo https://api.consent.link; le chiavi pubbliche per verificare i token di decisione sono su https://app.consent.link/.well-known/jwks.json.

Invia POST /v3/links con la destinazione. La risposta è 201 con il link: short è l’indirizzo da mettere in annunci, post ed email, id è il suo codice. Solo destination è obbligatorio.

I link si creano solo tramite l’API, mai nell’area clienti: ogni destinazione viene controllata alla creazione del link, e questo tiene lontano il phishing.

• destination: dove va il visitatore dopo aver deciso. Obbligatorio.
• type: la dicitura sulla pagina di consenso, una tra ad, sponsored, affiliate, none. Senza, la dicitura scelta in «Aspetto».
• template: il testo della pagina, l’id di un modello della nostra libreria (la tabella qui sotto). Senza, il modello scelto in «Aspetto».
• name: un tuo nome per il link, fino a 255 caratteri, mostrato nell’area clienti.
• external_id: un tuo id, per esempio di un post o di una campagna, fino a 255 caratteri. Puoi filtrare i link in base a questo; non si può cambiare in seguito.
• metadata: un tuo oggetto JSON, conservato e restituito così com’è.

La risposta contiene anche resolved_destination (per un tracker o un link breve, vedi sotto), status (active, disabled o blocked), mode (live o test) e created_at, più warnings quando c’è qualcosa da segnalare.

Un indirizzo assoluto http o https su un nome di dominio pubblico, fino a 2.048 caratteri: niente indirizzi IP, niente nome utente o password, niente spazi o barre rovesciate. Lo conserviamo byte per byte.

Ogni nuovo indirizzo viene controllato con la nostra lista di blocco e con Google Web Risk, e uno pericoloso viene rifiutato con 422 destination_blocked. Se in seguito un indirizzo si rivela pericoloso, il link viene bloccato: smette di aprirsi, non si può più modificare e il tuo webhook riceve link.blocked.

Quando l’host della destinazione è l’indirizzo di clic di una rete di affiliazione o di un accorciatore di link, come awin1.com, sjv.io, prf.hn, admitad.com, amzn.to, bit.ly (anche i sottodomini), seguiamo noi stessi i suoi reindirizzamenti: quando il link viene creato, anche in blocco, e quando PATCH ne cambia la destination. Sono fino a 5 reindirizzamenti in pochi secondi. L’indirizzo in cui la catena lascia i tracker per un altro sito viene salvato, byte per byte, come resolved_destination. Non interroghiamo mai altre destinazioni, e il loro resolved_destination resta null.

destination resta esattamente come l’hai inviata. Con il consenso il visitatore va lì, passando dal tracker. Senza consenso va direttamente a resolved_destination, saltando il tracker e senza gli identificatori dei clic sugli annunci.

Se la catena non si può seguire (il tracker non reindirizza, è troppo lento, reindirizza troppe volte, porta a un indirizzo interno o bloccato, o non lascia mai i tracker), il link viene creato comunque, ma per ora un rifiuto passa dal tracker. Ogni risposta che mostra il link contiene allora warnings con il codice tracker_unresolved, e anche la pagina del link nell’area clienti lo segnala. Riproviamo in background, aspettando 5 minuti, 1 ora tra un tentativo e l’altro; quando riesce, resolved_destination viene compilato e l’avviso sparisce. Dopo l’ultimo tentativo controlla l’indirizzo e invialo di nuovo con PATCH. Quando non c’è nulla da segnalare, la risposta non ha warnings.

Le nostre richieste ai tracker portano lo User-Agent Consent.link-Resolver/1 (+https://consent.link/faq/api).

Invia l’intestazione Idempotency-Key con POST /v3/links e POST /v3/links/bulk: da 1 a 255 caratteri ASCII stampabili, per esempio un UUID o un tuo id del post. Una ripetizione con la stessa chiave e lo stesso corpo entro 24 ore restituisce i link già creati, con l’intestazione Idempotent-Replayed: true, e non crea nulla.

La stessa chiave con un corpo diverso viene rifiutata con 422 idempotency_key_reused. Se la prima richiesta è ancora in corso, la ripetizione riceve 409 idempotency_in_progress: aspetta un attimo e inviala di nuovo.

Sì: POST /v3/links/bulk con {"links": [ … ]}, fino a 500 link per richiesta, ciascuno con gli stessi campi di un link singolo. La risposta è 201 con data, i link nell’ordine in cui li hai inviati.

È tutto o niente: se un elemento non è valido, non viene creato nulla e l’errore lo indica, per esempio links.3.destination.

PATCH /v3/links/{id} solo con i campi da cambiare: destination, type, template, name, metadata. null svuota un campo facoltativo, metadata viene sostituito per intero e external_id resta com’era alla creazione. La pagina di consenso mostra subito la modifica. Una nuova destinazione viene controllata come quella di un nuovo link e, se è su un altro dominio, i consensi precedenti con «Non chiedere più» per il vecchio dominio non fanno più passare i visitatori.

DELETE /v3/links/{id} disattiva il link: smette di aprirsi e non si può più modificare né riattivare, mentre le sue registrazioni restano nel registro. Crea un nuovo link se ti serve di nuovo.

GET /v3/links elenca i tuoi link, dai più recenti, 50 per pagina (fino a 100 con limit). Filtri: status, mode, type, template, external_id, domain, e from e to per la data di creazione (2026-10-31 o 2026-10-31T14:00:00Z). Per la pagina successiva passa next_cursor della risposta come cursor; null significa che non ci sono altre pagine.

GET /v3/links/{id} restituisce un link con le stats dalla sua creazione: shown, granted, denied, left (ha lasciato la pagina senza decidere), reused e withdrawn. I numeri sono qualche minuto indietro rispetto al registro.

La pagina che imposti in «Aspetto» nell’area clienti: il modello di testo della nostra libreria, i destinatari dei dati, la dicitura, il link alla tua informativa privacy e, su Business, il tuo logo e il tuo colore. I type e template propri del link hanno la precedenza sull’aspetto. Quando pubblichi una nuova versione, le pagine dei tuoi link cambiano entro un minuto.

La lingua viene presa dal browser del visitatore: inglese, spagnolo, tedesco, francese, italiano, portoghese o russo. Scegli un modello, non le parole: i testi vengono dalla nostra libreria, quindi non puoi scriverne di tuoi.

Finché in «Aspetto» non è pubblicato nulla, la pagina non mostra il link alla tua informativa sulla privacy né i destinatari dei dati. I link vengono comunque creati, e le risposte a POST /v3/links, POST /v3/links/bulk e PATCH /v3/links/{id} portano l'intestazione Consent-Link-Warning: design_unpublished finché la configurazione del link non ha una versione pubblicata.

Salva più profili della pagina in «Aspetto» o tramite l’API, ciascuno con un proprio id come black-friday, e indicane uno quando crei un link: "profile": "black-friday" in POST /v3/links o in un elemento della creazione in blocco. Senza profile il link riceve il tuo profilo predefinito.

Un link mantiene il suo profilo: se in seguito un altro profilo diventa il predefinito, i link vecchi non cambiano. PATCH /v3/links/{id} con profile sposta un link, e "profile": null lo sposta sul predefinito di quel momento. Un id sconosciuto dà 422 sul campo profile. L’oggetto del link mostra il suo profile, e GET /v3/links?profile=black-friday elenca i link di un profilo. Quanti profili puoi avere dipende dal piano: 1 su Free, 5 su Pro, 50 su Business, predefinito compreso.

GET /v3/profiles li elenca, il predefinito per primo. POST /v3/profiles ne crea uno con id e policy_url (obbligatori) e, se vuoi, name, template, vendors, type, remember, brand_name e default. Viene pubblicato subito. PATCH /v3/profiles/{id} lo modifica: i campi della pagina pubblicano subito una nuova versione, name e "default": true da soli non pubblicano nulla.

DELETE /v3/profiles/{id} elimina un profilo che non è il predefinito (409 profile_is_default) e non ha link attivi (409 profile_in_use). Crearne uno oltre il limite del piano, o usarne uno rimasto oltre il limite dopo il passaggio a un piano inferiore, dà 402 profiles_limit_reached. Le modifiche richiedono una chiave reale.

Con il consenso il visitatore va alla tua destinazione esattamente come l’hai indicata. Senza consenso anche utm_* e gli altri tuoi parametri restano, e vengono tolti solo gli identificatori dei clic sugli annunci: gclid, gbraid, wbraid, fbclid, msclkid, ttclid, twclid, li_fat_id. In entrambi i casi aggiungiamo un parametro, cl_ct, il token di decisione.

Contano solo i parametri della destinazione stessa: ciò che viene aggiunto al link breve (https://consent.link/nk7Qa?utm_source=…) non viene passato. Metti in destination tutto ciò che serve al tuo sito, oppure crea un link per campagna.

Ogni reindirizzamento dalla pagina di consenso porta cl_ct, un token firmato (JWT, ES256) che vale 10 minuti. Verificalo dal tuo server con POST /v3/consents/verify: la risposta contiene la decisione, e ogni token si può verificare una sola volta, quindi un indirizzo copiato non vale nulla. Leggi il token, poi toglilo dall’indirizzo.

Cosa contiene: decision (granted o denied), purposes (cosa ha permesso il visitatore), cid (la registrazione nel registro), sid (lo pseudonimo del visitatore nel tuo account, lo stesso su tutti i tuoi link), cexp (fino a quando vale il consenso, in tempo Unix), link, mode, iat e exp. Niente IP, browser o altri dati personali. Un visitatore che ha già accettato lasciando «Non chiedere più» passa direttamente, con granted.

Puoi anche verificare la firma da solo con le chiavi su https://app.consent.link/.well-known/jwks.json e qualsiasi libreria JWT: controlla exp e che link sia uno dei tuoi link. La tua verifica non può sapere se un token è già stato usato; il metodo dell’API sì. Errori: 422 token_invalid, 422 token_expired, 409 token_used.

Crea un webhook: POST /v3/webhooks con url e gli events che ti servono (la tabella qui sotto). L’indirizzo deve essere https su un nome host pubblico. La risposta contiene secret (whsec_…) per verificare le firme: viene mostrato una sola volta, quindi salvalo. Un account può avere fino a 10 webhook attivi.

Lo storico delle consegne, il pulsante «Riprova» e l’attivazione o disattivazione di un webhook sono nell’area clienti, in «Account» → «Webhook».

Ogni evento è un POST con un corpo JSON: id (evt_…), type, created_at, mode e data. Una registrazione di consenso in data.consent ha id, link, decision, purposes, scope (domain se il visitatore ha lasciato «Non chiedere più», altrimenti link), sid, dest_domain, country, notice_version, created_at ed expires_at. Mai un IP, un browser o un cookie.

Ogni richiesta porta le intestazioni Consent-Event, Consent-Delivery e Consent-Signature: t=1793712000,v1=5f3a…. v1 è l’HMAC-SHA256 esadecimale del testo t, un punto e il corpo grezzo della richiesta, con il segreto del tuo webhook come chiave.

Calcolalo sul corpo così come è arrivato (prima di interpretare il JSON), confronta in tempo costante e rifiuta un t che si discosti di più di cinque minuti dal tuo orologio, così una richiesta registrata non può essere ripetuta.

Una consegna conta quando il tuo server risponde 2xx entro 10 secondi; i reindirizzamenti non vengono seguiti. Altrimenti riproviamo, aspettando 1 minuto, 5 minuti, 30 minuti, 2 ore, 12 ore tra un tentativo e l’altro, 6 tentativi in tutto. Dopo l’ultimo la consegna viene segnata come fallita e resta nello storico, dove «Riprova» la invia di nuovo fino a 3 giorni dopo l’evento.

Quindi rispondi in fretta e fai il lavoro dopo. Lo stesso evento può arrivare più di una volta, per esempio dopo un timeout: salta gli id che hai già elaborato. Gli eventi non arrivano sempre nell’ordine in cui sono avvenuti.

I visitatori vedono e revocano i loro consensi su «I miei consensi». Se un visitatore si rivolge invece a te, revocalo per suo conto: POST /v3/consents/{id}/withdraw, senza corpo, con l’id della sua registrazione granted o reused. Funziona per qualsiasi consenso ancora in vigore, per quanto indietro il tuo piano mostri il registro. La risposta è 201 con la nuova registrazione withdrawn, il cui first_consent_id è il consenso revocato. Una registrazione che non è un consenso in vigore (rifiutato, già revocato o scaduto) riceve 409 consent_not_in_force; una che non puoi leggere, 404, come con GET /v3/consents/{id}.

Le due strade portano allo stesso risultato: una registrazione withdrawn nel registro, consent.withdrawn al tuo webhook con data.withdraws, l’id del consenso revocato, e da quel momento i tuoi link chiedono di nuovo a quel visitatore. Una revoca chiude tutti i consensi che il visitatore aveva dato prima per quel dominio, e non conta nel tuo limite.

Smetti di usare i dati del visitatore da parte tua: trovali tramite sid o tramite l’id della registrazione.

Un consenso vale 6 mesi da quando è stato dato: expires_at nella registrazione, cexp nel token di decisione. Una registrazione reused porta l’expires_at del consenso che riutilizza. Dopo, i tuoi link chiedono di nuovo al visitatore.

Quando un consenso granted scade senza essere stato revocato, il tuo webhook riceve consent.expired con data.consent, la registrazione, e data.expired_at. Controlliamo una volta all’ora, quindi arriva entro l’ora successiva a expires_at, una volta per consenso. Le registrazioni reused non hanno un evento proprio: le copre quello del consenso che riutilizzano. L’evento va solo ai webhook con consent.expired in events. Una scadenza viene annunciata una volta sola, anche se allora nessun webhook la aspettava: non viene inviata di nuovo più tardi.

Inserisci il nostro script in <head>, prima di GTM e gtag: https://consent.link/js/consent.js. Imposta i valori predefiniti di Consent Mode v2 (tutto negato tranne functionality_storage e security_storage, con wait_for_update di 500 ms), legge cl_ct dall'indirizzo, verifica la firma con le chiavi di https://app.consent.link/.well-known/jwks.json direttamente nel browser e aggiorna il consenso.

La decisione resta nel cookie cl_consent del tuo dominio: fino a cexp per un consenso, 180 giorni per un rifiuto, così le pagine successive non hanno bisogno del banner. Dopo la verifica cl_ct esce dalla barra degli indirizzi; gli altri parametri restano. Lo script non ci invia nulla.

Se registri la decisione da te, verifica il token anche dal tuo server con POST /v3/consents/verify: lo script non può sapere se il token è già stato usato.

Scarica il modello consent-link.tpl; in GTM apri Modelli → Nuovo → ⋮ → Importa e salva. Crea un tag dal modello con l'attivatore «Consent Initialization – All Pages» («Inizializzazione del consenso – Tutte le pagine»).

Il tag imposta i valori predefiniti, applica la decisione salvata nel cookie cl_consent e carica lo script, che verifica un cl_ct recente. Non serve allora mettere anche lo script in <head>.

Le purposes del token concedono questi segnali. Ciò che non è concesso resta negato; un rifiuto (denied) nega tutto tranne i due sempre concessi.

Non mostrare un secondo banner a chi ha già deciso sulla nostra pagina. Lo script fornisce la decisione in window.consentLink.decision (granted, denied o null) e window.consentLink.has('stats'); window.consentLink.ready si risolve quando il token nell'indirizzo è stato verificato. Ci sono anche l'evento consentlink:update su document e consent_link_update in dataLayer. Carica il nostro script prima di quello del banner.

Cookiebot: passa la decisione con Cookiebot.submitCustomConsent e il suo banner non compare. OneTrust non ha una funzione pubblica per registrare il consenso dal sito, quindi carica il suo script solo se non c'è una decisione. Con gli altri banner allo stesso modo: passa le finalità tramite la loro API o non caricare il banner.

GET /v3/consents elenca le registrazioni, dalle più recenti, con i filtri decision (granted, denied, reused, withdrawn), link, country (DE), from, to e la stessa paginazione dei link. GET /v3/consents/{id} restituisce una registrazione con le sue prove (indirizzo IP, browser, lingua, l’hash del testo della pagina, quando è stata mostrata la pagina e quanto ci ha messo il visitatore) e il suo posto nella catena di hash, chain.

Un rifiuto conserva solo la decisione, l’ora, il link e il paese, quindi il suo evidence è null. L’API dà i dati completi; l’area clienti ne nasconde una parte finché non attivi l’accesso in due passaggi. Quanto indietro puoi vedere dipende dal piano (la tabella in «Piani e limiti»).

GET /v3/consents/{id}/proof restituisce la registrazione in PDF: la decisione, chi, cosa è stato mostrato, gli hash e come verificarli. È nella lingua della tua area clienti. Disponibile su Pro e Business (402 plan_required su Free), fino a 20 al minuto. Se il PDF non si può generare in quel momento, la risposta è 503 unavailable con Retry-After.

Ogni registrazione granted porta evidence.snapshot_hash: lo SHA-256 della pagina di consenso così come l’ha vista il visitatore, in HTML. Una stessa istantanea vale per tutti i visitatori della stessa pagina, cioè stessa versione di aspetto e testo, lingua e tipo di link. GET /v3/consents/{id}/snapshot restituisce quell’HTML con l’hash nell’intestazione X-Snapshot-Hash, e GET /v3/consents/{id}/snapshot.png uno screenshot. Per entrambi valgono le regole di GET /v3/consents/{id}, compresa la profondità del registro.

Per verificarla, calcola lo SHA-256 dell’HTML esattamente come ricevuto: è uguale a snapshot_hash, e l’hash della registrazione stessa nella catena copre snapshot_hash, quindi la pagina non si può sostituire a posteriori. Ciò che cambia da una visita all’altra è fissato nell’istantanea: l’host della destinazione appare come example.com, la firma del modulo è vuota e la sua action è #. L’indirizzo vero è in dest_domain e evidence.destination.

Le registrazioni reused, i rifiuti e le registrazioni precedenti alle istantanee hanno snapshot_hash null, e la loro istantanea risponde 404 not_found («This record has no page snapshot.»). Subito dopo una decisione i file possono essere ancora in scrittura: 404 not_found con «The page snapshot is not ready yet.» vuol dire riprovare tra poco. L’HTML arriva in pochi secondi, lo screenshot poco dopo. Anche la pagina della registrazione nell’area clienti e la prova in PDF mostrano lo screenshot e l’hash.

POST /v3/exports con i filtri di GET /v3/consents (decision, link, country, from, to) risponde subito 202 con l’id dell’esportazione. Il file viene generato in background: ricevi il webhook export.ready, oppure controlli GET /v3/exports/{id} finché status è ready, poi scarichi GET /v3/exports/{id}/file. L’esportazione riporta anche rows e lo sha256 del file.

I file vengono conservati 7 giorni (dopo, 410 export_expired). Possono essere in corso fino a 3 esportazioni contemporaneamente (429 too_many_exports). Pro e Business.

GET /v3/stats/summary dà shown, granted, denied, left, reused e withdrawn per i giorni UTC da from a to (2026-10-31, entrambi inclusi; di default gli ultimi 30 giorni, al massimo 366 giorni, fin dove il tuo piano mostra il registro). Aggiungi link per un solo link. GET /v3/stats/daily dà gli stessi numeri giorno per giorno e, su Pro e Business, per paese con by=country. I bot non si contano mai.

GET /v3/usage mostra i consensi di questo periodo, il tuo limit, quanto resta (remaining) e l’inizio e la fine del periodo.

L’API, i webhook e la pagina di consenso in sette lingue sono in ogni piano. I piani si differenziano per i consensi al mese, quanto indietro si vede il registro, il ritmo delle richieste e le funzioni in più. Prezzi in euro, IVA esclusa.

Contano solo i nuovi consensi dati: i rifiuti, le visite ripetute con «Non chiedere più», e i bot no. All’80 % e al 100 % del limite ricevi un’email e il webhook usage.warning.

Una volta esaurito il limite, i nuovi link reali vengono rifiutati con 402 limit_reached. Tutto il resto continua a funzionare: i link esistenti continuano a chiedere e registrare, webhook e token arrivano come sempre e non viene nascosto nulla. La creazione di link riapre all’inizio del periodo successivo (su Free il primo del mese, sui piani a pagamento il giorno del pagamento) o subito dopo il passaggio a un piano superiore.

Per account, tutte le chiavi insieme: 60 al minuto su Free, 300 su Pro, 1.000 su Business. Oltre, la risposta è 429 rate_limited con un’intestazione Retry-After; le intestazioni X-RateLimit-Limit e X-RateLimit-Remaining mostrano a che punto sei. Alcuni metodi hanno anche un limite proprio: prove PDF 20 al minuto, nuove esportazioni 10, download di esportazioni 30.

Sempre nella stessa forma: lo stato HTTP e un corpo JSON con un code stabile e un message in inglese. Basati sul code; il messaggio può essere riformulato. I campi non validi danno 422 validation_failed con fields: ogni campo con i suoi problemi.

Crea una nuova chiave su «Collegati tramite API», passa il tuo server alla nuova chiave, poi revoca la vecchia: smette subito di funzionare. Revocare una chiave non tocca i tuoi link, il registro o i webhook.

Tieni le chiavi nelle variabili d’ambiente del tuo server, mai in un browser, in un’app mobile o in un repository pubblico. Se il segreto di un webhook può essere trapelato, disattiva quel webhook nell’area clienti e creane uno nuovo.