Las operaciones REST

Conectar un sistema abre la puerta. Una operación es cada cosa concreta que se puede pedir por ella: consultar un caso, crear un caso, cambiar su estado, buscar las citas de alguien.

Una operación son dos mitades, y conviene tenerlas separadas en la cabeza desde el principio:

1. La petición — qué se le pide al sistema.
2. La respuesta — cómo se convierte lo que contesta en algo que una persona pueda leer en un chat.

La segunda mitad es la que más se subestima. Un sistema contesta para otro programa; una persona necesita una frase.

Esta guía cubre las operaciones contra un sistema que se habla por API REST. Un sistema que se hable de otra manera tendrá sus propias operaciones y su propia guía.

Antes de empezar

• El sistema ya conectado y probado — ver Conectar un sistema REST.
• Saber qué le vas a pedir: la documentación del sistema te dirá a qué dirección y con qué verbo.

La regla que ahorra la mitad del trabajo

No adivines la respuesta: pruébala. La pantalla trae un botón de probar que ejecuta la operación de verdad, y a partir de ahí el portal ya sabe qué devuelve tu sistema y te deja elegir los datos de una lista en vez de escribirlos a mano. Arma la petición, prueba, y luego escribe los mensajes.

Primera parte · La petición

1 · Nombre y sistema

En Operaciones, pulsa Nueva operación.

• Nombre — se usa en dos sitios: para reconocerla, y para llamarla desde una capacidad. Tiene que ser único, y conviene que diga lo que hace: Consultar caso, Crear caso.
• Sistema destino — la puerta por la que sale.

2 · Método y ruta

El método es el verbo de la petición, y los sistemas REST usan siempre los mismos cuatro o cinco:

Verbo	Qué significa
GET	Consultar. No cambia nada.
POST	Crear algo nuevo.
PUT / PATCH	Modificar algo que ya existe.
DELETE	Borrar.

La ruta es lo que se le añade a la dirección base del sistema. Si la base es https://mi-sistema.com/api y la ruta es /casos, la petición sale a https://mi-sistema.com/api/casos.

La ruta puede llevar huecos, escritos entre llaves dobles:

/casos/{{numero_caso}}

Ese hueco se rellena en el momento con un dato de la conversación. De dónde salen esos datos lo vemos en el paso 5.

3 · Los parámetros de consulta

Es lo que va después del ? en una dirección: los filtros. Si su documentación dice que para traer solo los casos abiertos hay que pedir

/casos?estado=Abierto&limite=5

entonces la ruta es /casos y los parámetros son lo de después:

estado=Abierto&limite=5

Se pegan tal cual, y también admiten huecos: estado={{estado}}.

4 · El cuerpo de la petición

Solo para POST, PUT y PATCH: un GET no lleva cuerpo.

El cuerpo es el paquete de datos que se manda. Se copia de la documentación del sistema, con su forma exacta, y se ponen huecos donde van los datos que cambian:

{
  "values": {
    "Description": "{{descripcion}}",
    "Reported Source": "Chat",
    "Customer": "{{correo}}"
  }
}

Fíjate en "Reported Source": "Chat": no lleva llaves. Es un valor fijo, igual en todas las peticiones. Lo que no cambia se escribe tal cual; los huecos son solo para lo que viene de la conversación.

La forma la manda el sistema, no ELYRA

Si su documentación anida los campos dentro de values, tú anidas dentro de values. ELYRA no reordena ni traduce el paquete: lo manda como lo escribas. Copiar el ejemplo de su documentación y sustituir los valores por huecos es el camino más corto y el que menos falla.

5 · De dónde salen los huecos

Un hueco {{algo}} se rellena, en este orden, con lo primero que exista:

• Lo que la conversación ya recogió — si antes se le preguntó a la persona «¿cuál es el número del caso?», ese dato está disponible.
• Lo que produjo otra operación anterior en la misma conversación.
• Lo que ELYRA sabe siempre sin preguntarlo: quién escribe ({{remitente}}), por qué canal ({{canal}}), y la fecha y la hora.

No hace falta declarar nada: si el nombre coincide, se rellena.

6 · Archivos

En POST, PUT y PATCH aparece Campo del archivo. Es para cuando la persona manda una foto o un documento por el chat y hay que hacerlo llegar al sistema: se escribe el nombre del campo con el que ese sistema recibe archivos (attachment, file…). Vacío significa que esta operación no lleva archivos.

Segunda parte · Probar

Antes de escribir un solo mensaje, baja a Probar y ejecútala.

Se ejecuta de verdad contra el sistema. Eso importa saberlo: si estás probando un POST que crea casos, vas a crear un caso real.

La prueba devuelve dos cosas, y las dos sirven:

• La petición ya armada, con los huecos rellenos. Es la forma de ver qué se mandó de verdad, sin adivinar.
• La respuesta completa del sistema. A partir de aquí, el portal ya conoce los datos que devuelve y te los ofrece en listas en vez de pedirte que escribas rutas a ciegas.

Tercera parte · La respuesta

Aquí es donde una respuesta para máquinas se vuelve una frase para personas.

7 · Guardar datos con un nombre

Un sistema responde algo así:

{
  "entries": [{
    "values": {
      "Incident Number": "INC000000123",
      "Status": "Assigned",
      "Assignee": "Ana Pérez"
    }
  }]
}

Eso no se le enseña a nadie. Lo que se hace es sacar los datos que importan y ponerles un nombre: le dices a ELYRA «al dato que está en tal sitio llámalo numero_caso», y a partir de ahí {{numero_caso}} sirve en cualquier mensaje.

Si has ejecutado la prueba, el portal ya tiene la respuesta delante y eliges los datos de una lista. Si no, hay que escribir la ruta a mano.

El nombre va a la izquierda, la ruta a la derecha

Se lee «a esto lo llamo así», no al revés. Escrito al revés no da error: simplemente no encuentra nada, y el mensaje sale con sus {{llaves}} sin resolver. Es el tropiezo más común de esta pantalla.

Dos cosas que este paso no sabe hacer, porque no le corresponden:

• No cuenta. «Cuántos elementos tiene la lista» no es un dato que esté en la respuesta.
• No traduce. Un true se pinta «True», y eso no se le dice a nadie.

Cuando la respuesta no trae el dato en una forma que una persona pueda leer, lo correcto es que lo responda así el sistema. ELYRA no inventa datos que no le dieron.

8 · Cuando la respuesta trae varias cosas

Para una consulta que devuelve una lista —los casos abiertos de alguien, las citas de mañana— está el apartado Listado. Se activa con su interruptor y pide cuatro cosas:

• La lista — cuál de las listas de la respuesta es. Tras la prueba, el portal las detecta y las ofrece con cuántos elementos trae cada una.
• Cómo se ve cada uno — se escribe como quieres que lo lea la persona y se insertan los datos del elemento haciendo clic.
• Cuántos como máximo — en un chat, más de cinco se vuelve ilegible.
• Si no hay ninguno — lo que se responde cuando la lista viene vacía. Sin esto, una búsqueda sin resultados deja a la persona sin respuesta.

Hay una vista previa que enseña cómo va a quedar.

9 · Los tres mensajes

Una operación habla por tres bocas, y son distintas a propósito.

El mensaje de éxito es lo que le llega a la persona cuando todo salió bien. Se escribe en castellano normal, insertando los datos del paso 7:

Listo. Tu caso quedó registrado con el número {{numero_caso}} y está {{estado}}.

El mensaje de error es para cuando el sistema respondió que no. Puede incluir el motivo que dio el sistema, tal cual, en sus palabras.

El mensaje de «no se pudo confirmar» es el que casi nadie espera y el que más importa.

Un timeout no es un fallo: es una incógnita

Si el sistema no contesta a tiempo, no se sabe qué pasó. Puede que no le llegara la petición… o puede que el caso se haya creado perfectamente y solo se perdiera la respuesta.

Decirle a la persona «falló» la llevaría a intentarlo otra vez, y ahí es donde aparecen dos casos idénticos. Por eso hay un tercer mensaje, que dice la verdad —no se pudo confirmar— sin invitar a repetir.

Y por eso mismo ELYRA solo reintenta sola las operaciones que consultan. Un POST no se reintenta nunca: repetir una creación es crear dos.

Si lo dejas vacío, sale el texto de fábrica de tus voces.

Cuarta parte · Qué hace, y si se confirma

Cada operación declara qué hace en el sistema, y de eso sale si ELYRA pregunta «¿confirmas?» antes de ejecutarla. Son tres niveles, y los eliges en el selector Qué hace, junto al método:

Qué hace	Qué significa	Qué hace ELYRA
Consulta	Mira. No cambia nada en el sistema.	Ejecuta directo, sin preguntar.
Añade	Crea algo que después se puede tachar: un caso, una nota, una cita.	Pide confirmación antes de ejecutar.
Cambia o borra	Toca lo que ya había: cierra, cancela, modifica, elimina.	Pide confirmación cada vez, una por una. Ninguna aprobación anterior la cubre.

Léelo así: cuanto menos se pueda deshacer lo que hace la operación, menos margen tiene ELYRA para ejecutarla por su cuenta.

Al crear la operación, el nivel nace sugerido por el método: un GET nace como consulta y el resto como «cambia o borra». Es solo el punto de partida. Quien sabe qué hace la operación de verdad la ajusta: un POST que solo abre un caso se baja a «añade»; una consulta que cuesta dinero se puede subir para que pregunte. Lo que no se declara se trata como «cambia o borra»: ante la duda, ELYRA pregunta.

Debajo del selector hay una casilla, «Repetirla no duplica nada». Marcada, si la red se corta a medias ELYRA vuelve a intentar la llamada; sin marcar, no lo hace, porque repetir un «crear» que sí llegó abriría dos registros. También nace según el método y se corrige a mano.

El documento de cada capacidad enseña el nivel junto al servicio que la llama.

Quién ve cómo está hecha

Una operación se puede marcar privada. Entonces solo las personas que tú dejes entrar ven cómo está hecha —la ruta, el cuerpo, las plantillas—; el resto la ve en la lista, sabe para qué sirve, y la puede usar desde cualquier capacidad.

Sirve para lo de siempre: que un integrador arme la parte técnica y el resto del equipo la use sin poder romperla.

Si algo no funciona

El mensaje llega con {{llaves}} sin resolver. El dato no se extrajo. Casi siempre es el nombre y la ruta puestos al revés, o una ruta que no coincide con lo que el sistema devuelve. Ejecuta la prueba y elige el dato de la lista.

La prueba funciona y en la conversación falla. En la prueba pusiste los datos a mano; en la conversación tienen que venir de algún sitio. Comprueba que lo que rellena cada hueco se le haya preguntado antes a la persona, o lo produzca una operación anterior.

El sistema devuelve un error que no entiendo. Es el mensaje del sistema destino, en sus palabras. No lo traducimos: es información suya y cambiarla sería inventar. La respuesta completa queda en el registro de llamadas.

Se crean casos duplicados. Alguien está reintentando tras un timeout. Para eso está el mensaje de «no se pudo confirmar»: si está vacío o si dice «falló», la persona lo va a repetir.

Una lista sale cortada. Está el máximo de elementos, y encima manda el límite del canal: WhatsApp y los demás tienen su propio tope de cuántas opciones caben en un mensaje.

No puedo borrar una operación. Si alguna capacidad la usa, ELYRA se niega y te dice quién la está usando. Primero se quita de ahí.