> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Registro de Auditoría

> Rastrea cada acción sobre una solicitud de firma para cumplimiento normativo y reportes.

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

```bash theme={null}
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

```js theme={null}
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

```python theme={null}
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

```json theme={null}
{
  "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](#event-reference) 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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={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](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").