Versionado

La versión va en la ruta

Todos los endpoints llevan la versión en el path, por ejemplo /api/v1.0/sales. No hay negociación de versión por header ni por query param: la ruta es el contrato, y el sidebar de la referencia muestra qué versiones expone cada API.

Qué consideramos un cambio compatible

Estos cambios pueden salir en cualquier momento y tu integración tiene que tolerarlos:

• Agregar un campo nuevo a una respuesta.
• Agregar un parámetro opcional nuevo a un endpoint.
• Agregar un valor nuevo a un enumerado.
• Agregar un endpoint nuevo.
• Cambiar la redacción del message de un error, manteniendo su error.

De ahí se desprenden dos reglas para tu cliente:

1. Ignorá los campos que no conocés. Un parser estricto que falla ante una clave nueva convierte una mejora nuestra en una caída tuya.
2. Tené un caso por defecto para los enumerados. Un valor nuevo no debería tirar una excepción.

Qué consideramos un cambio incompatible

Estos no salen sin aviso previo:

• Sacar o renombrar un campo de una respuesta.
• Cambiar el tipo de un campo.
• Volver obligatorio un parámetro que era opcional.
• Cambiar el significado de un campo existente.
• Sacar un endpoint.

La referencia de este portal se genera desde el documento OpenAPI publicado: cuando el documento cambia, la referencia cambia sola. Lo que leés acá es el estado real de la API, no una copia que alguien se acordó de actualizar.

Estabilidad de las URLs de esta documentación

Las direcciones de las páginas de referencia también son un contrato. Un endpoint documentado mantiene su dirección aunque el path de la API cambie: si algo se mueve, se agrega una redirección y el link viejo sigue funcionando. Podés linkearlas desde tus runbooks internos sin miedo.