<!-- source_url: https://docs.mynexusapi.com/v1/guias/versionado | last_updated: 2026-11-19 -->

# Versionado

El contrato de la API se identifica por una versión con fecha; aquí ves cuál está vigente, qué cambios son compatibles y cómo se anuncia un retiro.

La versión mayor de la API es la V1 y forma parte de la ruta (`/v1`). Dentro de
ella, cada versión del contrato se identifica con una fecha que te devolvemos en
la cabecera `X-Api-Version`. Lo habitual son los cambios compatibles; si alguna
vez hiciera falta un cambio incompatible, lo marcaríamos como **incompatible** en
el [Changelog](/v1/guias/changelog), con su fecha y lo que debes hacer. Aquí ves
cómo versionamos el contrato, qué cambios puedes esperar y cómo preparar tu
código para tolerarlos.

Te recomendamos consultarla cuando diseñes cómo tu integración lee las respuestas o si recibes un
400 con el `codEstado` 3007 (`version_no_soportada`). Al terminar sabrás si debes enviar `X-Api-Version`, qué
cambios no te afectan y cómo te enterarías de un retiro.

## Conceptos

- **Versión mayor (`/v1`).** Forma parte de la ruta. Un cambio que rompa a los
  integradores existentes se publicaría en una ruta nueva o, de forma
  excepcional, dentro de `/v1`, anunciado como incompatible en el Changelog.
- **Versión del contrato (fecha).** Dentro de `/v1`, el contrato se identifica
  con una fecha `aaaa-mm-dd`. La vigente es `2026-11-16`, y la API la devuelve en
  la cabecera `X-Api-Version` de cada respuesta.
- **Cambio compatible.** Es un cambio que no rompe a un integrador que ignora lo
  que no conoce, por ejemplo un campo nuevo en una respuesta.

## Versión vigente

| Versión | Fecha del contrato | Estado | Retiro |
|---|---|---|---|
| V1 | 2026-11-16 | Actual | Sin fecha de retiro |

Una forma rápida de comprobar la versión es llamar a `GET /v1/contexto` con la
cabecera `X-Api-Version: 2000-01-01`, que no corresponde a ninguna versión. La
API responde 400 antes de autenticar, así que no gastas cupo ni necesitas tu API
Key, y el cuerpo trae `codEstado` con el número 3007:

```json
{
  "estado": "rechazado",
  "codEstado": 3007,
  "msgError": "Versión de API no admitida.",
  "errores": []
}
```

El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado).

### Calendario en formato de máquina

El calendario en formato de máquina está en
[api-versions.json](/.well-known/api-versions.json). Para cada versión incluye
`version`, `status`, `releaseDate`, `deprecationDate`, `sunsetDate`, `reference`
(la referencia de la API) y `changelog`, y en la raíz indica la versión actual
en `current`. El detalle de cada cambio está en el
[Changelog](/v1/guias/changelog).

## Cabecera `X-Api-Version`

La cabecera funciona en los dos sentidos, aunque en la solicitud es opcional:

| Uso | Obligatoria | Valor |
|---|---|---|
| Solicitud | No | La fecha de la versión que quieres usar, por ejemplo `2026-11-16`. Si no la envías, responde la versión vigente. |
| Respuesta | Siempre en `/v1` | La versión del contrato que respondió. |

| Envías | Resultado |
|---|---|
| Sin `X-Api-Version` | Responde la versión vigente. Es lo recomendado. |
| `X-Api-Version: 2026-11-16` | Responde la versión vigente. |
| Cualquier otro valor, por ejemplo `2025-01-01` | La API responde 400 con el `codEstado` 3007, antes de autenticar. |

Te recomendamos no enviar la cabecera en tus solicitudes y registrar en tus
logs el valor de `X-Api-Version` de las respuestas. Así detectas cuándo cambia
la versión sin que tu integración falle.

> [!NOTE]
> Si fijas `X-Api-Version` en tu código, cuando esa versión se retire todas tus
> peticiones responderán 400 con el `codEstado` 3007. Fíjala solo si tienes previsto
> cómo actualizarla.

## Qué cambios son compatibles

Lo habitual dentro de `/v1` son cambios **compatibles**. Te recomendamos
preparar tu integración para tolerarlos:

| Cambio compatible (se registra en el Changelog) | Qué debe hacer tu código |
|---|---|
| Un campo nuevo en una respuesta JSON | Ignora los campos que no conoce. No uses deserializadores que fallen ante campos desconocidos. |
| Un endpoint nuevo | No necesita hacer nada. |
| Un código de error nuevo del catálogo | Trata un `codEstado` desconocido según su primer dígito, que fija el `estado`, y según el estado HTTP: corrige ante un 4xx y reintenta ante un 5xx. |
| Un `eventType` de webhook nuevo | Responde con un 2xx e ignóralo sin detener el procesamiento. |
| Un valor nuevo en un enumerado, por ejemplo un estado | Trátalo como desconocido sin romper el flujo. |
| Un campo opcional nuevo en la solicitud | No necesita hacer nada, porque si no lo envías el comportamiento no cambia. |

Estos otros cambios son incompatibles. Los publicaríamos en una versión nueva o,
de forma excepcional, dentro de `/v1`. En los dos casos los marcaríamos como
**incompatibles** en el [Changelog](/v1/guias/changelog), con la fecha, el
impacto y qué hacer.

| Cambio incompatible |
|---|
| Quitar o renombrar un campo de la solicitud o de la respuesta |
| Volver obligatorio un campo opcional |
| Cambiar el tipo o el formato de un campo |
| Cambiar el significado de un código de error o de un estado |

Ten en cuenta que en las solicitudes la regla es la contraria: la API
**rechaza** los campos desconocidos en la Estructura del comprobante con un 422
y el `codEstado` 3002. Por eso no envíes campos que no estén documentados en la guía
de su tipo de comprobante.

## Deprecación y retiro

Cuando una versión se reemplace, te avisaremos del retiro con tiempo y en
varios lugares:

1. Lo anunciamos en el [Changelog](/v1/guias/changelog) y en esta página, con la
   fecha de deprecación y la fecha de retiro.
2. `api-versions.json` publica `deprecationDate` y `sunsetDate`.
3. Las respuestas de esa versión incluyen las cabeceras de deprecación del
   RFC 8594: `Deprecation`, que indica desde cuándo está obsoleta, y `Sunset`,
   que indica cuándo dejará de responder.
4. La versión sigue operativa durante el periodo de solapamiento. Al llegar la
   fecha de retiro, responde 400 con el `codEstado` 3007.

Mientras una versión no esté en deprecación, sus respuestas no traen las
cabeceras `Deprecation` ni `Sunset`. La V1 no lo está.

## Reglas de la V1 que debes conocer

Si conoces otras APIs de facturación del SRI, estas reglas de la Estructura del
comprobante son las que más errores evitan:

| Regla | Qué hacer |
|---|---|
| `version` y `formato` no van en la Estructura del comprobante | Si los envías, la API responde 422 con el `codEstado` 3002. |
| `ambiente` y `tipoEmision` no se envían, ni en la raíz ni en `infoTributaria` | El ambiente lo define la URL y la emisión es siempre normal; si los envías, la API responde 422 con el `codEstado` 3002. |
| `infoTributaria.claveAcceso` no se envía | Deja que nosotros asignemos la clave de acceso; la obtienes en la respuesta 202 cuando el `codEstado` es 1002, en el seguimiento o en el webhook. |
| `infoTributaria.secuencial` es opcional | Omítelo o envíalo en ceros para que asignemos el siguiente. |
| El tipo de comprobante lo fija la ruta de emisión | Usa la ruta del tipo que emites: `facturas`, `liquidaciones-compra`, `notas-credito`, `notas-debito`, `guias-remision` o `retenciones`. No envíes `infoTributaria.tipoDocumento` en el cuerpo; `tipoDocumento` se lee en las respuestas y se usa en los filtros de consulta. |
| Los datos propios del tipo de comprobante van en `info` | Arma `info` solo con los campos de ese tipo. |
| Las respuestas JSON traen sus campos en el primer nivel | Lee cada campo directamente en la raíz del JSON, sin buscar una clave contenedora. |
| El resultado de una emisión está en `estado` | Sigue la operación mientras `estado` sea `recibido`, con `codEstado` 1001 o 1002; con cualquier otro valor ya es final, y `codEstado`, `msgError` y `errores` explican la causa cuando no es `autorizado`. |
| Los errores son planos (`estado`, `codEstado`, `msgError`, `errores`) y `codEstado` es un número estable de cuatro dígitos, como 3002 | Decide con `codEstado` y el estado HTTP, y lee el identificador de la petición en la cabecera `X-Correlation-Id`, porque no viene en el cuerpo. |

## Siguientes pasos

- [Changelog](/v1/guias/changelog): los cambios de la API con su fecha, impacto y qué hacer.
- [Respuestas del API](/v1/guias/respuestas): cabeceras de respuesta, incluida `X-Api-Version`.
- [Errores](/v1/guias/errores#catalogo-de-codestado): el `codEstado` 3007 y el resto del catálogo.
