Preguntas sobre la API

Regístrate y confirma tu correo. La primera página tras iniciar sesión, «Conectar por API», crea tu clave clk_live_….

La clave se muestra una sola vez, justo al crearla, así que cópiala en ese momento: solo guardamos su hash. Una cuenta puede tener hasta 10 claves activas. La clave que ya no necesites se revoca en la misma página y deja de funcionar al instante.

La API está en https://api.consent.link/v3 y habla JSON. Envía la clave en cada petición en la cabecera Authorization: Bearer clk_live_… (también vale la cabecera X-AUTH-TOKEN de nuestra antigua API v2). Una petición sin una clave válida recibe 401 unauthenticated.

Llama a la API solo desde tu servidor. Quien tenga la clave puede crear enlaces y leer tu registro con todos los datos de los visitantes.

Todos de un vistazo. Cada ruta va detrás de https://api.consent.link; las claves públicas para comprobar los tokens de decisión están en https://api.consent.link/.well-known/jwks.json.

Envía POST /v3/links con el destino. La respuesta es 201 con el enlace: short es la dirección que pones en tus anuncios, publicaciones y correos, id es su código. Solo destination es obligatorio.

Los enlaces se crean solo con la API, nunca en el panel: cada destino se comprueba al crear el enlace, lo que deja fuera el phishing.

• destination: adónde va el visitante después de decidir. Obligatorio.
• type: la etiqueta de la página de consentimiento, una de ad, sponsored, affiliate, none. Sin él, la etiqueta elegida en «Diseño».
• template: el texto de la página, un id de plantilla de nuestra biblioteca (la tabla de abajo). Sin él, la plantilla elegida en «Diseño».
• name: tu propio nombre para el enlace, hasta 255 caracteres, visible en el panel.
• external_id: tu propio id, por ejemplo de una publicación o una campaña, hasta 255 caracteres. Puedes filtrar los enlaces por él; no se puede cambiar después.
• metadata: un objeto JSON propio, que guardamos y devolvemos tal cual.

La respuesta lleva además resolved_destination (para un rastreador o un enlace corto, ver más abajo), status (active, disabled o blocked), mode (live o test) y created_at; warnings, solo cuando hay algo que avisar.

Una dirección absoluta http o https con un nombre de dominio público, de hasta 2048 caracteres: sin direcciones IP, sin usuario ni contraseña, sin espacios ni barras invertidas. La guardamos byte a byte.

Cada dirección nueva se comprueba con nuestra lista de bloqueo y con Google Web Risk, y una peligrosa se rechaza con 422 destination_blocked. Si más tarde una dirección resulta peligrosa, el enlace se bloquea: deja de abrirse, ya no se puede cambiar y tu webhook recibe link.blocked.

Cuando el host del destino es la dirección de clic de una red de afiliados o de un acortador de enlaces, como awin1.com, sjv.io, prf.hn, admitad.com, amzn.to, bit.ly (también sus subdominios), seguimos nosotros mismos sus redirecciones: al crear el enlace, también en lote, y cuando PATCH cambia su destination. Son hasta 5 redirecciones en pocos segundos. La dirección donde la cadena sale de los rastreadores hacia otro sitio se guarda, byte a byte, como resolved_destination. Nunca consultamos otros destinos, y su resolved_destination se queda en null.

destination se queda exactamente como lo enviaste. Con consentimiento, el visitante va allí, a través del rastreador. Sin consentimiento, va directamente a resolved_destination, sin pasar por el rastreador y sin los identificadores de clic de anuncios.

Si no se puede seguir la cadena (el rastreador no redirige, tarda demasiado, redirige demasiadas veces, lleva a una dirección interna o bloqueada o nunca sale de los rastreadores), el enlace se crea igualmente, pero de momento un rechazo pasa por el rastreador. Entonces cada respuesta que muestra el enlace lleva warnings con el código tracker_unresolved, y la página del enlace en el panel también lo indica. Lo intentamos de nuevo en segundo plano, esperando 5 minutos, 1 hora entre intentos; cuando funciona, resolved_destination se rellena y el aviso desaparece. Tras el último intento, revisa la dirección y envíala de nuevo con PATCH. Cuando no hay nada que avisar, la respuesta no lleva warnings.

Nuestras peticiones a los rastreadores llevan el User-Agent Consent.link-Resolver/1 (+https://consent.link/faq/api).

Envía la cabecera Idempotency-Key con POST /v3/links y POST /v3/links/bulk: de 1 a 255 caracteres ASCII imprimibles, por ejemplo un UUID o tu propio id de la publicación. Una repetición con la misma clave y el mismo cuerpo en un plazo de 24 horas devuelve los enlaces ya creados, con la cabecera Idempotent-Replayed: true, y no crea nada.

La misma clave con otro cuerpo se rechaza con 422 idempotency_key_reused. Si la primera petición aún está en curso, la repetición recibe 409 idempotency_in_progress: espera un momento y vuelve a enviarla.

Sí: POST /v3/links/bulk con {"links": [ … ]}, hasta 500 enlaces por petición, cada uno con los mismos campos que un enlace suelto. La respuesta es 201 con data, los enlaces en el orden en que los enviaste.

Es todo o nada: si un elemento no es válido, no se crea nada y el error lo señala, por ejemplo links.3.destination.

PATCH /v3/links/{id} solo con los campos que cambian: destination, type, template, name, metadata. null borra un campo opcional, metadata se sustituye entero y external_id se queda como se creó. La página de consentimiento muestra el cambio al instante. Un destino nuevo se comprueba igual que el de un enlace nuevo y, si está en otro dominio, los consentimientos anteriores con «No volver a preguntar» para el dominio antiguo dejan de dejar pasar a los visitantes.

DELETE /v3/links/{id} desactiva el enlace: deja de abrirse y ya no se puede cambiar ni volver a activar, mientras que sus registros se quedan en el registro. Crea un enlace nuevo si lo necesitas de nuevo.

GET /v3/links lista tus enlaces, los más nuevos primero, 50 por página (hasta 100 con limit). Filtros: status, mode, type, template, external_id, domain, y from y to para la fecha de creación (2026-10-31 o 2026-10-31T14:00:00Z). Para la página siguiente, pasa next_cursor de la respuesta como cursor; null significa que no hay más páginas.

GET /v3/links/{id} devuelve un enlace con stats desde su creación: shown, granted, denied, left (salió de la página sin decidir), reused y withdrawn. Las cifras van unos minutos por detrás del registro.

La página que configuras en «Diseño» en el panel: la plantilla de texto de nuestra biblioteca, los destinatarios de los datos, la etiqueta, el enlace a tu política de privacidad y, en Business, tu logotipo y tu color. Los type y template propios del enlace tienen prioridad sobre el diseño. Cuando publicas una versión nueva, las páginas de tus enlaces cambian en menos de un minuto.

El idioma se toma del navegador del visitante: inglés, español, alemán, francés, italiano, portugués o ruso. Eliges una plantilla, no palabras: los textos vienen de nuestra biblioteca, así que no puedes escribir los tuyos.

Mientras no haya nada publicado en «Diseño», la página no muestra el enlace a tu política de privacidad ni los destinatarios de los datos. Los enlaces se crean igualmente, y las respuestas a POST /v3/links, POST /v3/links/bulk y PATCH /v3/links/{id} llevan la cabecera Consent-Link-Warning: design_unpublished mientras la configuración del enlace no tenga una versión publicada.

Guarda varios perfiles de la página en «Diseño» o con la API, cada uno con su propio id, como black-friday, e indica uno al crear un enlace: "profile": "black-friday" en POST /v3/links o en un elemento de la creación masiva. Sin profile, el enlace recibe tu perfil predeterminado.

Un enlace conserva su perfil: si más tarde otro perfil pasa a ser el predeterminado, los enlaces antiguos no cambian. PATCH /v3/links/{id} con profile mueve un enlace, y "profile": null lo mueve al predeterminado de ese momento. Un id desconocido da 422 en el campo profile. El objeto del enlace muestra su profile, y GET /v3/links?profile=black-friday lista los enlaces de un perfil. Cuántos perfiles puedes tener depende del plan: 1 en Free, 5 en Pro, 50 en Business, contando el predeterminado.

GET /v3/profiles los lista, el predeterminado primero. POST /v3/profiles crea uno con id y policy_url (obligatorios) y, si quieres, name, template, vendors, type, remember, brand_name y default. Se publica al instante. PATCH /v3/profiles/{id} lo cambia: los campos de la página publican una versión nueva en el acto; name y "default": true por sí solos no publican nada.

DELETE /v3/profiles/{id} elimina un perfil que no sea el predeterminado (409 profile_is_default) y que no tenga enlaces activos (409 profile_in_use). Crear uno por encima del límite del plan, o usar uno que quedó por encima del límite tras bajar de plan, da 402 profiles_limit_reached. Los cambios necesitan una clave real.

Con consentimiento, el visitante va a tu destino exactamente como lo indicaste. Sin consentimiento, utm_* y tus demás parámetros también se quedan, y solo se quitan los identificadores de clic de anuncios: gclid, gbraid, wbraid, fbclid, msclkid, ttclid, twclid, li_fat_id. En ambos casos añadimos un parámetro, cl_ct, el token de decisión.

Solo cuentan los parámetros del propio destino: lo que se añada al enlace corto (https://consent.link/nk7Qa?utm_source=…) no se transmite. Pon en destination todo lo que necesita tu sitio, o crea un enlace por campaña.

Cada redirección desde la página de consentimiento lleva cl_ct, un token firmado (JWT, ES256) que vive 10 minutos. Compruébalo desde tu servidor con POST /v3/consents/verify: la respuesta trae la decisión, y cada token se puede comprobar una sola vez, así que una dirección copiada no sirve de nada. Lee el token y luego quítalo de la dirección.

Lo que contiene: decision (granted o denied), purposes (lo que permitió el visitante), cid (el registro), sid (el seudónimo del visitante en tu cuenta, el mismo en todos tus enlaces), cexp (hasta cuándo vale el consentimiento, en tiempo Unix), link, mode, iat y exp. Ni IP, ni navegador, ni otros datos personales. Un visitante que ya aceptó y dejó marcado «No volver a preguntar» pasa directamente, con granted.

También puedes comprobar la firma tú mismo con las claves de https://api.consent.link/.well-known/jwks.json y cualquier biblioteca JWT: comprueba exp y que link sea uno de tus enlaces. Tu propia comprobación no sabe si un token ya se usó; el método de la API sí. Errores: 422 token_invalid, 422 token_expired, 409 token_used.

Crea un webhook: POST /v3/webhooks con url y los events que quieras (la tabla de abajo). La dirección debe ser https con un nombre de host público. La respuesta trae secret (whsec_…) para comprobar las firmas: se muestra una sola vez, así que guárdalo. Una cuenta puede tener hasta 10 webhooks activos.

El historial de entregas, el botón «Reintentar» y la activación o desactivación de un webhook están en el panel, en «Cuenta» → «Webhooks».

Cada evento es un POST con un cuerpo JSON: id (evt_…), type, created_at, mode y data. Un registro de consentimiento en data.consent tiene id, link, decision, purposes, scope (domain si el visitante dejó marcado «No volver a preguntar», si no link), sid, dest_domain, country, notice_version, created_at y expires_at. Nunca una IP, un navegador ni una cookie.

Cada petición lleva las cabeceras Consent-Event, Consent-Delivery y Consent-Signature: t=1793712000,v1=5f3a…. v1 es el HMAC-SHA256 en hexadecimal del texto t, un punto y el cuerpo bruto de la petición, con el secreto de tu webhook como clave.

Calcúlalo sobre el cuerpo tal como llegó (antes de interpretar el JSON), compara en tiempo constante y rechaza un t que se aleje más de cinco minutos de tu reloj, para que una petición grabada no se pueda reenviar.

Una entrega cuenta cuando tu servidor responde 2xx en 10 segundos; las redirecciones no se siguen. Si no, lo intentamos de nuevo, esperando 1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas entre intentos, 6 intentos en total. Tras el último, la entrega se marca como fallida y se queda en el historial, donde «Reintentar» la vuelve a enviar hasta 3 días después del evento.

Así que responde rápido y haz el trabajo después. El mismo evento puede llegar más de una vez, por ejemplo tras un tiempo de espera agotado: omite los id que ya procesaste. Los eventos no siempre llegan en el orden en que ocurrieron.

Los visitantes ven y retiran sus consentimientos en «Mis consentimientos». Si un visitante te lo pide a ti, retíralo en su nombre: POST /v3/consents/{id}/withdraw, sin cuerpo, con el id de su registro granted o reused. Funciona para cualquier consentimiento aún vigente, sin importar hasta dónde muestre tu plan el registro. La respuesta es 201 con el nuevo registro withdrawn, cuyo first_consent_id es el consentimiento retirado. Un registro que no es un consentimiento vigente (rechazado, ya retirado o caducado) recibe 409 consent_not_in_force; uno que no puedes leer, 404, como con GET /v3/consents/{id}.

Las dos vías dan el mismo resultado: un registro withdrawn, consent.withdrawn en tu webhook con data.withdraws, el id del consentimiento retirado, y a partir de ese momento tus enlaces vuelven a preguntar a ese visitante. Una retirada cierra todos los consentimientos que el visitante dio antes para ese dominio, y no cuenta para tu límite.

Deja de usar los datos del visitante por tu parte: búscalos por sid o por el id del registro.

Un consentimiento vale 6 meses desde que se dio: expires_at en el registro, cexp en el token de decisión. Un registro reused lleva el expires_at del consentimiento que reutiliza. Después, tus enlaces vuelven a preguntar al visitante.

Cuando un consentimiento granted caduca sin haberse retirado, tu webhook recibe consent.expired con data.consent, el registro, y data.expired_at. Lo comprobamos una vez por hora, así que llega en la hora siguiente a expires_at, una vez por consentimiento. Los registros reused no tienen evento propio: los cubre el del consentimiento que reutilizan. El evento solo va a los webhooks con consent.expired en events. Cada caducidad se avisa una sola vez, aunque entonces ningún webhook la esperara: no se vuelve a enviar más tarde.

Coloca nuestro script en <head>, antes de GTM y gtag: https://consent.link/js/consent.js. Fija los valores predeterminados de Consent Mode v2 (todo denegado salvo functionality_storage y security_storage, con wait_for_update de 500 ms), lee cl_ct de la dirección, comprueba su firma con las claves de https://api.consent.link/.well-known/jwks.json en el propio navegador y actualiza el consentimiento.

La decisión se guarda en la cookie cl_consent de tu dominio: hasta cexp si hay consentimiento y 180 días si hay rechazo, así que las páginas siguientes no necesitan banner. Tras comprobarlo, cl_ct sale de la barra de direcciones; tus otros parámetros se quedan. El script no nos envía nada.

Si guardas la decisión en tu lado, comprueba también el token desde tu servidor con POST /v3/consents/verify: el script no puede saber si el token ya se usó.

Descarga la plantilla consent-link.tpl; en GTM abre Plantillas → Nueva → ⋮ → Importar y guárdala. Crea una etiqueta con ella y el activador «Consent Initialization – All Pages» («Inicialización del consentimiento – Todas las páginas»).

La etiqueta fija los valores predeterminados, aplica la decisión guardada en la cookie cl_consent y carga el script, que comprueba un cl_ct nuevo. Así no hace falta poner también el script en <head>.

Las purposes del token conceden estas señales. Lo que no se concede sigue denegado; un rechazo (denied) deniega todo salvo las dos que siempre se conceden.

No muestres un segundo banner a quien ya decidió en nuestra página. El script da la decisión en window.consentLink.decision (granted, denied o null) y window.consentLink.has('stats'); window.consentLink.ready se resuelve cuando se ha comprobado el token de la dirección. También están el evento consentlink:update en document y consent_link_update en dataLayer. Carga nuestro script antes que el del banner.

Cookiebot: pasa la decisión con Cookiebot.submitCustomConsent y su banner no aparece. OneTrust no tiene una función pública para registrar el consentimiento desde el sitio, así que carga su script solo cuando no haya decisión. Con otros banners igual: pasa las finalidades por su API o no cargues el banner.

GET /v3/consents lista los registros, los más nuevos primero, con los filtros decision (granted, denied, reused, withdrawn), link, country (DE), from, to y la misma paginación que los enlaces. GET /v3/consents/{id} devuelve un registro con sus pruebas (dirección IP, navegador, idioma, el hash del texto de la página, cuándo se mostró la página y cuánto tardó el visitante) y su lugar en la cadena de hashes, chain.

Un rechazo guarda solo la decisión, la hora, el enlace y el país, así que su evidence es null. La API da los datos completos; el panel oculta una parte hasta que activas el inicio de sesión en dos pasos. Hasta dónde puedes ver hacia atrás depende del plan (la tabla de «Planes y límites»).

GET /v3/consents/{id}/proof devuelve el registro en PDF: la decisión, quién, qué se mostró, los hashes y cómo comprobarlos. Está en el idioma de tu panel. Disponible en Pro y Business (402 plan_required en Free), hasta 20 por minuto. Si el PDF no se puede generar ahora mismo, la respuesta es 503 unavailable con Retry-After.

Cada registro granted lleva evidence.snapshot_hash: el SHA-256 de la página de consentimiento tal como la vio el visitante, en HTML. Una misma captura sirve para todos los visitantes de la misma página, es decir, la misma versión de diseño y de texto, idioma y tipo de enlace. GET /v3/consents/{id}/snapshot devuelve ese HTML con el hash en la cabecera X-Snapshot-Hash, y GET /v3/consents/{id}/snapshot.png, una captura de pantalla. Para ambos valen las reglas de GET /v3/consents/{id}, incluido hasta dónde muestra tu plan el registro.

Para comprobarla, calcula el SHA-256 del HTML exactamente como lo recibiste: coincide con snapshot_hash, y el hash del propio registro en la cadena cubre snapshot_hash, así que la página no se puede cambiar después. Lo que varía de una visita a otra está fijado en la captura: el host del destino aparece como example.com, la firma del formulario está vacía y su action es #. La dirección real está en dest_domain y evidence.destination.

Los registros reused, los rechazos y los registros anteriores a las capturas tienen snapshot_hash null, y su captura responde 404 not_found («This record has no page snapshot.»). Justo después de una decisión los archivos pueden estar escribiéndose aún: 404 not_found con «The page snapshot is not ready yet.» significa que lo intentes de nuevo en un momento. El HTML llega en segundos y la captura de pantalla algo después. La página del registro en el panel y la prueba en PDF también muestran la captura y el hash.

POST /v3/exports con los filtros de GET /v3/consents (decision, link, country, from, to) responde 202 al instante con el id de la exportación. El archivo se genera en segundo plano: recibes el webhook export.ready, o consultas GET /v3/exports/{id} hasta que status sea ready, y luego descargas GET /v3/exports/{id}/file. La exportación también trae rows y el sha256 del archivo.

Los archivos se guardan 7 días (después, 410 export_expired). Puede haber hasta 3 exportaciones en curso a la vez (429 too_many_exports). Pro y Business.

GET /v3/stats/summary da shown, granted, denied, left, reused y withdrawn para los días UTC de from a to (2026-10-31, ambos incluidos; por defecto los últimos 30 días, como máximo 366 días, y hasta donde tu plan muestra el registro). Añade link para un solo enlace. GET /v3/stats/daily da las mismas cifras día a día y, en Pro y Business, por país con by=country. Los bots nunca se cuentan.

GET /v3/usage muestra los consentimientos de este periodo, tu limit, lo que queda (remaining) y el inicio y el fin del periodo.

La API, los webhooks y la página de consentimiento en siete idiomas están en todos los planes. Los planes se diferencian en los consentimientos al mes, hasta dónde se muestra el registro hacia atrás, el ritmo de peticiones y las funciones extra. Precios en euros, sin IVA.

Solo cuentan las aceptaciones nuevas: los rechazos, las visitas repetidas con «No volver a preguntar», y los bots no. Al 80 % y al 100 % del límite recibes un correo y el webhook usage.warning.

Una vez agotado el límite, los enlaces reales nuevos se rechazan con 402 limit_reached. Todo lo demás sigue funcionando: los enlaces existentes siguen preguntando y registrando, los webhooks y los tokens llegan como siempre y no se oculta nada. La creación de enlaces se reabre al empezar el periodo siguiente (en Free el día 1 del mes, en los planes de pago el día del pago) o justo después de subir de plan.

Por cuenta, con todas las claves juntas: 60 por minuto en Free, 300 en Pro, 1.000 en Business. Por encima, la respuesta es 429 rate_limited con una cabecera Retry-After; las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining muestran dónde estás. Algunos métodos tienen además su propio límite: PDF de prueba 20 por minuto, exportaciones nuevas 10, descargas de exportaciones 30.

Siempre con la misma forma: el estado HTTP y un cuerpo JSON con un code estable y un message en inglés. Actúa según el code; el mensaje puede cambiar de redacción. Los campos no válidos dan 422 validation_failed con fields: cada campo con sus problemas.

Crea una clave nueva en «Conectar por API», cambia tu servidor a ella y luego revoca la antigua: deja de funcionar al instante. Revocar una clave no afecta a tus enlaces, al registro ni a los webhooks.

Guarda las claves en las variables de entorno de tu servidor, nunca en un navegador, una app móvil o un repositorio público. Si puede haberse filtrado el secreto de un webhook, desactiva ese webhook en el panel y crea uno nuevo.