Política de actualizaciones [Desarrolladores]

En Adereso estamos orientados a mejorar continuamente nuestro servicio al cliente, por esta razón permanentemente optimizamos nuestros canales de atención y ayuda, y rediseñamos los procesos que nos permiten responder con más rapidez y efectividad.

En este documento se detalla el acuerdo de nivel de servicio y especificaciones en cada Web Service (APIs) desarrollados para integrar sistemas de terceros.

En la siguiente tabla se muestran las versiones activas en nuestra API.

A continuación se explica la implicancia de cada estado:

Activa: Con soporte completo. Está operativa y puede presentar versiones menores en el futuro.

Legacy: Aún operativa pero no tendrá actualizaciones. Candidata a eliminación próxima.

Deprecada: Sin soporte ni documentación. Esta versión de API ya no se encuentra operativa y es inminente su eliminación.

Eliminada: Esta versión de API ya no se encuentra operativa.

Cada versión de API no recibirá cambios que afecten la especificación técnica original, solo correcciones de errores.

Las modificaciones se realizarán sobre nuevas versiones completas de la API, permitiendo asegurar continuidad y retro compatibilidad si su código consume la versión de API compatible.

Es normal que ocurran cambios en una API a lo largo del tiempo debido a distintos motivos:

Para resolver lo anterior, la API de Adereso disponible para clientes seguirá la siguiente nomenclatura en sus versiones:

Número de versión mayor: Representa que entre un número y otro existen cambios que rompen la operación de la API respecto a su predecesor. Si el número de versión es v2.1, el número de versión mayor corresponde a 2.

Número de versión menor: Representa que entre un número y otro existen cambios que no deben afectar el consumo de la API respecto a su predecesor y es seguro hacer la actualización. Si el número de versión es v2.1, el número de versión mayor corresponde a 1.

Si se desea actualizar a una versión v3.0 será necesario hacer cambios en su código fuente para poder cambiar a dicha versión. Por el contrario, una actualización a v2.2 indica que hay modificaciones en la API pero los cambios sí son retro compatibles.

Un cambio retro compatible implica que desde una versión a otra, se tiene la misma información, por ejemplo:

Es decir, es seguro actualizar desde v2 hacia v2.1 pues se asegura que la información que se consume en v2 también estará disponible en v2.1, pero como se explica en el párrafo anterior, la versión v2.1 sí puede contener cosas nuevas.

Cambios que rompen la API, es decir no son retrocompatibles son modificaciones que hacen que al cambiar de versión ya no se cuente con la misma información anterior, por ejemplo:

Es decir, si usted actualiza de v2.1 hacia v3, debe leer la guía de migración para enteder los cambios que podrían afectar su sistema.

Cada vez que Adereso prepare una nueva versión se avisará con anticipación su fecha de lanzamiento.

Durante el lanzamiento se indicará la lista de cambios que pueden afectar su servicio. Se indicará si la versión tiene cambios mayores o menores y se incluirá una guía de migración entre versiones.

Cada vez que Adereso lance una nueva versión menor, se darán 6 meses de soporte a la versión inmediatamente anterior durante 6 meses.

Transcurridos los 6 meses se dejará de entregar corrección de errores dedicados a esta versión, entrando en estado legacy.

A los 6 meses posteriores dicha versión de API pasa a estado deprecado y se perderá acceso a la documentación. En este punto es forzosamente es necesario actualizar al menos a la próxima versión más nueva ya que el servicio en esa versión puede terminar su funcionamiento, entrando a estado eliminado.

En resumen, se asegura mínimo 12 meses de operación para una versión v2.1 una vez se lance la versión v2.2.

Opera muy similar al proceso de cambio entre versión menor, pero los bloques de tiempo son de 8 meses y no 6.

A los 8 meses se dejará de entregar corrección de errores dedicados a la versión anterior previa entrando en estado denominado legacy.

A los 8 meses posteriores la API pasa a estado deprecado.

En resumen, se asegura mínimo 16 meses de operación para una versión v2.2 una vez se lance la versión v3.

El equipo de Adereso analizará el consumo de sus servicios a la API, lo que nos permitirá conocer si su integración solicita una versión próxima a ser eliminada, permitiendo notificar oportunamente.

Además de la guía de migración, nuestros ingenieros estarán disponibles para consultas sobre cómo migrar sus servicios.

Bajo excepciones el plazo de deprecado a eliminado se puede extender.

Siempre utilice las llaves de los argumentos, no se base en el orden de los campos pues este no es garantizado.

Si recibe una respuesta con más información de la que utiliza debe ignorarla.

No realizar validaciones sobre la cantidad de campos, es posible que éstos aumenten en una versión menor y haga más difícil la migración entre versiones.