Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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 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:

{
  "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:

  1. Lo anunciamos en el 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: los cambios de la API con su fecha, impacto y qué hacer.
  • Respuestas del API: cabeceras de respuesta, incluida X-Api-Version.
  • Errores: el codEstado 3007 y el resto del catálogo.
No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.