Conectar un sistema REST

Un sistema es cualquier programa de tu empresa con el que ELYRA necesita hablar: la mesa de servicio donde viven los casos, el ERP que sabe el estado de un pedido, la agenda que tiene las citas. ELYRA no guarda esa información: la pide, y para pedirla necesita saber tres cosas — dónde está, cómo se entra y con qué se entra.

Esta guía cubre los sistemas que se hablan por una API REST, que es la forma más extendida. Si el tuyo se habla de otra manera, es otro recorrido con su propia guía.

Qué es una API REST, en una frase

Es una forma de que dos programas se hablen usando direcciones web. Tú ya usas direcciones todos los días: escribes una en el navegador y te llega una página. Aquí es igual, salvo que en vez de una página llega un dato ordenado —normalmente en un formato llamado JSON— que otro programa puede leer.

Antes de empezar

Todo esto lo tiene quien administra el sistema que vas a conectar, y está en su documentación para desarrolladores:

• La dirección base del sistema.
• Cómo se pide permiso para entrar — lo que en esas documentaciones se llama autenticación.
• Las credenciales: el usuario y la clave, o la llave de aplicación, o lo que ese sistema use.

Esta es la parte técnica de ELYRA, y está aquí a propósito

Casi todo en ELYRA se configura escribiendo en castellano. Esta pantalla no: aquí se describe cómo se entra a otro programa, y eso hay que decirlo con la precisión con la que ese programa lo pide. La buena noticia es que se hace una vez por sistema, y a partir de ahí todo lo demás se configura normal.

Primera parte · Dar de alta el sistema

1 · Crear el sistema

En el portal, entra a Conexiones y elige la pestaña Sistemas. Ahí está el botón de Nuevo sistema.

Pide dos datos:

• Nombre — es para ti, para reconocerlo entre los tuyos.
• URL base — la dirección del sistema, sin barra al final. Es la parte que se repite en todas sus direcciones; lo que cambia de una a otra lo pondrá cada operación.

Qué va en la URL base y qué no

Si la documentación de tu sistema dice que sus direcciones son https://mi-sistema.com/api/casos y https://mi-sistema.com/api/usuarios, la parte común es la base:

https://mi-sistema.com/api

Lo que cambia (/casos, /usuarios) va en cada operación, no aquí.

Segunda parte · Cómo entra ELYRA

Aquí está el corazón del asunto, así que conviene entender qué se está describiendo antes de rellenar nada.

El problema que resuelve

Un sistema no le abre la puerta a cualquiera. Antes de contestar nada quiere saber quién pregunta. Hay muchas formas de demostrarlo, y cada sistema elige la suya. ELYRA no trae ninguna metida por dentro: tú le describes la de tu sistema, y esa descripción es lo que en el portal se llama la forma de login.

Que sea una descripción y no código tiene una consecuencia práctica: la puedes guardar y reutilizar. Si mañana conectas un segundo sistema del mismo fabricante, eliges la forma que ya guardaste y solo cambias las credenciales.

Las dos maneras, y cómo saber cuál es la tuya

Lee la documentación de tu sistema y busca a cuál de estas dos se parece:

Si la documentación dice…	Entonces es…
«haz una petición a /login y te devolveremos un token»	Login con token
«incluye tu clave en la cabecera X-API-Key en cada petición»	Llave fija

La primera es la más común y la que explica el resto de esta guía. La segunda es más simple y está al final.

2 · Qué es un token, y por qué hay un paso previo

Un token es un pase temporal. En vez de mandar tu usuario y tu clave en cada pregunta —que sería como gritar tu contraseña cada vez que abres una puerta—, se mandan una sola vez a una dirección de entrada, y el sistema devuelve una cadena larga de caracteres: el token. A partir de ahí, cada petición lleva ese token y no la contraseña.

El formato más extendido se llama JWT. Para lo que aquí hace falta, un JWT es simplemente un token que el sistema firma, de modo que puede comprobar que no se ha manipulado. No hay que saber leerlo por dentro ni hacer nada con él: ELYRA lo pide, lo guarda mientras dure y lo vuelve a pedir cuando caduca.

Por eso entrar tiene dos momentos, y la pantalla los separa:

1. El login — se manda lo secreto una vez y se recibe el token.
2. Cada petición — se manda el token.

3 · Elegir la forma de login

Con el sistema creado, pulsa Configurar: en su ficha está la tarjeta Autenticación, y ahí van los tres campos que vienen numerados.

El primer campo ofrece empezar por la forma en blanco o usar una que ya hayas guardado. Empieza por la forma en blanco: es el caso más común y viene lista para ajustar.

Así es como viene:

{
  "login_method": "POST",
  "login_content_type": "json",
  "login_body": {
    "username": "{{username}}",
    "password": "{{password}}"
  },
  "login_headers": {},
  "token_path": "access_token",
  "auth_header_name": "Authorization",
  "auth_header_format": "Bearer {token}",
  "token_ttl_minutes": 55
}

Parece mucho. Son ocho frases, y cada una contesta una pregunta:

Lo que dice	Qué pregunta contesta
login_method	¿Con qué verbo se pide el token? Casi siempre POST.
login_content_type	¿Cómo se empaqueta lo que se manda? json o form.
login_body	Qué se manda para entrar. Es la parte que más cambia.
login_headers	¿Hace falta alguna cabecera extra en el login? Muchos sistemas no piden ninguna.
token_path	Dónde viene el token dentro de la respuesta.
auth_header_name	¿En qué cabecera va el token en cada petición?
auth_header_format	¿Cómo se escribe ahí dentro?
token_ttl_minutes	¿Cuánto se reutiliza el token antes de pedir otro?

Las cuatro que importan de verdad son login_body, token_path, auth_header_name y auth_header_format. Vamos una por una.

4 · El cuerpo del login: qué se manda para entrar

login_body es lo que tu sistema espera recibir en la petición de entrada. Se copia de su documentación, tal cual, con los nombres que él usa.

Si su documentación dice que hay que mandar esto:

{ "user": "…", "pass": "…" }

entonces tu login_body es exactamente eso, con las llaves dobles en lugar de los valores:

"login_body": { "user": "{{usuario}}", "pass": "{{clave}}" }

Las llaves dobles son huecos, no secretos

{{usuario}} no es el valor: es un hueco con nombre. El valor va en la lista de credenciales del paso siguiente, y ELYRA lo sustituye en el momento de entrar.

Esa separación es la que hace que esta descripción se pueda guardar, exportar y compartir sin que salga ni una contraseña. Nunca escribas un valor real aquí dentro.

Los nombres de los huecos los eliges tú; lo único que importa es que coincidan con los de la lista de credenciales. Y no tienen por qué ser dos: hay sistemas que piden una sola llave y otros que piden tres o cuatro.

"login_body": {
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "audience": "{{audience}}",
  "grant_type": "client_credentials"
}

Fíjate en grant_type: no lleva llaves. Es un valor fijo que ese sistema siempre espera igual, no un secreto. Lo que no cambia y no es secreto se escribe tal cual.

5 · Dónde viene el token: token_path

El sistema contesta al login con un paquete de datos. El token es uno de los campos de ese paquete, y token_path dice cuál.

Si tu sistema responde así:

{ "access_token": "eyJhbGciOi…", "expires_in": 3600 }

entonces token_path es access_token, que es lo que viene puesto.

Si el token viene anidado —dentro de otro campo— se escribe el camino separado por puntos:

{ "data": { "jwt": "eyJhbGciOi…" } }

"token_path": "data.jwt"

Y si tu sistema devuelve el token pelado, sin envolverlo en nada, quita la línea token_path entera. Sin ella, ELYRA busca los nombres habituales (access_token, token, jwt) y, si la respuesta no es un paquete de datos sino texto suelto, toma el texto.

6 · Cómo viaja el token después

auth_header_name y auth_header_format describen la otra mitad: ya con el token en la mano, cómo se manda en cada petición.

Lo que viene puesto es lo que usa la mayoría:

"auth_header_name": "Authorization",
"auth_header_format": "Bearer {token}"

Eso produce una cabecera que dice Authorization: Bearer eyJhbGciOi…. La palabra Bearer es una convención: significa «el que porta esto». Si la documentación de tu sistema pide otra cosa, se copia:

Si tu sistema pide	Escribes
Authorization: Token abc…	"auth_header_format": "Token {token}"
Authorization: abc… (sin prefijo)	"auth_header_format": "{token}"
X-Auth-Token: abc…	"auth_header_name": "X-Auth-Token" y "auth_header_format": "{token}"

Aquí {token} lleva UNA llave, no dos

Y no es un descuido. Las llaves dobles son tus credenciales; la llave simple {token} es el sitio donde ELYRA pone el token que acaba de recibir. Son dos cosas distintas y por eso se escriben distinto.

Los ocho campos se ven y se editan juntos en Avanzado · la forma del login, como datos, al final de la tarjeta:

Esa captura es un caso real y enseña dos cosas que esta guía explica: un auth_header_format que no es Bearer —ese sistema pide AR-JWT— y un login_headers con una cabecera que ese sistema exige en el login.

7 · Cuánto dura el token

token_ttl_minutes es cuánto tiempo reutiliza ELYRA el mismo token antes de pedir otro. Viene en 55 minutos.

Es una decisión nuestra, no un dato de tu sistema: si el tuyo dice que sus tokens duran una hora, 55 minutos deja margen de sobra. Si duran menos, bájalo. Ponerlo más alto de lo que el sistema aguanta hace que algunas peticiones fallen con el token ya vencido.

8 · Las credenciales

Debajo de la forma de login está la lista de credenciales: los valores reales de los huecos que escribiste con llaves dobles.

Cada fila es un nombre y un valor. El nombre es el del hueco —usuario, client_secret, audience— y el valor es el dato de verdad.

Tres cosas que conviene saber:

• No son «usuario y contraseña». Son llaves libres: tantas como tu sistema pida, con los nombres que él use.
• Se guardan cifradas y no se vuelven a mostrar. Al reabrir la ficha, una credencial guardada aparece con puntos; dejar el campo vacío es lo que hace que no se cambie.
• Si falta alguna, el portal te lo dice antes de salir a la red, nombrando cuál: «tu forma de login usa «audience» y no está en la lista».

9 · Probar

Pulsa Probar conexión. ELYRA ejecuta el login de verdad contra tu sistema, descartando cualquier token que tuviera guardado.

Eso es a propósito, y es lo que separa esta comprobación de una inútil: sondear la dirección base no prueba nada, porque muchos sistemas contestan amablemente a cualquiera que llame a su puerta principal y solo rechazan cuando se les pide algo de verdad. La única forma de saber que las credenciales sirven es usarlas.

Si algo falla, el mensaje trae el motivo que dio tu sistema, en sus palabras. No lo traducimos ni lo adornamos: es información suya y cambiarla sería inventar.

Tercera parte · La otra manera: llave fija

Algunos sistemas no tienen login: entregan una llave permanente y basta con incluirla en cada petición.

Para esos, la forma de login se queda sin token_url y sin login_body, con solo la parte de cómo viaja:

{
  "auth_header_name": "X-API-Key",
  "auth_header_format": "{token}"
}

Y en la lista de credenciales, una sola fila llamada token con el valor de la llave.

Sin login, «Probar» solo puede decir la mitad

Si no hay login que ejecutar, ELYRA sondea la dirección base y lo único que puede afirmar es que no rechazó la credencial. La prueba de verdad la da la primera operación de consulta que crees.

Y un aviso: si dejas una URL de login puesta por error, ELYRA intentará loguearse contra ella y fallará. Sin login, ese campo va vacío.

Guardar la forma para reutilizarla

Cuando tengas el login funcionando, puedes guardar esa forma con un nombre. Queda disponible en el primer campo para el siguiente sistema que conectes.

Lo que se guarda es la forma, jamás los valores: los secretos viven en la lista de credenciales, que no viaja. Por eso una forma guardada se puede exportar y pasársela a otra persona sin riesgo.

Y después, las operaciones

Un sistema conectado todavía no hace nada: solo es una puerta con su llave. Lo que se puede pedir por esa puerta —consultar un caso, crear uno, cambiar su estado— se define en las operaciones, que es la guía siguiente.

Si algo no funciona

«Falta la llave X». Tu forma de login usa un hueco {{X}} que no está en la lista de credenciales. Añádelo con ese nombre exacto — las llaves dobles y el nombre de la fila tienen que coincidir letra por letra.

El login responde pero ELYRA dice que no encuentra el token. El token viene en un campo distinto del que dice token_path. Mira la respuesta real de tu sistema y escribe el camino completo, con puntos si está anidado.

Las peticiones fallan aunque el login funcione. Mira la cabecera: el sistema puede esperar el token con otro prefijo, o en otra cabecera. Revisa auth_header_name y auth_header_format contra su documentación.

Funciona un rato y luego empieza a fallar. El token caduca antes de lo que dice token_ttl_minutes. Bájalo.

Falla siempre, y el mensaje habla de credenciales. Antes de revisar la clave, comprueba que no sobre una URL de login en un sistema de llave fija: ahí ELYRA intenta un login que ese sistema no tiene.

Dejó de responder y antes iba bien. Comprueba si alguien apagó el sistema en su ficha. Un sistema apagado no es un sistema roto: se apaga a propósito cuando se da de baja, y ELYRA lo dice como aviso, no como error.