Versionado de la API

La v3 versiona en dos ejes independientes: el major vive en la ruta (/v3) y los cambios de comportamiento dentro de v3 se seleccionan con un header fechado, AllSign-Version. Fijas una fecha, congelas el comportamiento.

Dos ejes de versión

No mezcles los dos ejes: el major solo se mueve ante un cambio que rompe (breaking); todo lo demás —campos nuevos, defaults, correcciones de comportamiento— se entrega como una versión fechada dentro del mismo major, y tú eliges cuándo adoptarla.

Eje	Dónde	Cuándo cambia	Ejemplo
Major	En la ruta: `/v3/...`	Solo ante un breaking change (se corta compatibilidad)	`/v3` → `/v4`
Versión fechada	Header `AllSign-Version`	Cambios de comportamiento dentro de v3	`2026-07-11`

La versión fechada activa es 2026-07-11 — el mismo valor que info.version del OpenAPI y que el campo apiVersion que devuelve la API.

El header AllSign-Version

Manda la fecha en el header AllSign-Version. El nombre va en Hyphenated-Pascal-Case y sin prefijo X- (los headers con X- están deprecados por el RFC 6648). El valor es una fecha ISO YYYY-MM-DD.

curl "https://api.allsign.io/v3/documents?limit=20" \
  -H "Authorization: Bearer allsign_live_sk_..." \
  -H "AllSign-Version: 2026-07-11"

Fijar AllSign-Version: 2026-07-11 te garantiza el mismo contrato mientras exista esa versión, aunque publiquemos versiones fechadas más nuevas después.

Si falta o es desconocida

Dos caminos, según lo que mandes:

Omites el header → la petición corre contra la única versión de hoy (2026-07-11). Cómodo para explorar; en producción conviene fijarla explícita para no moverte solo cuando salga una nueva.
Mandas una fecha desconocida o inválida (formato malo, o una versión que no existe) → 400 UNSUPPORTED_API_VERSION. Fallamos cerrado: nunca adivinamos a qué versión te referías.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://developers.allsign.io/errors#UNSUPPORTED_API_VERSION",
  "title": "Unsupported API version",
  "status": 400,
  "detail": "Unknown AllSign-Version '2019-01-01'. Supported: 2026-07-11.",
  "code": "UNSUPPORTED_API_VERSION",
  "requestId": "req_..."
}

Escribe clientes tolerantes

Aun fijando la versión, tu cliente debe ser forward-compatible para que las adiciones no te rompan:

Ignora los campos que no conozcas en las respuestas — agregar un campo no es un breaking change.
Tolera valores nuevos en los enums de respuesta marcados x-extensible-enum (como DocumentStatus y SignerStatus): pueden aparecer estados nuevos sin cambiar de versión. Maneja el default con un caso genérico, no con un switch exhaustivo que truene ante lo desconocido.

Deprecación

Cuando algo se depreque, lo anunciaremos por headers estándar: Deprecation y Sunset (RFC 9745 / RFC 8594) más un Link a la guía de migración. Hoy no hay nada deprecado en v3 — pero instrumenta tu cliente para loguear esos headers y enterarte a tiempo.

Confirmar la versión activa

GET /v3/healthz te devuelve la versión fechada activa en el campo apiVersion. Úsalo como smoke check al arrancar o en CI para confirmar contra qué contrato estás corriendo.

GET /v3/healthz

{
  "status": "ok",
  "apiVersion": "2026-07-11",
  "requestId": "req_..."
}

El valor de apiVersion siempre coincide con info.version del OpenAPI y con lo que fijas en AllSign-Version.