Saltar al contenido principal
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

CampoTipoDescripción
iduuidID del evento
timestampdatetimeCuándo ocurrió el evento
sourcestring"signer" o "admin"
eventstringIdentificador del tipo de evento (ver referencia de eventos más abajo)
descriptionstringDescripción legible del evento
actorobject | nullQuién realizó la acción (ver más abajo)
ip_addressstring | nullDirección IP del firmante (solo eventos de firmante)
detailsobject | nullMetadatos específicos del evento
condensed_countintegerPresente 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

EventoDescripciónTiene details
document_openedAbrió el documentoNo
document_viewedVisualizó el documentoNo
document_savedGuardó valores de camposNo
document_finishedCompletó la firmaNo
document_signedFirmó el documentoNo
document_hiddenSalió de la páginaNo
document_visibleVolvió a la páginaNo
document_closedCerró el documentoNo

​
Firma y verificación

EventoDescripciónTiene details
signature_finalizedFirma finalizadaNo
signing_declinedRechazó firmarNo
terms_acceptedAceptó los términos y condicionesNo
otp_verifiedVerificó la identidad vía OTPNo
certificate_downloadDescargó el certificadoNo

​
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ónDescripción
field_focusedSeleccionó un campo
field_completedCompletó un campo por primera vez
field_modifiedModificó el valor de un campo existente
field_clearedBorró el valor de un campo
field_blurTerminó de editar un campo
El objeto details para las interacciones con campos incluye:
CampoTipoDescripción
field_typestringTipo de campo (firma, texto, fecha, etc.)
actionstringLa acción específica de la tabla anterior
interaction_countintegerNúmero de veces que se ha interactuado con este campo
value_lengthintegerLongitud del valor del campo (cuando aplica)
time_spent_msintegerTiempo dedicado al campo en milisegundos (cuando aplica)
EventoDescripciónTiene details
page_viewedVisualizó una página específicaSí — page_number
document_scrolledSe desplazó a una páginaSí — page_number
navigation_actionNavegó por el documentoSí — action (next_page, prev_page, go_to_page)
zoom_changedCambió el nivel de zoomNo
modal_interactionAbrió o cerró un cuadro de diálogoSí — 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”).