Cláusulas de consentimiento y versionado

Crea un propósito, redacta su texto, publícalo y modifícalo después sin perder la prueba.

Un propósito es algo a lo que una persona puede decir que sí o que no: “envíame correo de marketing”, “mide cómo uso el sitio”. Tiene una key estable que usas en la API, una categoría y una base legal. Su redacción —la cláusula que lee la persona— se versiona por separado, para poder demostrar exactamente qué se mostró en cualquier fecha.

Ejemplo: consentir el envío de correo de marketing

1. Crea el propósito. En la consola, Purposes & statements → New purpose:

2. Redacta la cláusula. En el borrador, añade el texto que verá la persona, una entrada por idioma:

Título:  Emails de marketing
Cuerpo:  Te enviaremos novedades de producto, consejos y alguna oferta.
         Puedes darte de baja cuando quieras.
Link:    https://acme.com/privacidad#marketing   (opcional — tu política)

3. Publícala. Elige Display-only (es la primera versión, nadie ha consentido todavía). La redacción queda congelada como v1.

4. Registra el consentimiento contra ella desde tu aplicación:

curl -X POST $API/v1/consent \
  -H "authorization: Bearer sk_live_…" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"subject":"email:sam@example.com","purpose":"marketing_email",
       "state":"GRANTED","locale":"es","channel":"formulario_registro"}'

La bóveda guarda la decisión con el hash del texto exacto de la v1, la IP, la marca de tiempo y un justificante firmado. Si más tarde un regulador pregunta “¿a qué dio su consentimiento Sam en esta fecha?”, puedes mostrar las palabras exactas.

Por qué siempre hay un borrador

Publicar congela el borrador actual como una versión inmutable y abre un borrador nuevo con el mismo texto copiado. Así, un propósito siempre tiene una versión activa (lo que sirve GET /v1/purposes y lo que cita el consentimiento nuevo) y un borrador que puedes editar libremente. La consola muestra “al día” cuando el borrador coincide con la versión activa, es decir, cuando no hay nada nuevo que publicar.

Cambiar el texto después: ¿qué tipo de cambio es?

Al publicar una versión nueva eliges qué significa para quien ya respondió:

Añadir un idioma

1. Abre el propósito → Draft text → + locale.
2. Introduce el código de idioma (en, fr-CA, …) y el título y el cuerpo traducidos.
3. Publica como display-only.

Tu banner solicita entonces GET /v1/purposes?locale=en y muestra el texto en inglés. Si un idioma aún no está traducido, la API recurre al idioma por defecto del sitio.

Etiquetas de versión

Opcionalmente, etiqueta una versión con un número de versión (v1.0, 2.3) o una fecha (2024-05-01). Se muestra junto a la versión en todas partes y se incluye en GET /v1/purposes. Es útil cuando importas un historial de cláusulas existente de otro sistema y quieres conservar tu numeración original.

Forzar el idioma (opcional)

Actívalo en un propósito y toda escritura de consentimiento para él deberá enviar un locale para el que la versión publicada tenga texto; de lo contrario, la API devuelve 422. Úsalo cuando legalmente necesites registrar en qué idioma se mostró a la persona. Está desactivado por defecto; en ese caso, el locale se guarda solo como metadato.