# Versiones

> Qué significa v1 en la ruta y api_version en cada evento, y en qué estado está hoy el contrato.

Página: https://safeonuba.com/desarrolladores/versiones · API de SafeOnuba v1 (`api_version: "2026-09-24"`), en vista previa: el contrato puede cambiar.

La API tiene dos marcas de versión, y cada una dice una cosa distinta.

## v1 en la ruta

Todas las rutas van bajo `/v1`. Es la versión mayor del contrato: las rutas, los objetos y su significado.

## api_version en cada evento

Cada evento lleva `api_version: "2026-09-24"`, y el `User-Agent` de los webhooks lo repite (`SafeOnuba-Webhooks/2026-09-24`). Es la fecha de la versión del formato con el que se ha generado ese evento.

Guárdala junto a cada evento que recibas. Si algún día conviven formatos, es lo que te dirá con cuál se escribió cada uno.

## Estado actual: vista previa

> **v1 · vista previa**
>
> El contrato v1 está pendiente del visto bueno del primer cliente y **puede cambiar**. Cualquier cambio se anotará en el [changelog](https://safeonuba.com/desarrolladores/changelog), y el contrato publicado es siempre el que manda.

Mientras dure la vista previa:

- Genera tu cliente, si lo haces, desde el contrato ([OpenAPI 3.1](https://safeonuba.com/desarrolladores/openapi.json)) y vuelve a generarlo cuando cambie.
- Ignora los campos que no conozcas en lugar de fallar. Es la forma más sencilla de que un campo nuevo no rompa tu integración.
- Programa contra el `code` de los errores y contra los valores de los enums, no contra textos.

## El contrato

El contrato OpenAPI 3.1 es la fuente de verdad: la [referencia](https://safeonuba.com/desarrolladores/referencia) de esta documentación se genera desde él en cada despliegue. Lo tienes para descargar en [/desarrolladores/openapi.json](https://safeonuba.com/desarrolladores/openapi.json), y la API lo sirve en `GET /v1/openapi.json`, sin token.