Comenzar · 01

Documentación de CASANDRA

Guía para comprender el alcance, elegir un enfoque de integración y revisar los contratos técnicos necesarios para conectar CASANDRA.

Ilustración de privacidad y documentación técnica de CASANDRA

Qué es CASANDRA

CASANDRA gestiona privacidad de punta a punta conectando actividades de tratamiento, consentimiento, derechos, comunicación y evidencia dentro de una operación trazable.

Principio de producto. Transparencia, control y trazabilidad se traducen en confianza cuando cada decisión puede comprenderse y cada operación puede demostrarse.

Cómo recorrer la documentación

01 · DecidirWidget embebido o API directa.

→

02 · CompararExperiencia y responsabilidades.

→

03 · IntegrarIdentidad, interfaz y contratos.

→

04 · ValidarSeguridad, pruebas y producción.

Cómo elegir el enfoque

La página Resumen permite comparar los enfoques disponibles antes de revisar el detalle técnico del Widget o de la API directa.

Estado de la documentación

La documentación distingue entre comportamiento definido de producto, implementación disponible en DEV, contratos preliminares y decisiones técnicas pendientes. Esa diferencia se identifica en cada página.

Comenzar · 02

Arquitectura de CASANDRA

Vista de los componentes que participan en la operación y de las relaciones necesarias para integrar CASANDRA sin exponer detalles internos de infraestructura que no forman parte del contrato con el integrador.

Vista general

Canal cliente
Web · App · WiFi

Widget CASANDRA
Consentimiento contextual

Portal Titular
Gestión posterior

↓ ↓ ↓

CASANDRA · gestión, trazabilidad y evidencia

RAT / AT

Finalidades

Consentimientos

Solicitudes ARSOP

Notificaciones

Estados

Evidencia

Auditoría

↓

Operación de la organización

Las Finalidades y las respuestas ARSOP se interpretan en relación con las versiones correspondientes de las Actividades de Tratamiento declaradas en el RAT.

Arquitectura de integración

Implementación disponible en DEV. El canal puede cargar el Widget JavaScript de CASANDRA o implementar directamente las cuatro rutas públicas. Ambos enfoques escriben el mismo tipo de evidencia; cambia quién construye la interfaz y quién responde por la identidad y el contexto capturado.

CanalIdentifica el punto de consentimiento.

→

Widget o APIObtiene textos y captura decisiones.

→

InteracciónResuelve al titular y registra contexto.

→

EvidenciaConserva versión, acción y fecha.

Aislamiento

Definición de arquitectura. El modelo definido para aislamiento es instancia dedicada single-tenant por cliente, sin almacenamiento ni entorno compartido entre organizaciones. La formalización de despliegue por ambiente se documentará cuando corresponda.

Comenzar · 03

Ambientes & autenticación

Ambientes, valores de integración y controles vigentes para implementar y probar el flujo público de consentimiento.

Ilustración de ambientes y autenticación de CASANDRA

Ambiente DEV

Recurso	Disponibilidad actual
Dashboard	`https://casandra-dev.elunlabs.io`
CASANDRA API	`https://casandrabackend-dev.elunlabs.io`
Widget	`https://casandra-dev.elunlabs.io/widget/consent-widget.js`

Implementación actual. Estas URLs corresponden al ambiente DEV y se documentan como referencia de integración. No representan todavía una convención de dominios para producción.

Valores entregados por CASANDRA

Valor	Uso	Tratamiento
`codigo_importacion` `wid_…`	Identifica el Widget en las cuatro rutas públicas y se usa como `widgetId`.	Es público e impredecible; no debe tratarse como autorización.
`widget_id`	Identificador UUID para rutas administrativas del Dashboard.	No se utiliza en el flujo público del cliente.
`secret_integracion` `sec_…`	Reservado para autenticación servidor a servidor.	Se muestra una sola vez; CASANDRA conserva su SHA-256. Guardar en un gestor de secretos.

Autenticación del flujo público

Estado actual del contrato. Las cuatro rutas públicas no requieren cabecera Authorization ni validan actualmente secret_integracion. En navegador, la protección aplicable es la lista de dominios autorizados y la validación de Origin/Referer. En servidor a servidor, el cliente debe proteger su propio endpoint intermedio.

Prerrequisitos de ambiente

Campaña en estado PUBLICADA y dentro de su ventana de fechas.
Widget activo.
Host del canal registrado en dominios autorizados cuando la llamada se origine en navegador.
Catálogo de tipos de identificador cargado en el ambiente.
Base URL y codigo_importacion externalizados por ambiente.

Prueba de humo · DEV

curl -s https://casandrabackend-dev.elunlabs.io/api/v1/public/widgets/wid_TU_CODIGO

Fundamentos · 01

RAT · Actividades de Tratamiento

Registro declarativo por organización de las Actividades de Tratamiento. En CASANDRA es una entidad versionada que relaciona finalidades, bases de licitud y evidencia con la operación posterior.

Definición y alcance

El RAT corresponde al Registro de Actividades de Tratamiento exigido por el Art. 14 ter de la Ley 21.719. Cada edición de una Actividad de Tratamiento genera una nueva versión y conserva la anterior como histórico inmutable.

Regla de versionado. Archivar una Actividad de Tratamiento genera una nueva versión vN+1 con estado Archivada. El estado no se modifica in place, preservando la cadena de evidencia.

Alcance. El RAT declara finalidad y base de licitud. No reemplaza el mapeo físico de flujos de datos dentro de los sistemas del cliente; esa capa es complementaria.

Atributos de una Actividad de Tratamiento

Atributo	Tipo / regla
`id_actividad`	UUID
`organización`	FK
`versión`	Integer correlativo
`finalidad`	Referencia única
`base_licitud`	Enum
`atributos_datos`	Lista: personal / sensible / biométrico / económico / adolescente / niño
`categoría_titulares`	String
`destinatarios`	Lista de cesionarios
`plazo_conservación`	Duración
`transferencia_internacional`	Boolean + detalle
`decisiones_automatizadas`	Boolean + detalle
`estado`	Activa / Archivada
`hash_registro`	SHA-256
`hash_anterior`	SHA-256, referencia

Relación con Finalidad

La cardinalidad RAT (AT) — Finalidad es muchos a uno: cada Actividad de Tratamiento declara una finalidad específica y una finalidad puede estar asociada a varias Actividades de Tratamiento con distintas bases de licitud o formas de tratamiento.

Ciclo de vida

Creaciónv1 · Activa.

→

EdiciónvN+1 · histórico inmutable.

→

ArchivovN+1 · estado Archivada.

Brechas de cumplimiento

Una finalidad activa en operación sin Actividad de Tratamiento declarada, o una Actividad de Tratamiento sin consentimientos de respaldo cuando corresponda, se registra como Brecha de Cumplimiento.

DetectadaBrecha registrada.

→

AsignadaResponsable definido.

→

RegularizaciónAcciones en curso.

→

ResueltaCierre con evidencia.

Endpoints

Contrato preliminar. Los siguientes endpoints forman parte de la definición técnica y no están confirmados en producción.

Método	Ruta	Resultado
POST	`/v1/rat/activities`	201 · AT versión 1, estado Activa
PUT	`/v1/rat/activities/{id}`	201 · nueva versión vN+1
PATCH	`/v1/rat/activities/{id}/archive`	Nueva versión en estado Archivada
GET	`/v1/compliance/gaps`	Brechas y ciclo de vida

El PUT devuelve 201 porque cada edición se registra como un evento nuevo append-only y no como una mutación del registro existente.

Fundamentos · 02

Modelo de datos

Entidades y reglas transversales utilizadas para relacionar tratamiento, decisiones, solicitudes, comunicaciones y evidencia dentro de CASANDRA.

Entidades base

Titular

↓

Consentimiento

Solicitud ARSOP

Notificación

RAT / AT

Finalidad

Categoría de datos

Evidencia

Decisión

Estado

Política

Transición de Estado

Entidades presentes en la implementación DEV

La implementación entregada permite reconocer organizaciones, usuarios, finalidades, campañas, widgets, titulares, identificadores, interacciones, consentimientos, solicitudes y auditoría. Este listado describe la implementación actual y no sustituye el modelo de datos contractual.

Inmutabilidad y cadena de hashes

hash_registro corresponde al SHA-256 del contenido canónico del registro, serializado de forma determinística y calculado una sola vez al insertar. hash_anterior referencia el hash_registro del registro insertado inmediatamente antes en la misma tabla.

La cadena se mantiene por tabla completa, no por titular ni por expediente.
Aplica a Consentimiento, Notificación, RAT y Transición de Estado.
El primer registro de cada tabla usa un valor génesis sin hash_anterior.
La evidencia se interpreta bajo la versión de política, finalidad y Actividad de Tratamiento vigente al momento del evento, no bajo la versión actual.

Categorías de datos

Categoría	Nivel
Dato personal	base
Dato personal sensible	sensible
Dato de salud / perfil biológico	especial
Dato biométrico	especial
Dato de geolocalización	especial
Dato financiero / económico	especial
Dato de niño o niña	especial
Dato de adolescente	especial

Capacidades · 01

Consentimiento contextual

Presenta una solicitud contextual, permite una decisión granular por finalidad y conserva el resultado con su contexto y evidencia.

ActivaciónEl Widget aparece en el canal.

→

ComprensiónLa persona revisa finalidades.

→

DecisiónAcepta, rechaza o configura.

→

RegistroCASANDRA conserva la evidencia.

Las finalidades configurables derivan de las Actividades de Tratamiento declaradas en el RAT y referencian la versión específica de la Actividad de Tratamiento bajo la que ocurre la decisión.

La taxonomía base de CASANDRA considera las siguientes finalidades bajo consentimiento:

#	Finalidad
01	Comunicaciones comerciales y marketing
02	Personalización de productos o servicios
03	Análisis estadístico o investigación
04	Prestación y mejora del servicio
05	Contacto y atención al cliente
06	Cesión o transferencia a terceros
07	Elaboración de perfiles y decisiones automatizadas

Implementación actual. El ambiente DEV utiliza temporalmente un catálogo reducido de categorías técnicas para el desplegable. Esos valores son placeholders de implementación y no reemplazan la taxonomía oficial de CASANDRA.

CASANDRA ofrece dos vías que producen el mismo tipo de evidencia: Widget embebido, con interfaz provista por CASANDRA, y API directa, para interfaces propias, aplicaciones no web y procesos servidor a servidor.

El registro de la decisión conserva el contexto necesario para reconstruir quién decidió, cuándo, bajo qué finalidad y bajo qué versión de tratamiento ocurrió la interacción.

Capacidades · 02

Portal Titular

Capa de gestión posterior para que la persona revise consentimientos, consulte historial y continúe acciones vinculadas al ejercicio de sus derechos.

Alcance

Acceso e identificación del titular.
Consulta de consentimientos.
Modificación o revocación.
Ingreso y seguimiento de solicitudes ARSOP.
Portabilidad, notificaciones, perfil y accesibilidad según alcance del producto.

Flujo

AccesoIngreso al Portal.

→

IdentificaciónReconocimiento del titular.

→

GestiónConsentimientos y derechos.

→

HistorialTrazabilidad posterior.

Implementación DEV. El flujo entregado identifica actualmente al titular mediante email para acceder a consentimientos e historial. Esta implementación utiliza una sesión separada de la sesión de operación de la organización.

Capacidades · 03

Gestión de derechos ARSOP

Gestiona el ingreso, seguimiento, plazos, resolución y evidencia de las solicitudes asociadas al ejercicio de derechos del titular.

Derechos considerados

Derecho	Uso en CASANDRA	Bloqueo accesorio
Acceso	Solicitud de información asociada al titular.	—
Rectificación	Corrección de datos.	Disponible
Supresión	Eliminación según corresponda.	Disponible
Oposición	Oposición a un tratamiento.	Disponible
Portabilidad	Entrega o traslado de datos cuando corresponda.	—

Cómputo de plazo

Situación	Plazo
Solicitud ARSOP estándar	30 días corridos
Bloqueo accesorio	2 días hábiles

Ciclo de la solicitud

IngresoSolicitud registrada.

→

ValidaciónInformación e identidad.

→

GestiónProcesamiento y plazo.

→

ResoluciónCierre con evidencia.

Al cerrar una resolución se publica el evento correspondiente hacia Notificaciones para gestionar la comunicación y su evidencia.

Implementación DEV. El catálogo técnico actual contempla estados equivalentes a recibida, en revisión, requiere antecedentes, aprobada, rechazada y completada. Estos nombres describen la implementación entregada y deben validarse antes de fijarlos como contrato de producto.

Capacidades · 04

Notificaciones

Gestiona las comunicaciones que CASANDRA debe emitir a partir de eventos del producto y conserva evidencia de contenido, envío, entrega y escalamiento.

Notificaciones ≠ Eventos. Eventos corresponde al mecanismo técnico de integración hacia sistemas del cliente. Notificaciones corresponde a la comunicación al titular, DPO, cesionarios o Agencia y a la evidencia de esa comunicación. Revisar Eventos.

Arquitectura event-driven

Notificaciones consume eventos generados por otras capacidades de CASANDRA. No requiere una invocación directa de usuario para iniciar el proceso.

Evento conocido	Origen
`arsop.resuelta`	ARSOP al cerrar resolución
`arsop.bloqueo.disparado`	ARSOP · bloqueo Art. 8° ter
`arsop.resolución_positiva`	Rectificación / supresión hacia cesionarios
`politica.clasificada_sustancial`	Consentimiento · re-consentimiento

Contrato mínimo del evento

Todo productor debe emitir al menos tipoEvento, idEntidadOrigen, timestamp de emisión, destinatarios resueltos según la matriz de SLA y el payload mínimo exigido para ese tipo de evento.

Matriz de SLA

Evento	Destinatario	Canal	SLA	Contenido mínimo
Resolución de bloqueo	Titular	Email / domicilio físico	2 días hábiles	Decisión, fundamento y, si hay denegación, plazo de 30 días hábiles para reclamar ante la Agencia.
Resolución de bloqueo · aviso interno	DPO / Legal	Email	Junto a respuesta al titular	Aviso de que debe notificarse a la Agencia si existe rechazo.
Respuesta a solicitud ARSOP	Titular	Email / domicilio físico	30 días corridos	Resolución completa, fundamento de denegación, plazo y vía de reclamación.
Prórroga de solicitud ARSOP	Titular	Email / domicilio físico	Antes del vencimiento original	Notificación de prórroga y nuevo plazo.
Aviso a cesionarios	Cesionarios	Email	Junto a resolución al titular	Resolución positiva y finalidades afectadas.
Alerta de vencimiento	DPO / Legal	Plataforma + Email	Configurable, p.ej. 72h / 24h	ID de solicitud, días restantes, responsable y acción requerida.
Nueva solicitud ARSOP	DPO / Legal / Titular	Plataforma + Email	Inmediato	Tipo de derecho, canal, identidad verificada y timestamp.
Cambio de política	Titular	Email / canal original	Configurable	Descripción del cambio, finalidades afectadas y acción requerida.

Entidad Notificación

Atributo	Definición
`id_notificación`	UUID
`evento_disparador`	Referencia a Consentimiento / Expediente / Política
`destinatario`	Titular / DPO / Cesionario / Agencia
`canal`	Email / domicilio físico / plataforma
`contenido_íntegro`	Snapshot renderizado
`sla_aplicable`	SLA asociado
`nivel_certeza_entrega`	Remitido / Entregado / Leído
`estado`	Estado de ciclo de vida
`timestamp_envío`	Timestamp
`timestamp_confirmación`	Timestamp
`hash_registro`	SHA-256
`hash_anterior`	SHA-256

Estados

PendienteCreada.

→

En colaEsperando envío.

→

EnviadaDespachada.

→

EntregadaConfirmación disponible.

Los estados de falla continúan de forma append-only: falla de entrega → reintento → escalada a DPO → cierre con evidencia.

Contenido íntegro

Regla de evidencia. La notificación debe conservar el contenido completo de la resolución enviada. Un enlace al portal no reemplaza el contenido exigido. Se persiste el snapshot final renderizado tal como se envió y no una referencia mutable a plantilla + variables.

Excepción de minimización

Tratamiento diferenciado. Notificación almacena contenido íntegro con datos personales cuando ese contenido constituye la evidencia exigida. Ese repositorio requiere cifrado en reposo reforzado, acceso restringido y una política de retención propia.

Endpoints

Contrato preliminar. Las rutas siguientes forman parte de la definición técnica y no están confirmadas en producción.

Método	Ruta	Uso
GET	`/v1/notifications/{expedienteId}`	Snapshot íntegro
GET	`/v1/notifications?tipo=bloqueo`	Notificaciones críticas
GET	`/v1/notifications/alerts`	Alertas internas
POST	`/v1/notifications/cesionarios`	Comunicación a cesionarios
POST	`/v1/notifications/delivery-callback`	Estado de entrega del proveedor
GET	`/v1/notifications/reports`	Reporte de trazabilidad

Integración · 01

Resumen

Comparación general de los enfoques disponibles para integrar el consentimiento CASANDRA en los canales digitales de una organización.

Cómo usar esta página. Selecciona el enfoque que mejor se ajuste al canal, la experiencia requerida y las responsabilidades que asumirá el equipo cliente.

1. Elegir el enfoque

Widget embebido

CASANDRA provee modal, estilos, verificación previa y orquestación del registro.

Recomendado para canales web.
Menor desarrollo y mantenimiento.
La evidencia conserva contexto del navegador.
Requiere integrar el script, la identidad y el disparador.

API directa

El cliente construye la interfaz y ejecuta cuatro llamadas públicas.

Útil para UX propia, apps nativas o canales no web.
Permite integrar el consentimiento dentro de un flujo existente.
El cliente responde por el texto mostrado, identidad, reintentos y contexto.
Mayor esfuerzo de desarrollo, QA y seguridad.

Criterio	Widget	API directa
Interfaz	Provista por CASANDRA.	Diseñada y desarrollada por el cliente.
Textos y orden	Se obtienen en cada apertura.	El cliente debe consultar y renderizar la configuración vigente.
Verificación previa	Automática.	El cliente implementa `verificar-titular`.
Contexto de evidencia	IP, user-agent y dominio del navegador.	Corresponde al origen de la llamada; si se usa backend, será el servidor.
Responsabilidad principal	Integración del canal e identidad.	UX, texto mostrado, identidad, orquestación, reintentos y observabilidad.

Integración · 02

Widget de consentimiento

La vía de menor esfuerzo para incorporar la experiencia CASANDRA en un canal web, conservando el contexto del navegador y delegando la orquestación del flujo.

Implementado en DEV. El Widget se distribuye como un bundle JavaScript, provee su propio modal y estilos, consulta los textos vigentes en cada apertura y se inicializa con window.CassandraConsent.open().

Ejemplo · ambiente DEV

<script src="https://casandra-dev.elunlabs.io/widget/consent-widget.js" defer></script>

<button id="casandra-consent">Gestionar mis consentimientos</button>

<script>
  document.getElementById("casandra-consent")
    .addEventListener("click", function () {
      window.CassandraConsent.open({
        widgetId: "wid_TU_CODIGO",
        apiBaseUrl: "https://casandrabackend-dev.elunlabs.io",
        userName: "Nombre del titular",
        userIdentifiers: [
          { tipo: "EXTERNAL_ID", valor: "cli-90210" },
          { tipo: "EMAIL", valor: "titular@ejemplo.com" }
        ]
      });
    });
</script>

El botón es del canal cliente. CASANDRA aporta el modal; la organización define dónde y cuándo se dispara, y obtiene los identificadores desde una fuente confiable.

Parámetro	Uso	Consideración técnica
`widgetId`	Recibe el `codigo_importacion` con prefijo `wid_`.	Debe externalizarse y cambiar por ambiente.
`apiBaseUrl`	URL base de CASANDRA API.	No dejar fija en el código; configurar DEV y producción.
`userName`	Nombre del titular cuando está disponible.	Se almacena solo si el titular aún no tiene nombre.
`userIdentifiers`	Uno o más identificadores de la misma persona.	Requiere definir fuente, confiabilidad y momento de disponibilidad.

1 · VerificarDecide si corresponde volver a preguntar.

→

2 · ConfigurarObtiene campaña y textos vigentes.

→

3 · PresentarAbre el modal sin preselecciones.

→

4 · RegistrarCrea la interacción y envía todas las decisiones.

Si el titular ya respondió la versión vigente, no muestra el modal.
Si la verificación falla por red, timeout o 500, aplica falla abierta y muestra el consentimiento.
La interacción se crea solo cuando el titular confirma. Cerrar u omitir no crea registro.
Una decisión desmarcada se registra como DENEGAR; ninguna opción parte seleccionada.
Si cambia la versión del texto o vence su duracion_dias, la verificación vuelve a solicitar respuesta.

Código	Normalización en CASANDRA	Uso recomendado
`EMAIL`	Espacios recortados, minúsculas y validación básica.	Identificación y contacto.
`TELEFONO`	Formato E.164; sin prefijo se asume Chile `+56`.	Identificación y contacto.
`RUT`	Sin puntos ni guion, K mayúscula y dígito verificador válido.	Identificador nacional.
`EXTERNAL_ID`	Recorte de espacios.	ID estable del sistema cliente; ideal junto al email.

Todos deben pertenecer a la misma persona. Si dos identificadores ya están asociados a titulares distintos, CASANDRA rechaza la operación con 409 IDENTITY_CONFLICT. Si el Widget exige contacto, debe incluirse al menos un EMAIL o TELEFONO.

Definir el punto de activación y el comportamiento del canal cuando el modal no se muestra.
Cargar el bundle bajo la política CSP del sitio y registrar los dominios definitivos.
Obtener los identificadores desde la sesión o una fuente confiable.
Externalizar bundle URL, apiBaseUrl y widgetId por ambiente.
Validar accesibilidad, responsive, navegadores soportados y convivencia con otros modales.
Implementar telemetría del disparador y monitoreo de errores visibles en el canal.
Probar re-consentimiento, denegación, cierre sin responder y evidencia en CASANDRA.

Para comparar este enfoque con la API directa, revisa el Resumen.

Cada ambiente tiene su propia campaña, codigo_importacion, bundle y base URL. Antes de desplegar, registrar todos los hosts —incluyendo variantes con y sin www— y verificar que la evidencia conserve el dominio, IP y user-agent esperados.

Integración · 03

API pública de consentimiento

Contrato implementado en DEV para construir una experiencia propia y registrar el mismo tipo de evidencia que genera el Widget embebido.

Responsabilidad del cliente. Con API directa, CASANDRA registra la versión respondida pero no puede comprobar qué se mostró en pantalla. La interfaz debe renderizar, sin editar, titulo, descripcion y texto_completo obtenidos de la configuración vigente.

Flujo completo

1 · Verificar¿Debe responder el titular?

→

2 · ConfiguraciónObtener textos e IDs vigentes.

→

3 · InterfazPresentar y capturar decisiones.

→

4–5 · RegistrarCrear interacción y enviar respuestas.

Los pasos 4 y 5 van juntos. Solo se ejecutan cuando el titular confirma. Si sale sin responder, no se crea interacción ni queda registro. Cada interacción admite un único conjunto de decisiones.

Convenciones

Aspecto	Contrato DEV
Base URL	`https://casandrabackend-dev.elunlabs.io`
Prefijo	`/api/v1/public`
Autenticación	Sin `Authorization`; `codigo_importacion` en la ruta.
Cuerpo	JSON UTF-8; `POST` con `Content-Type: application/json`.
Fechas	ISO 8601 con offset UTC.
CORS	Abierto (`*`); las rutas pueden llamarse desde navegador.
Dominio	Compara host de `Origin` o `Referer` con la lista autorizada.
Rate limit	No se aplica actualmente; un proxy del cliente debe incorporar su propio límite.
Campos desconocidos	Se ignoran; los obligatorios se validan.

La validación de dominio no ocurre si el Widget no tiene dominios configurados o la petición no envía Origin ni Referer, como suele ocurrir en servidor a servidor.

Endpoints públicos

GET

/api/v1/public/widgets/{codigo_importacion}Configuración y textos vigentes de la campaña.

POST

/api/v1/public/widgets/{codigo_importacion}/verificar-titularIndica si corresponde solicitar una respuesta.

POST

/api/v1/public/widgets/{codigo_importacion}/interaccionesResuelve o crea al titular y abre el contenedor de evidencia.

POST

/api/v1/public/interacciones/{interaccion_id}/respuestasRegistra las decisiones y completa la interacción.

1. Obtener configuración

GET · configuración pública

curl -s \
  https://casandrabackend-dev.elunlabs.io/api/v1/public/widgets/wid_TU_CODIGO

200 · respuesta

{
  "codigo_importacion": "wid_TU_CODIGO",
  "campania": {
    "nombre": "Consentimientos de datos personales",
    "descripcion": "Elige cómo quieres que usemos tus datos."
  },
  "consentimientos": [{
    "campania_consentimiento_id": "3f1c9b0e-2d4a-4f7b-9a1e-8c5d6e7f0a1b",
    "consentimiento_version_id": "b7e2d1a4-5c6f-4839-9d0e-1f2a3b4c5d6e",
    "icono": "megaphone",
    "titulo": "Comunicaciones comerciales",
    "descripcion": "Para enviarte ofertas y novedades por email.",
    "tooltip_titulo": "¿Qué implica?",
    "tooltip_descripcion": "Puedes revocarlo cuando quieras.",
    "texto_completo": "Autorizo el tratamiento de mis datos…",
    "duracion_dias": 365,
    "requiere_respuesta": true,
    "orden": 1
  }]
}

Ordenar por orden ascendente, no por la posición del arreglo.
Usar campania_consentimiento_id al enviar la decisión.
consentimiento_version_id identifica la versión exacta del texto y queda referenciada en la evidencia.
Puede cachearse por minutos, pero no debe persistirse ni copiarse dentro del código.

2. Verificar titular

Es una operación de solo lectura: no crea titular, identificador ni interacción. Puede omitirse si todavía no existe ningún identificador.

POST · verificar-titular

curl -X POST \
  https://casandrabackend-dev.elunlabs.io/api/v1/public/widgets/wid_TU_CODIGO/verificar-titular \
  -H 'Content-Type: application/json' \
  -d '{
    "identificadores": [
      { "tipo": "EMAIL", "valor": "juan@ejemplo.cl" },
      { "tipo": "RUT", "valor": "12.345.678-5" }
    ]
  }'

200 · respuesta

{
  "debe_responder": false,
  "motivo": "YA_RESPONDIO",
  "consentimientos_requeridos": 2,
  "consentimientos_pendientes": 0,
  "vigente_hasta": "2026-12-14T18:30:00+00:00"
}

motivo	¿Mostrar?	Interpretación
`TITULAR_NO_ENCONTRADO`	Sí	Primera respuesta en la empresa.
`RESPUESTA_PENDIENTE`	Sí	Falta una respuesta o cambió la versión del texto.
`RESPUESTA_EXPIRADA`	Sí	Venció, fue revocada o expirada.
`YA_RESPONDIO`	No	Todos los obligatorios están respondidos y vigentes.
`SIN_CONSENTIMIENTOS_REQUERIDOS`	Sí	La campaña solo contiene opciones no obligatorias.

Falla abierta. Ante red caída, timeout o 500, continuar y mostrar. Los 403 y 409 asociados al Widget o campaña también impedirán obtener la configuración y deben tratarse como errores de configuración.

3. Construir la interfaz

Regla	Comportamiento requerido
Estado inicial	Todas las opciones desmarcadas; nunca preseleccionar.
Contenido	Mostrar `titulo` y `descripcion`; hacer accesible `texto_completo`.
Detalle	Presentar tooltip cuando sus campos tengan valor.
Salir sin responder	Debe permitirse; no llamar a la API ni crear interacción.
`requiere_respuesta`	Exige incluir `OTORGAR` o `DENEGAR`; no obliga a otorgar.
Seleccionar todos	Puede ofrecerse como atajo, manteniendo decisión granular.

4. Crear interacción

POST · interacciones

curl -X POST \
  https://casandrabackend-dev.elunlabs.io/api/v1/public/widgets/wid_TU_CODIGO/interacciones \
  -H 'Content-Type: application/json' \
  -d '{
    "nombre": "Juan Pérez",
    "identificadores": [
      { "tipo": "EXTERNAL_ID", "valor": "cli-90210" },
      { "tipo": "EMAIL", "valor": "juan@ejemplo.cl" }
    ]
  }'

201 · respuesta

{
  "interaccion_id": "9c3a7f21-5b6d-4e08-a1c2-3d4e5f6a7b89",
  "titular_id": "1a2b3c4d-5e6f-4708-9a0b-1c2d3e4f5a6b",
  "estado": "ABIERTA",
  "expira_at": "2026-08-21T14:05:00+00:00"
}

La API normaliza los identificadores, busca al titular por hash y lo reutiliza si existe. Los identificadores nuevos se asocian al titular resuelto; si apuntan a personas distintas, la operación se rechaza. La interacción expira a las 72 horas.

Contexto registrado	Origen
`dominio_origen`	Host de `Origin` o `Referer`.
`ip_address`	Primer valor válido de `X-Forwarded-For` o IP de conexión.
`user_agent`	Cabecera `User-Agent`.

Origen de la evidencia. Si la llamada se realiza desde un backend, el contexto será el del servidor y no el dispositivo del titular. Esta decisión debe evaluarse según el riesgo y la fuerza probatoria requerida.

5. Registrar decisiones

POST · respuestas

curl -X POST \
  https://casandrabackend-dev.elunlabs.io/api/v1/public/interacciones/9c3a7f21-5b6d-4e08-a1c2-3d4e5f6a7b89/respuestas \
  -H 'Content-Type: application/json' \
  -d '{
    "decisiones": [
      { "campania_consentimiento_id": "3f1c9b0e-2d4a-4f7b-9a1e-8c5d6e7f0a1b", "accion": "OTORGAR" },
      { "campania_consentimiento_id": "7d2e8a1f-aaaa-4bbb-8ccc-123456789012", "accion": "DENEGAR" }
    ]
  }'

200 · respuesta

{
  "interaccion_id": "9c3a7f21-5b6d-4e08-a1c2-3d4e5f6a7b89",
  "estado": "COMPLETADA",
  "resultados": [{
    "consentimiento_id": "c0ffee00-1111-4222-8333-444455556666",
    "accion": "OTORGAR",
    "ocurrido_at": "2026-08-18T14:05:03+00:00"
  }]
}

Enviar siempre todos. Recorrer toda la configuración: marcado → OTORGAR; desmarcado → DENEGAR. Así se incluye cada obligatorio y queda evidencia explícita del rechazo.

resultados[].consentimiento_id identifica la finalidad visible en el Portal Titular; no es el campania_consentimiento_id enviado ni el consentimiento_version_id.

Identificadores y resolución del titular

Tipo	Normalización	Ejemplo
`EMAIL`	Trim, minúsculas y validación de estructura.	`Juan@Ejemplo.CL` → `juan@ejemplo.cl`
`TELEFONO`	E.164; asume `+56` sin prefijo.	`9 1234 5678` → `+56912345678`
`RUT`	Sin puntos/guion, K mayúscula y módulo 11.	`12.345.678-5` → `123456785`
`EXTERNAL_ID`	Trim; no puede quedar vacío.	`cli-90210` → `cli-90210`

El valor normalizado se transforma con HMAC-SHA256 con alcance por empresa y tipo.
El valor se almacena cifrado con AES-GCM y no se devuelve en la API pública.
Basta un identificador coincidente para reutilizar al titular y agregar los restantes.
Se recomienda un EXTERNAL_ID estable junto al email para mantener continuidad si este cambia.

Estados y acciones

Objeto	Valores	Regla
Interacción	`ABIERTA`, `COMPLETADA`, `ABANDONADA`, `EXPIRADA`	Solo `ABIERTA` recibe respuestas.
Acción del flujo	`OTORGAR`, `DENEGAR`	Ambas cuentan como respuesta vigente.
Otras acciones	`RENOVAR`, `REVOCAR`, `EXPIRAR`	Corresponden a otros orígenes, como el Portal Titular.

Los eventos creados mediante estas rutas quedan con origen WIDGET, tanto si la llamada proviene del bundle como de una interfaz desarrollada por el cliente.

Idempotencia y reintentos

Llamada	¿Reintentar?	Comportamiento
Configuración	Sí	Solo lectura.
Verificar titular	Sí	Solo lectura; falla abierta.
Crear interacción	Con cuidado	Cada llamada crea otra interacción abierta.
Registrar respuestas	Sí, con el mismo payload	Devuelve `200` sin duplicar; payload distinto retorna `409`.

Antes del paso 5, conservar temporalmente interaccion_id y decisiones para poder reintentar durante las 72 horas. Una interacción abierta sin respuestas no constituye evidencia de consentimiento.

Vigencia y re-consentimiento

Un consentimiento requerido vuelve a quedar pendiente si nunca se respondió esa versión, la última acción fue REVOCAR/EXPIRAR, cambió el consentimiento_version_id o transcurrió duracion_dias. Con valor null, la respuesta no vence por tiempo.

Frecuencia recomendada. Ejecutar la verificación en cada punto donde podría mostrarse el consentimiento. vigente_hasta puede reducir llamadas, pero una nueva versión del texto solo se detecta consultando CASANDRA.

Formato de error

Error estándar

{
  "error": {
    "code": "DOMAIN_NOT_ALLOWED",
    "message": "El dominio de origen no está autorizado",
    "details": { "origen": "sitio-no-autorizado.cl" }
  }
}

Programar contra error.code, que es estable. message puede cambiar de redacción y details depende del caso.

Integración · 04

Eventos

Mecanismo técnico para propagar cambios relevantes de CASANDRA hacia otras capacidades o sistemas del cliente.

Eventos ≠ Notificaciones. Eventos describe el bus, webhook o mecanismo máquina-a-máquina. Notificaciones gestiona la comunicación a destinatarios y su evidencia.

Eventos definidos

Evento	Uso
`arsop.resuelta`	Inicia comunicación de resolución.
`arsop.bloqueo.disparado`	Activa la lógica de bloqueo y comunicación asociada.
`arsop.resolución_positiva`	Permite comunicar a cesionarios cuando corresponda.
`politica.clasificada_sustancial`	Inicia proceso de re-consentimiento.

Contrato mínimo

Todo productor debe emitir tipoEvento, idEntidadOrigen, timestamp de emisión, destinatarios resueltos y el payload mínimo requerido para el caso.

Privacidad que se puede operar.

Privacidad gestionada de extremo a extremo.

Consentimiento contextual

Portal Titular

Gestión ARSOP

Notificaciones

RAT · Actividades

API & Eventos

Diseñada para conectarse con el ecosistema digital de cada organización.

Cada operación debe poder comprenderse, gestionarse y demostrarse.

Documentación de CASANDRA

Qué es CASANDRA

Cómo recorrer la documentación

Cómo elegir el enfoque

Estado de la documentación

Arquitectura de CASANDRA

Vista general

Arquitectura de integración

Aislamiento

Ambientes & autenticación

Ambiente DEV

Valores entregados por CASANDRA

Autenticación del flujo público

Prerrequisitos de ambiente

RAT · Actividades de Tratamiento

Definición y alcance

Atributos de una Actividad de Tratamiento

Relación con Finalidad

Ciclo de vida

Brechas de cumplimiento

Endpoints

Modelo de datos

Entidades base

Entidades presentes en la implementación DEV

Inmutabilidad y cadena de hashes

Categorías de datos

Consentimiento contextual

Cómo funciona

Finalidades

Integración

Evidencia

Portal Titular

Alcance

Flujo

Gestión de derechos ARSOP

Derechos considerados

Cómputo de plazo

Ciclo de la solicitud

Notificaciones

Arquitectura event-driven

Contrato mínimo del evento

Matriz de SLA

Entidad Notificación

Estados

Contenido íntegro

Excepción de minimización

Endpoints

Resumen

1. Elegir el enfoque

Widget embebido

API directa

Widget de consentimiento

Quickstart

Parámetros de apertura

Qué ejecuta el Widget

Identificadores

Trabajo del equipo cliente

Promoción a producción

API pública de consentimiento

Flujo completo

Convenciones

Endpoints públicos

1. Obtener configuración

2. Verificar titular

3. Construir la interfaz

4. Crear interacción

5. Registrar decisiones

Identificadores y resolución del titular

Estados y acciones

Idempotencia y reintentos