Docs

Cómo funciona

Las cinco ideas en las que se apoya la API: sujeto, propósito, la bóveda, estado actual e idempotencia.

Con cinco conceptos basta para usar bien Tripticonsent. Todo en la API es uno de ellos.

Sujeto — la persona

Un sujeto es una persona. Nunca nos envías un nombre: lo referencias mediante un identificador que ya tiene en tu sistema:

email:sam@example.com
external_id:u_9241          (tu propio id de usuario)
phone:+34600111222
cookie_id:ck_a1b2           (una cookie propia, para visitantes anónimos)

Una persona puede tener varios identificadores: un cookie_id antes de registrarse y un email después. Puedes fusionarlos más tarde para que sus decisiones anteriores sigan asociadas (consulta la guía anónimo → identificado). Los valores de los identificadores se cifran en reposo; aun así podemos localizar a un sujeto sin descifrar nada, y una solicitud de borrado destruye la clave y deja a la persona sin posibilidad de ser localizada.

Propósito — aquello que se decide

Un propósito es una decisión de sí o no: marketing_email, analytics, personalization. Tiene una categoría y una base legal, y su redacción se versiona. Más detalle en Cláusulas de consentimiento.

La bóveda — un historial que solo crece

Cada decisión es una fila nueva que nunca se edita ni se borra. Retirar el consentimiento no borra el “concedido” anterior: añade una fila “retirado” que apunta a él. Así siempre puedes reconstruir exactamente a qué había dado su consentimiento una persona en cualquier momento del pasado, y eso es lo que lo hace válido como prueba.

2024-01-10  sam@example.com  marketing_email  GRANTED    (banner, v1)
2024-06-02  sam@example.com  marketing_email  WITHDRAWN  (centro de preferencias, v1)
2024-09-15  sam@example.com  marketing_email  GRANTED    (nuevo opt-in, v2)

Estado actual — la lectura rápida

Rara vez necesitas todo el historial: necesitas “¿puedo enviarle un correo a Sam ahora mismo?”. GET /v1/subjects/{ref}/consent te da solo el último estado por propósito, calculado a partir de la bóveda y cacheado. Es el endpoint que tu aplicación llama en cada carga de página.

EstadoSignificado
GRANTEDDijo que sí y sigue vigente.
DENIEDDijo que no.
WITHDRAWNDijo que sí y luego lo retiró.
EXPIREDUna política de caducidad lo invalidó; trátalo como “volver a preguntar”.
NOT_GIVENNunca se le ha preguntado. Los propósitos sin registro devuelven su estado por defecto.

Idempotencia — reintentos seguros

Las llamadas de red fallan y se reintentan. Envía una cabecera Idempotency-Key (cualquier cadena única, por ejemplo un UUID) en cada escritura. Si la misma clave llega dos veces con el mismo cuerpo, recibes de vuelta la respuesta original, sin fila duplicada. La misma clave con un cuerpo distinto se rechaza con 409, lo que detecta el error de haber reutilizado una clave sin querer.

curl -X POST $API/v1/consent \
  -H "authorization: Bearer sk_live_…" \
  -H "idempotency-key: 7c9e6a1b-4f2d-4a10-9c3e-1b2a3c4d5e6f" \
  -d '{"subject":"email:sam@example.com","purpose":"analytics","state":"GRANTED"}'
AnteriorPuesta en marcha