Registro de Auditoría

Cada solicitud de firma en Firma tiene un registro de auditoría completo. Cada visualización de documento, interacción con campos, firma, rechazo y acción administrativa se registra con marca de tiempo, identidad del actor y direcciones IP. Casos de uso comunes:

Cumplimiento normativo y evidencia legal — demuestra quién firmó qué, cuándo y desde dónde
Depuración de problemas de firmantes — observa exactamente qué hizo un destinatario durante su sesión de firma
Reportes internos — rastrea acciones administrativas como creación, ediciones y cancelaciones

El registro de auditoría captura dos categorías de eventos:

Eventos de firmante — visualizaciones de documento, interacciones con campos, firma, rechazo, descargas de certificado
Eventos de administrador — creación, ediciones, envío, cancelación, reenvío (desde el panel o vía API)

Cada evento incluye una marca de tiempo, una descripción legible, la identidad del actor y (para eventos de firmante) la dirección IP del firmante.

Ver el registro de auditoría en el panel

Abre cualquier solicitud de firma en el panel de Firma y haz clic en la pestaña Registro de Auditoría. Verás una línea de tiempo cronológica de todos los eventos, con las acciones de firmantes y de administradores distinguidas visualmente. Los eventos repetitivos consecutivos (como desplazamientos o interacciones repetidas con campos) se condensan automáticamente con un indicador de conteo.

Obtener el registro de auditoría vía API

Usa el endpoint de auditoría para obtener el historial completo de eventos de una solicitud de firma:

GET /signing-requests/{id}/audit

curl

curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"

Node.js

const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);

Python

import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]

Ejemplo de respuesta

{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}

Campos de la respuesta

Campo	Tipo	Descripción
`id`	`uuid`	ID del evento
`timestamp`	`datetime`	Cuándo ocurrió el evento
`source`	`string`	`"signer"` o `"admin"`
`event`	`string`	Identificador del tipo de evento (ver referencia de eventos más abajo)
`description`	`string`	Descripción legible del evento
`actor`	`object \| null`	Quién realizó la acción (ver más abajo)
`ip_address`	`string \| null`	Dirección IP del firmante (solo eventos de firmante)
`details`	`object \| null`	Metadatos específicos del evento
`condensed_count`	`integer`	Presente cuando eventos idénticos consecutivos del mismo actor se agrupan

Comprender las fuentes de eventos

El campo source indica si un evento proviene de un firmante o de un administrador, y el campo actor tiene una forma diferente para cada caso.

Eventos de firmante

Los eventos con source: "signer" son acciones realizadas por los destinatarios durante el flujo de firma. El objeto actor contiene el name y email del firmante. El campo ip_address está poblado.

{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}

Eventos de administrador

Los eventos con source: "admin" son acciones realizadas desde el panel o vía API. El objeto actor contiene un campo type ("api_key" o "user") y opcionalmente un user_id. El campo ip_address es null.

{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}

{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}

Seguimiento en tiempo real vía webhooks

Si necesitas notificación en tiempo real de eventos de firmante en lugar de consultar periódicamente el endpoint de auditoría, Firma admite webhooks. Consulta la guía de Webhooks para instrucciones de configuración.

Referencia de eventos

Ciclo de vida del documento

Evento	Descripción	Tiene `details`
`document_opened`	Abrió el documento	No
`document_viewed`	Visualizó el documento	No
`document_saved`	Guardó valores de campos	No
`document_finished`	Completó la firma	No
`document_signed`	Firmó el documento	No
`document_hidden`	Salió de la página	No
`document_visible`	Volvió a la página	No
`document_closed`	Cerró el documento	No

Firma y verificación

Evento	Descripción	Tiene `details`
`signature_finalized`	Firma finalizada	No
`signing_declined`	Rechazó firmar	No
`terms_accepted`	Aceptó los términos y condiciones	No
`otp_verified`	Verificó la identidad vía OTP	No
`certificate_download`	Descargó el certificado	No

Interacciones con campos

Las interacciones con campos se registran como eventos field_interaction. El objeto details contiene la acción específica y los metadatos del campo.

Acción	Descripción
`field_focused`	Seleccionó un campo
`field_completed`	Completó un campo por primera vez
`field_modified`	Modificó el valor de un campo existente
`field_cleared`	Borró el valor de un campo
`field_blur`	Terminó de editar un campo

El objeto details para las interacciones con campos incluye:

Campo	Tipo	Descripción
`field_type`	`string`	Tipo de campo (firma, texto, fecha, etc.)
`action`	`string`	La acción específica de la tabla anterior
`interaction_count`	`integer`	Número de veces que se ha interactuado con este campo
`value_length`	`integer`	Longitud del valor del campo (cuando aplica)
`time_spent_ms`	`integer`	Tiempo dedicado al campo en milisegundos (cuando aplica)

Navegación

Evento	Descripción	Tiene `details`
`page_viewed`	Visualizó una página específica	Sí — `page_number`
`document_scrolled`	Se desplazó a una página	Sí — `page_number`
`navigation_action`	Navegó por el documento	Sí — `action` (`next_page`, `prev_page`, `go_to_page`)
`zoom_changed`	Cambió el nivel de zoom	No
`modal_interaction`	Abrió o cerró un cuadro de diálogo	Sí — `modal_type`, `action`

Actividad administrativa

Los eventos de administrador usan event: "activity" con un campo description legible que describe la acción realizada (por ejemplo, “Created signing request via API”, “Sent signing request”, “Cancelled signing request”).

Guías de Inicio

Guías avanzadas

Registro de Auditoría

Ver el registro de auditoría en el panel

Obtener el registro de auditoría vía API

curl

Node.js

Python

Ejemplo de respuesta

Campos de la respuesta

Comprender las fuentes de eventos

Eventos de firmante

Eventos de administrador

Seguimiento en tiempo real vía webhooks

Referencia de eventos

Ciclo de vida del documento

Firma y verificación

Interacciones con campos

Navegación

Actividad administrativa

​Ver el registro de auditoría en el panel

​Obtener el registro de auditoría vía API

​curl

​Node.js

​Python

​Ejemplo de respuesta

​Campos de la respuesta

​Comprender las fuentes de eventos

​Eventos de firmante

​Eventos de administrador

​Seguimiento en tiempo real vía webhooks

​Referencia de eventos

​Ciclo de vida del documento

​Firma y verificación

​Interacciones con campos

​Navegación

​Actividad administrativa

Ver el registro de auditoría en el panel

Obtener el registro de auditoría vía API

curl

Node.js

Python

Ejemplo de respuesta

Campos de la respuesta

Comprender las fuentes de eventos

Eventos de firmante

Eventos de administrador

Seguimiento en tiempo real vía webhooks

Referencia de eventos

Ciclo de vida del documento

Firma y verificación

Interacciones con campos

Navegación

Actividad administrativa