Conceptos

Qué son realmente una Session, una fila de Evidence y una cadena de auditoría, en las menos palabras posibles. Lea esto una vez y la referencia de la API tendrá sentido.

Organización

El tenant de nivel superior. Una organización corresponde a una cuenta de cliente. Todos los demás recursos (sesiones, pruebas, eventos de auditoría, usuarios) están limitados a una Org mediante seguridad a nivel de fila en las tablas subyacentes de Postgres. Un error en el código de la aplicación no puede cruzar tenants — la base de datos rechazará la consulta.

Una Org tiene: miembros (usuarios con acceso basado en roles), personalización de marca (logotipo / colores / pie de página del PDF), una suscripción de facturación, datos opcionales de entidad legal KYB, configuración opcional de SSO y una política de retención.

Miembro, Rol, Permiso

Un Membresía es la unión entre un User y una Org. Un usuario puede tener membresías en varias organizaciones y cambiar entre ellas (la organización activa viaja como una claim del JWT).

Cada Org siembra cuatro roles de sistema en su creación:

• org_admin — control total. Facturación, miembros, personalización de marca, retención.
• inspector — puede ejecutar inspecciones, capturar pruebas y firmar informes.
• observer — acceso de solo lectura a las sesiones y a los datos de auditoría.
• auditor — acceso de solo lectura más permiso de verificación de la cadena.

Los administradores de la organización pueden crear roles personalizados componiendo el catálogo de permisos. Los permisos se comprueban por slug en la capa de vista y se contrastan mediante RLS en la capa de base de datos.

Sesión

Una inspección. Es la unidad de facturación (usted paga por sesión cerrada) y la unidad de prueba (una cadena de auditoría es por sesión, no por organización).

Una sesión tiene: un operador (el miembro de su equipo que la inició), uno o varios participantes (el usuario de campo, más observadores opcionales), estado de consentimiento, posición GPS opcional, notas opcionales, una cadena de auditoría y —una vez cerrada— tokens de sello de tiempo anclados por TSA.

Participante

Una persona en una sesión. Hay un operador por sesión y al menos un usuario de campo; se admiten observadores adicionales opcionales. Los usuarios de campo se unen mediante una URL firmada de un solo uso (no se requiere cuenta); los operadores y observadores son miembros de la Org.

Pruebas

Una pieza de prueba capturada durante una sesión. Tipos:

• snapshot — foto fija de la cámara del usuario de campo.
• annotation — dibujo superpuesto sobre una instantánea o pizarra.
• whiteboard — lienzo de Excalidraw dentro de la sesión exportado como PNG + estado.
• clip — segmento de vídeo corto.
• document — archivo subido (usado por la capa de chat para PDF-para-firma).

Cada fila de Evidence tiene un SHA-256 de su contenido binario, almacenado en la cadena de auditoría. Manipular el archivo a posteriori hace que la verificación falle.

Cadena de auditoría

La columna vertebral criptográfica. Cada evento en una sesión — creación de la sesión, concesión de consentimiento, registro de GPS, captura de pruebas, anotación, guardado de pizarra, firma, fin de sesión — emite una fila AuditEvent con:

{
  "session": "<uuid>",
  "sequence": N,
  "occurred_at": "<iso8601>",
  "kind": "evidence.snapshot_added",
  "actor": { "user": <id|null>, "participant": <id|null> },
  "payload": { /* event-specific */ },
  "prev_hash": "<sha256 of previous event>",
  "hash": "<sha256 of canonical_json of this event>"
}

El primer evento usa prev_hash = "0" * 64 (génesis). Cada evento posterior usa el hash del evento anterior como prev_hash e incrementa sequence en 1. Un advisory lock de Postgres serializa las escrituras por sesión; un trigger append-only bloquea UPDATE + DELETE en la tabla.

TimestampToken (anclaje TSA)

Al finalizar la sesión (y al activar el «sellar ahora» por parte del operador), la cabeza actual de la cadena se envía a tres autoridades de sellado de tiempo independientes:

• YodaLedger — anclaje en la blockchain Tezos. Finalidad de ~15-20 minutos. Asíncrono; recibimos una devolución de llamada cuando el bloque se confirma.
• FreeTSA — sello de tiempo RFC 3161. Síncrono; el token se devuelve de inmediato. Intercambiable por un QTSP de pago (DataSure) para el cumplimiento del art. 42 de eIDAS.
• OpenTimestamps — anclaje en Bitcoin mediante el protocolo de calendario OpenTimestamps. Asíncrono; la ruta de actualización se ejecuta en un barrido de Celery.

Tres es por diseño: si alguna TSA desaparece, las otras dos siguen anclando la cadena. Un auditor puede verificar contra cualquiera de ellas de forma independiente usando exploradores de bloques públicos o endpoints de verificación.

Firma (SES / AES / QES)

Tres niveles eIDAS, todos sobre el mismo PDF de informe de auditoría:

• SES (Firma Electrónica Simple) — respaldada por la cadena de auditoría, sin certificado de firma. Adecuada para registros internos.
• AES (Firma Electrónica Avanzada) — certificado de firma vinculado a la identidad, anclado con PAdES B-T. Adecuado para la mayoría de los contratos B2B.
• QES (Firma Electrónica Cualificada) — el nivel eIDAS más alto, equivalente legal de una firma manuscrita en toda la UE. Restringido tras la verificación KYB de la organización emisora.

Campaña (opcional)

Una agrupación lógica de sesiones para informes por lotes — "Reclamaciones de motor Q2 2026" o "Defectos de entrega del Sitio A". Las sesiones no requieren una campaña; es una comodidad para informes.

Webhook

Una URL registrada por el cliente que recibe POST de eventos firmados con HMAC. Tipos de eventos: session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, más un webhook.test para la verificación de la entrega.

Firma: estilo Stripe t=...,v1=... cabecera con HMAC-SHA256 sobre <timestamp>.<body>. El constructEvent() helper del SDK verifica en tiempo constante con una tolerancia de desfase de reloj de 5 minutos.