Lo que se garantiza

Una integración se parametriza una vez y tiene que seguir funcionando mientras ELYRA cambia por dentro. Para que eso sea una garantía y no una intención, la API de integraciones tiene un espacio propio, una versión y una foto de lo prometido que vigila cada cambio.

Lo que es contrato y lo que no

	Contrato	Interno
Dónde vive	https://tu-empresa.onelyra.com/api/integraciones/v1/…	Cualquier otra dirección de ELYRA: lo que usa el portal.
Está en	La referencia interactiva.	En ninguna documentación.
Cambia	Solo añadiendo. Lo que rompe va a una versión nueva, con aviso y plazo.	Cuando convenga, sin aviso.
Con credencial de integración	Abre lo de su familia.	No abre nada.
Soporte	Sí.	No.

Léalo así: solo está garantizado lo que aparece en la referencia. Si una integración se apoya en una ruta que no está ahí, puede dejar de funcionar en cualquier momento, y no es un fallo de ELYRA.

Qué cuenta como cambio que rompe

En la versión vigente ELYRA puede añadir, nunca quitar:

Se puede hacer en v1 (novedad)	No se hace en v1 (ruptura: va a v2)
Una ruta nueva.	Quitar o renombrar una ruta.
Un campo nuevo opcional en una petición.	Exigir un campo nuevo, o uno que era opcional.
Un campo nuevo en una respuesta.	Quitar o renombrar un campo de una respuesta, o cambiar su tipo.
Un valor nuevo en una lista de valores de respuesta.	Quitar un valor que una petición aceptaba.
Un código de error nuevo.	Quitar un código de error.
Un texto de detail mejor escrito.	Cambiar el codigo de un error.

De ahí dos reglas para quien integra: ignorar los campos que no conozca (mañana puede haber más) y programar contra codigo, nunca contra el texto de detail.

Cómo se vigila

El contrato de cada versión está guardado en una foto, y una prueba compara la API contra esa foto en cada cambio: una novedad pasa; una ruptura la detiene. Así la garantía no depende de que alguien se acuerde.

Versiones y retiro

• La versión va en la dirección: /api/integraciones/v1/.
• Cuando algo tiene que romperse, nace v2 y v1 sigue funcionando: las dos conviven.
• El retiro de una versión se anuncia con plazo —nunca menos de seis meses— por dos vías: el aviso al cliente y las cabeceras Deprecation y Sunset en cada respuesta de la versión que se retira, con la fecha.
• Cada versión tiene su referencia.

Lo que ayuda a soporte

Toda respuesta lleva la cabecera X-Request-Id. Si una llamada no hace lo esperado, ese identificador es lo que hay que enviar: con él se encuentra la llamada exacta. Si el sistema manda su propio X-Request-Id (letras, números, puntos, guiones; entre 8 y 128 caracteres), ELYRA lo devuelve tal cual, y así las dos partes hablan del mismo identificador.

Relacionado: La credencial · Errores, reintentos y duplicados.