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

# Registros de auditoría

> Quién hizo qué en un espacio de trabajo: miembros, permisos, claves API, integraciones, configuración y cambios de contenido, con la dirección de origen y si se permitió. Solo admite añadir entradas, se puede exportar y tú controlas la retención.

## Descripción general

El registro de auditoría guarda cada acción de control realizada en un despliegue: un miembro invitado, un conjunto de permisos modificado, una clave API creada, una integración editada, una plantilla guardada, un envío masivo programado, un contacto eliminado, la licencia instalada. Cada entrada indica el actor, la acción, su objetivo, la dirección IP y el user agent de origen, el ID de la petición, y si tuvo éxito, falló o se rechazó. Las acciones sensibles para la seguridad incluyen además el antes y el después de lo que cambió, con todos los secretos ocultos.

Nunca registra el plano de datos (upserts de contactos, envíos, seguimiento, eventos personalizados), que puede llegar a miles de peticiones por minuto y corresponde a [Registros](https://www.notifuse.com/es/docs/features/logs.md).

Los registros de auditoría son una **capacidad con licencia** (Enterprise): solo se registran entradas mientras haya instalada una clave de licencia que cubra `audit_logs`. Leer, exportar y configurar la retención nunca están restringidos, así que la página funciona en cualquier estado de la licencia con lo que se haya registrado. Consulta [Claves de licencia](https://www.notifuse.com/es/docs/self-hosting/licence.md).

En Notifuse Cloud la clave se gestiona por ti, y los registros de auditoría se guardan en el plan Business. Consulta [En Notifuse Cloud](https://www.notifuse.com/es/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> **No se rechaza nada y no se oculta nada.** Un despliegue sin licencia no escribe ninguna entrada y no recibe ningún aviso. Un despliegue cuya clave caduca deja de registrar al terminar el periodo de gracia de 30 días y escribe una entrada que lo marca, `licence.recordingStopped`, para que el hueco nunca pase desapercibido. Al volver a instalar una clave se escribe `licence.recordingResumed`.

## Dónde encontrarlo

**Registros → Registro de auditoría**, en un espacio de trabajo, muestra las entradas de ese espacio, junto a los registros de mensajes y de webhooks. Un usuario root (un `ROOT_EMAIL`) puede cambiar esa misma pestaña a **Todo el despliegue**: todos los espacios de trabajo más las entradas del despliegue que no pertenecen a ningún espacio (inicios de sesión, la licencia, la configuración del sistema).

Los propietarios ven siempre la pestaña. Un miembro o una clave API solo la ven si tienen el permiso de lectura de **Registros de auditoría**. Este permiso hay que concederlo de forma expresa y nunca forma parte del "acceso total", porque el acceso total no debería implicar leer la dirección de correo, la dirección IP y las acciones rechazadas de cada compañero. Un miembro que solo tiene ese permiso ve la entrada Registros del menú y únicamente esta pestaña.

Cada entrada se lee como una frase, por ejemplo "Invitó a **[ann@example.com](mailto:ann@example.com)**", junto al actor, el recurso y, cuando la petición no tuvo éxito, su resultado. Al hacer clic en una entrada se abre en un panel lateral con la acción, el resultado y el estado HTTP, el actor, el objetivo, la dirección IP, el user agent, el ID de la petición, el antes y el después de lo que cambió, los metadatos y la entrada en bruto.

![Pestaña Registro de auditoría en la sección Registros](https://www.notifuse.com/docs/assets/screenshots/audit_logs.png)

![Una entrada del registro de auditoría abierta en su panel lateral: acción, resultado, actor, objetivo, dirección IP, user agent, ID de la petición y metadatos](https://www.notifuse.com/docs/assets/screenshots/audit_logs_entry.png)

**Configuración → Registro de auditoría** es donde un propietario define la retención del espacio de trabajo, y donde aparece el aviso de licencia cuando no se está registrando nada.

## Qué contiene una entrada

| Campo                                                               | Significado                                                                                                                                                                                                                             |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `occurred_at`                                                       | Cuándo terminó la acción, en UTC.                                                                                                                                                                                                       |
| `action`                                                            | La ruta RPC que la ejecutó, tal cual: `workspaces.inviteMember`, `templates.update`, `contacts.delete`.                                                                                                                                 |
| `category`                                                          | Una agrupación para filtrar: `auth`, `licence`, `system`, `workspaces`, `members`, `api_keys`, `integrations`, `webhooks`, `templates`, `broadcasts`, `automations`, `lists`, `segments`, `transactional`, `blog`, `contacts`, `audit`. |
| `outcome`                                                           | `success`, `failure` (la petición se rechazó por otro motivo, o falló un inicio de sesión) o `denied` (403 o 402).                                                                                                                      |
| `status_code`                                                       | El estado HTTP con el que respondió la petición.                                                                                                                                                                                        |
| `actor_type`, `actor_id`, `actor_email`, `actor_name`, `actor_role` | Quién lo hizo: un `user`, una `api_key`, el `system` (purgas de retención, marcas de licencia) o `anonymous` (un inicio de sesión fallido). El rol es `owner`, `member` o `root`.                                                       |
| `auth_method`                                                       | `session`, `api_key`, `magic_code`, `sso` o `root_password`.                                                                                                                                                                            |
| `target_type`, `target_id`, `target_name`                           | Sobre qué se hizo.                                                                                                                                                                                                                      |
| `ip_address`, `user_agent`, `request_id`                            | De dónde vino. El ID de la petición se devuelve en cada respuesta de la API como `X-Request-ID`, así que una entrada se puede relacionar con una línea del registro de tu aplicación.                                                   |
| `changes`                                                           | El antes y el después de los campos que cambiaron, como `{ "field": { "old": …, "new": … } }`. Las contraseñas, secretos, tokens y claves se sustituyen por `[redacted]` en ambos lados; se conserva el hecho de que cambiaron.         |
| `metadata`                                                          | Detalle libre: el alcance del permiso concedido, el número de contactos importados, el motivo por el que falló un inicio de sesión.                                                                                                     |

## Qué se registra

Cada ruta `POST /api/…` de la tabla se registra con su propio nombre. Las lecturas no se registran, con una excepción: la exportación de contactos de la consola pide la primera página de `contacts.list` con `export=true`, y esa petición se registra como `contacts.export`. Un cliente de la API que recorre la lista por su cuenta hace lecturas normales, que no se registran.

| Categoría       | Acciones                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| auth            | `user.signin`, `user.verify`, `user.rootSignin`, `user.oidc.exchange`, `user.oidc.callback`, `user.logout`, `setup.initialize`                                                                         |
| licence         | `licence.set`, `licence.recordingStopped`, `licence.recordingResumed`                                                                                                                                  |
| system          | `settings.update`                                                                                                                                                                                      |
| workspaces      | `workspaces.create`, `workspaces.update`, `workspaces.delete`, `workspaces.setBlogSettings`, `workspaces.setCustomFieldLabels`, `workspaces.setWebAnalyticsSettings`, `workspaces.setAuditLogSettings` |
| members         | `workspaces.inviteMember`, `workspaces.acceptInvitation`, `workspaces.joinInvitation`, `workspaces.deleteInvitation`, `workspaces.removeMember`, `workspaces.setUserPermissions`                       |
| api_keys        | `workspaces.createAPIKey`, `workspaces.connectZapier`                                                                                                                                                  |
| integrations    | `workspaces.createIntegration`, `workspaces.updateIntegration`, `workspaces.deleteIntegration`, `ses.enableTenantIsolation`, `webhooks.register`                                                       |
| webhooks        | `webhookSubscriptions.create`, `.update`, `.delete`, `.toggle`, `.regenerateSecret`                                                                                                                    |
| templates       | `templates.create`, `.update`, `.delete`, `templateBlocks.create`, `.update`, `.delete`                                                                                                                |
| broadcasts      | `broadcasts.create`, `.update`, `.schedule`, `.pause`, `.resume`, `.cancel`, `.delete`, `.retryFailed`, `.selectWinner`, `.sendToIndividual`                                                           |
| automations     | `automations.create`, `.update`, `.delete`, `.activate`, `.pause`                                                                                                                                      |
| lists, segments | `lists.create`, `.update`, `.delete`, `segments.create`, `.update`, `.delete`, `.rebuild`                                                                                                              |
| transactional   | `transactional.create`, `.update`, `.delete`                                                                                                                                                           |
| blog            | `blogPosts.*`, `blogCategories.*`, `blogThemes.*`                                                                                                                                                      |
| contacts        | `contacts.delete`, `contacts.import`, `contacts.export`, `customEvents.import`, `annotations.*`, `webAnalytics.backfillStart`, `.backfillCancel`                                                       |
| audit           | `auditLogs.export`, `audit.purged`                                                                                                                                                                     |

`GET /api/auditLogs.actions` devuelve este catálogo, que es la base del filtro de acciones de la consola.

**También se registran los fallos.** Un inicio de sesión con una dirección desconocida, un código erróneo o caducado, un intento bloqueado por límite de frecuencia: la respuesta no revela nada y la entrada dice el motivo (`metadata.reason`). Una petición rechazada por una comprobación de permisos se registra como `denied` con el recurso y el permiso que le faltaba; una rechazada por la licencia queda como `denied` con la función que necesitaba.

**No se registra**: el plano de datos (`contacts.upsert`, `customEvents.upsert`, `transactional.send`, `lists.subscribe` y las demás rutas por contacto), las lecturas, las pruebas y vistas previas, los endpoints de tareas internas, ni un envío masivo pausado automáticamente por el circuit breaker, porque eso ocurre en la ruta de envío, que no contiene ninguna comprobación de licencia.

## Filtrar y exportar

El cuadro de búsqueda acepta una dirección IP, el correo de un actor o el ID de un objetivo, y muestra por cuál de ellos está buscando. Una dirección IP y un ID de objetivo deben coincidir exactamente; un correo coincide con cualquier parte. Al lado hay filtros para el periodo (de las últimas 24 horas a los últimos 90 días, todo el historial o un rango personalizado), el actor (tú, un miembro o una clave del espacio de trabajo en la vista del espacio; cualquier clave API, el sistema o un visitante sin sesión en ambas vistas) y el recurso, y **+ Filtro** añade la acción, el resultado, el correo del actor, el ID del objetivo y la dirección IP. Todos los filtros se guardan en el enlace de la página, así que puedes compartir una vista filtrada o guardarla en marcadores. La API acepta los mismos filtros más `target_type`. Las páginas usan cursores, de la más reciente a la más antigua, y en la vista del espacio de trabajo el pie de la lista indica cuánto tiempo conserva el espacio sus entradas.

**Exportar** descarga el filtro actual en CSV o NDJSON, hasta 100 000 filas. Una exportación que llega al límite termina con una fila de marca `export.truncated` que lleva `max_rows`, para que un archivo truncado nunca se tome por uno completo; acota el rango de fechas y vuelve a exportar. La propia exportación se registra como `auditLogs.export`. Cada entrada tiene un ID, y el botón **Copiar enlace** del panel lateral da un enlace que abre la página en esa entrada, aunque esté muy abajo en la lista.

## Retención

Las entradas más antiguas que la retención se eliminan una vez al día. El valor predeterminado es **365 días**. El propietario de un espacio de trabajo puede definir la retención propia del espacio en Configuración → Registro de auditoría (0 conserva todas las entradas para siempre; si no, de 30 a 3650 días). Un usuario root define el valor predeterminado del despliegue en la configuración del sistema; ese valor rige también las entradas del despliegue y las de los espacios de trabajo que ya no existen. Cada purga que eliminó algo se registra como `audit.purged`, con el número de entradas.

La retención funciona en cualquier estado de la licencia: borrar datos nunca depende de la licencia.

## Integridad

La tabla **solo admite añadir entradas**: un trigger de la base de datos rechaza todo `UPDATE` y `TRUNCATE`, y todo `DELETE` salvo los que hace la función de retención. Ningún código de Notifuse reescribe el historial, y tampoco puede hacerlo una sentencia SQL suelta ejecutada con su rol de base de datos.

Lo que no impide: que el propietario de la base de datos, o un superusuario, desactive el trigger o borre la tabla. La garantía es "la aplicación no puede alterar el registro", no "nadie puede". Si tienes que demostrarlo ante un auditor, haz copias de seguridad de la tabla fuera de banda con una frecuencia que el auditor acepte.

Las entradas se guardan en la base de datos del sistema, no en la base de datos propia del espacio de trabajo, así que eliminar un espacio de trabajo no borra nada del registro: queda constancia de quién lo eliminó y de lo que hizo antes.

## API

Los cuatro endpoints están documentados en la referencia de la API: [`auditLogs.list`](https://www.notifuse.com/docs/api-reference/audit-logs/list-audit-logs.md), [`auditLogs.get`](https://www.notifuse.com/docs/api-reference/audit-logs/get-an-audit-log-entry.md), [`auditLogs.actions`](https://www.notifuse.com/docs/api-reference/audit-logs/list-audit-actions.md) y [`auditLogs.export`](https://www.notifuse.com/docs/api-reference/audit-logs/export-audit-logs.md). Una clave API puede llamarlos si tiene el permiso de lectura de Registros de auditoría, y así es como un SIEM recoge el registro de forma periódica. La retención se define por la API con [`workspaces.setAuditLogSettings`](https://www.notifuse.com/docs/api-reference/audit-logs/set-the-workspace-audit-log-retention.md), que solo puede llamar el propietario del espacio de trabajo: ningún permiso lo concede.
