En esta página
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, 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 fechaaaaa-mm-dd. La vigente es2026-11-16, y la API la devuelve en la cabeceraX-Api-Versionde 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:
{
"estado": "rechazado",
"codEstado": 3007,
"msgError": "Versión de API no admitida.",
"errores": []
}
El catálogo completo de codEstado está en Errores.
Calendario en formato de máquina#
El calendario en formato de máquina está en
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.
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.
Nota
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, 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:
- Lo anunciamos en el Changelog y en esta página, con la fecha de deprecación y la fecha de retiro.
api-versions.jsonpublicadeprecationDateysunsetDate.- Las respuestas de esa versión incluyen las cabeceras de deprecación del
RFC 8594:
Deprecation, que indica desde cuándo está obsoleta, ySunset, que indica cuándo dejará de responder. - La versión sigue operativa durante el periodo de solapamiento. Al llegar la
fecha de retiro, responde 400 con el
codEstado3007.
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: los cambios de la API con su fecha, impacto y qué hacer.
- Respuestas del API: cabeceras de respuesta, incluida
X-Api-Version. - Errores: el
codEstado3007 y el resto del catálogo.