---
title: "Versionado — API v3 de AllSign"
type: explanation
canonical_url: "https://allsign.io/developers/docs/versioning"
api_version: "2026-07-11"
---

# 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_API_KEY" \
  -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://allsign.io/developers/docs/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`.