POLÍTICA DE VERSIONES DE LA API PÚBLICA · WASTRA · v1 · T10 Interoperabilidad

Escrita el 24-09-2026 (noche) para dejar publicada la regla que ARQUITECTURA_SAAS.md y nucleo/api.py ya

aplican [F]: **la API nace versionada en la ruta (/v1/), es aditiva en versiones menores y toda ruptura es

una versión mayor nueva (/v2/) que convive con la anterior doce meses**. Esta página es la que un tercero

lee antes de integrarse; se enlaza desde web/api/ junto al contrato OpenAPI. Corte de revisión: 24-09-2026.

1 · Qué está versionado y cómo

Superficie	Versión	Dónde se ve
Rutas HTTP (`/v1/ingesta/lote`, `/v1/estado`, `/v1/lectura/*`, `/v1/biblioteca`, `/v1/openapi.json`)	mayor en la ruta: `v1`	la propia URL
Contrato OpenAPI	`info.version` = mayor vigente	`/v1/openapi.json`, copia publicada en `web/api/openapi.json`
Formato de exportación	`wastra-export/1.0` (norma pública)	manifiesto de cada paquete
Tipos de hecho	`TIPO/N` en el propio hecho (`esquema`)	`esquemas/INDICE.json` con huellas
Catálogos gobernados	`vN` ratificado en la cadena (`VERSION_CATALOGO`)	`catalogos/ESTADO_RATIFICACIONES.md`
Webhooks al pagador	`formato: WEBHOOK_WASTRA/1` en cada aviso	`API_LECTURA.md` §Webhooks
Adaptadores de entrada	`FORMATO_*/N` por formato	`ADAPTADORES_EXTERNOS.md`, `ADAPTADOR_ADMS.md`

Aditivo dentro de una mayor. En /v1/ solo se añaden rutas, campos opcionales de respuesta y valores

nuevos en enumeraciones. Nunca se quita una ruta, se renombra un campo, se cambia el tipo de un valor ni se

vuelve obligatorio un parámetro que era opcional. Un cliente escrito contra /v1/ de hoy sigue funcionando

contra /v1/ de dentro de un año.

Ruptura = mayor nueva. Cualquier cambio que rompa la regla 1 nace en /v2/. /v1/ sigue sirviendo

doce meses desde la publicación de /v2/, con aviso en /v1/estado (aviso_version) y en la página de

estado desde el primer día. Pasados los doce meses, /v1/ devuelve 410 con la ruta equivalente en el cuerpo.

Los tipos de hecho no se editan: se versionan. TIPO/2 convive con TIPO/1 para siempre: un hecho

antiguo se valida contra el esquema con el que se firmó (la huella del índice lo fija). La ingesta acepta

las versiones que el MAPA_TIPOS_MODULOS vigente declara.

Los catálogos se versionan en la cadena. Un catálogo ratificado no cambia; la versión siguiente se

ratifica con un hecho VERSION_CATALOGO y la anterior queda citable por su huella.

El contrato manda. web/api/openapi.json se regenera de nucleo/api.py (generar_pagina_openapi.py) y

se publica con su huella; la documentación en prosa (API_LECTURA.md) explica, no contradice.

Cuota y claves no son parte de la versión. Pueden cambiar con aviso de treinta días en la página de

estado; el código de respuesta (429 con Retry-After) no cambia.

Lo que se retira, se anuncia. Cualquier retirada (ruta, valor, formato) aparece en web/api/ como

«retirado en» con fecha y sustituto, doce meses antes de dejar de servirse.

pruebas/test_lectura_api.py y test_api_lectura_certificado fijan las rutas y campos de /v1/lectura/*:

quitar uno rompe la batería.

pruebas/test_indice_esquemas fija que ninguna versión publicada de un tipo cambie de huella.

La página web/api/ lleva la huella del contrato y esta política al pie.

Publicar aviso_version en /v1/estado cuando exista una /v2/ (hoy no hay ruptura prevista).

Servir el MCP de lectura por HTTP con la misma clave (bloque 1 de API_LECTURA.md).