# Versiones de la configuración

> Cada cambio en una zona crea una versión numerada con su autor, su motivo, su acción y una instantánea completa de la configuración.

Cada zona tiene un contador de versiones que empieza en 1 al darla de alta. Cada escritura que cambia su configuración, la haga una persona, un token de API o el propio OpenWAF, lo incrementa en uno y guarda la versión nueva. La versión actual de la zona es la que deben servir sus nodos de borde.

## Qué registra una versión

| Campo | Significado |
|---|---|
| `version` | El número, consecutivo en cada zona. |
| `created_at` | Cuándo se confirmó el cambio. |
| `actor` | Quién lo hizo: `user:<id>` para una persona con sesión en el panel, `token:<id>` para un token de API (CLI, SDK, scripts, clientes MCP) y `system:<nombre>` para los cambios automáticos, como la emisión de certificados (`system:acme`). |
| `action` | Qué tipo de cambio fue, como `record.create`, `zone.edge.update` o `zone.revert`. Están todas en [Acciones de las versiones](https://developers.openwaf.dev/es/change-control/version-actions/). |
| `reason` | El motivo que acompañó al cambio, de 1 a 500 caracteres. |
| `restored_from` | En una vuelta atrás, la versión cuya configuración se restauró; si no, `null`. |
| `channel` | `mcp` cuando el cambio llegó por el servidor MCP; ausente en los demás casos. |
| `snapshot_sha256` | SHA-256 de la instantánea canónica. Dos versiones con el mismo hash tienen la misma configuración. |
| `snapshot` | La configuración completa de la zona en esa versión (solo al leer una versión concreta). |

## Qué contiene la instantánea

La instantánea es JSON canónico: claves ordenadas y listas ordenadas por una identidad estable, así que la misma configuración produce siempre los mismos bytes y el mismo hash. Contiene:

- la identidad de la zona: id, nombre y modo DNS (delegada o externa);
- sus ajustes de borde, incluidos los ajustes propios de cada nombre y sus límites de peticiones, caché, redirecciones, medición de usuarios reales y agentes de IA;
- sus reglas de borde (IP, país, excepciones del WAF, límites), con sus ids;
- sus registros DNS, con sus ids, comentarios y etiquetas;
- los grupos de nodos de borde que la sirven;
- una referencia a cada certificado: nombre, origen (ACME o manual), huella SHA-256 y fecha de caducidad.

> **Nota: Sin secretos**
>
> Ni el material de los certificados y sus claves privadas, ni los tokens de API ni ningún otro secreto se guardan en una versión. Los certificados aparecen solo por referencia, y por eso una vuelta atrás no los restaura (ver [Volver a una versión anterior](https://developers.openwaf.dev/es/change-control/revert-a-zone/#certificates)).


## Qué no se versiona

Algunos cambios no son configuración de la zona y no crean versión. Aun así quedan en la [auditoría](https://developers.openwaf.dev/es/change-control/audit-log/):

- el estado de la zona (pendiente, activa, desactivada), que depende de la comprobación de la delegación o de la propiedad;
- las purgas de caché (una vuelta atrás nunca recupera contenido purgado);
- los certificados de origen emitidos por la OpenWAF Origin CA y su revocación;
- los cambios de la organización: miembros, invitaciones, tokens de API, clientes, marca y marca blanca.

## Escrituras que no cambian nada

Si una escritura deja la configuración exactamente igual (mismo hash de instantánea), no se crea versión. Su simulación devuelve el mismo `from_version` y `to_version` con las diferencias vacías, y la entrada de la auditoría lleva `"unchanged": true`.

## Zonas borradas

Borrar una zona crea una última versión con la acción `zone.delete`: la identidad de la zona sin ajustes y con las listas vacías. El historial sobrevive a la zona y tu organización puede seguir leyéndolo por el id de la zona:

```sh
openwaf-cloud ctl zones history 3f1c2a9e-0000-4000-8000-000000000000
```

## Leer las versiones

| Interfaz | Lista | Una versión con su instantánea | Diferencias |
|---|---|---|---|
| Panel | **Cambios → Historial** | **Instantánea** en una fila | **Comparar versiones** |
| CLI | `zones history <zona>` | `zones history <zona> <versión>` | `zones diff <zona> <desde> [<hasta>]` |
| API | `GET /v1/orgs/{org}/zones/{zone}/versions` | `GET …/versions/{version}` | `GET …/diff?from=N&to=M` |
| MCP | `zone_history` | — | `zone_diff` |

Cualquier rol puede leer el historial de las zonas que ve. Paso a paso: [Ver el historial y comparar versiones](https://developers.openwaf.dev/es/change-control/view-history/).