Versionamiento de APIs
Política aplicable a las APIs públicas de Adereso Desk y Adereso Studio: versiones vigentes, compatibilidad, soporte, deprecación, retiro y comunicación de cambios.
Introducción y alcance
Esta política describe cómo Adereso versiona, mantiene, depreca y retira las APIs que ofrece expresamente a clientes y partners.
Adereso Desk y Adereso Studio son productos SaaS de despliegue continuo y no tienen una versión comercial única. La versión indicada en esta política corresponde al contrato de cada API.
Quedan fuera de esta política las interfaces internas entre servicios, los endpoints utilizados exclusivamente por las aplicaciones web o móviles de Adereso, las versiones de configuración de bots y las APIs de proveedores externos, salvo que un contrato indique expresamente lo contrario.
APIs vigentes
Producto | Superficie | Versión | Estado | Alcance |
Adereso Desk | API externa | v2 | Activa/GA | Integraciones de clientes y partners habilitados |
Adereso Desk | Rutas anteriores | v1 o rutas bajo /api/ | Legacy / en evaluación | Se mantiene mientras Adereso verifica consumidores y prepara un eventual plan de retiro |
Adereso Studio | Integration API | v1 · especificación OpenAPI 1.0.0 | Disponibilidad controlada | Integraciones externas expresamente habilitadas por Adereso |
Las versiones de bots creadas, restauradas o publicadas en Adereso Studio pertenecen a la configuración de cada bot. No representan la versión del producto ni de su API.
El estado vigente de cada API debe mantenerse en un registro operativo que identifique producto, audiencia, base URL, versión mayor, estado, documentación, propietario, fecha de disponibilidad general y, cuando corresponda, fechas de deprecación y retiro.
Versionamiento y compatibilidad
Adereso identifica en la ruta el número de versión mayor, por ejemplo /v1 o /v2. Una nueva versión mayor se crea cuando un cambio puede exigir modificaciones en la integración del consumidor.
Los cambios compatibles pueden publicarse dentro de la versión mayor vigente y se informan en el changelog. Entre otros, pueden incluir:
- Endpoints nuevos.
- Parámetros opcionales nuevos.
- Campos adicionales en respuestas.
- Métodos HTTP nuevos.
- Nuevos valores en conjuntos declarados como extensibles.
- Correcciones que alineen el comportamiento con la especificación publicada.
Las integraciones deben ignorar campos que no utilizan y no deben depender del orden ni de la cantidad exacta de campos de una respuesta.
Se consideran incompatibles, entre otros:
- Eliminar o cambiar el nombre de endpoints, parámetros o campos.
- Convertir un dato opcional en obligatorio.
- Restringir formatos, rangos o valores previamente aceptados.
- Cambiar la semántica de un dato.
- Modificar autenticación, códigos de respuesta o límites publicados de una forma que pueda romper integraciones existentes.
- Retirar un servicio web sin una alternativa o un proceso formal de deprecación.
Los cambios incompatibles requieren una nueva versión mayor o un proceso formal de deprecación.
Estados del ciclo de vida
- Preview: disponible para evaluación; puede cambiar y no tiene garantía de permanencia.
- Activa/GA: recomendada para nuevas integraciones, con documentación y soporte.
- Legacy: operativa para consumidores existentes, sin nuevas capacidades relevantes; no recomendada para nuevas integraciones.
- Deprecada: operativa durante el período de migración, con una fecha de retiro anunciada.
- Retirada: ya no está disponible.
Una API deprecada continúa funcionando durante el período de migración. Sólo el estado Retirada significa que dejó de operar.
Política de soporte y plazos mínimos
Reemplazo de una versión mayor
Cuando una nueva versión mayor alcance disponibilidad general, Adereso mantendrá operativa la versión mayor anterior durante un mínimo de 16 meses desde esa fecha.
Durante los primeros 8 meses la versión anterior mantendrá soporte de correcciones. Durante los 8 meses siguientes podrá operar como Legacy o Deprecada, con foco en correcciones críticas de seguridad y disponibilidad y en la migración hacia la versión activa.
Retiro de endpoints o capacidades
Cuando se retire un endpoint o una capacidad pública dentro de una versión mayor sin reemplazar toda la versión, Adereso dará un aviso mínimo de 12 meses antes de su retiro.
Los cambios compatibles y aditivos no inician un período de deprecación.
Excepciones
Los plazos anteriores no aplican a funcionalidades Preview o Beta, interfaces internas o cambios urgentes exigidos por:
- Una vulnerabilidad crítica de seguridad.
- Una obligación legal o regulatoria.
- El retiro o modificación forzosa de una plataforma o dependencia externa.
En estos casos, Adereso comunicará el cambio tan pronto como sea razonablemente posible y entregará una alternativa o mitigación cuando esté disponible.
Un contrato particular puede establecer condiciones diferentes o más favorables.
Comunicación y migración
Cada deprecación publicada incluirá:
- Fecha de anuncio.
- Fecha de retiro o sunset.
- Versiones, endpoints y consumidores afectados.
- Alternativa recomendada.
- Changelog y diferencias del contrato.
- Guía de migración.
- Entorno o mecanismo de prueba, cuando corresponda.
- Canal de soporte.
Adereso publicará el aviso en su documentación para desarrolladores y procurará notificar directamente a los administradores de las organizaciones cuyo consumo pueda identificar. Los clientes deben mantener actualizado su contacto técnico y monitorear el changelog.
Durante el período de migración, las mejoras funcionales se concentrarán en la versión activa. La versión deprecada seguirá operativa hasta la fecha de retiro anunciada y recibirá las correcciones comprometidas para su etapa del ciclo de vida.
Recomendaciones para consumidores
- Usar nombres de campos y no depender de su orden.
- Ignorar campos desconocidos que la integración no utilice.
- Tolerar valores nuevos en conjuntos declarados como extensibles.
- No validar la cantidad exacta de campos de una respuesta.
- Definir timeouts, reintentos con backoff e idempotencia cuando el endpoint lo permita.
- Monitorear el changelog y mantener actualizado el contacto técnico de la organización.
Gobierno y revisión
El inventario de APIs y sus estados debe revisarse al menos trimestralmente, antes de anunciar una deprecación y antes de responder compromisos contractuales o licitaciones.
Ninguna API pública puede declararse Retirada mientras existan rutas operativas o consumo conocido sin que se haya completado el proceso de deprecación aplicable.
Control de cambios
Fecha | Versión del documento | Cambio |
5 de septiembre de 2026 | 2.1 | Se cambia el título a Versionamiento y retiro de las APIs de Adereso Desk y Studio para comunicar con claridad el alcance y propósito de la política. |
5 de septiembre de 2026 | 2.0 | Reescritura integral. Se separan las versiones del producto y de sus APIs; se incorporan Adereso Desk y Adereso Studio; se registran Desk API v2 y Studio Integration API v1; se corrigen los estados del ciclo de vida; se formalizan compatibilidad, comunicación, excepciones y gobierno; se mantienen garantías mínimas de 16 meses para versiones mayores y 12 meses para endpoints o capacidades públicas. |
24 de febrero de 2023 | 1.0 | Política anterior. Inventario genérico de API v1 y v2, nomenclatura mayor/menor y ventanas de operación de 12 y 16 meses. |