Integraciones Manuales
Las integraciones manuales te permiten conectar cualquier servicio web, o incluso tu propio servicio, con Kosmos, para utilizarlos posteriormente en tus flujos a través de Business. Logic. Las integraciones manuales funcionan con peticiones que se hacen al servicio web, y respuestas cuyos datos puedes utilizar en tu flujo.
Las peticiones pueden realizarse con parámetros de entrada. Es decir, solicitar una respuesta en función de variables del flujo.
Las integraciones manuales se dividen en REST y SOAP y las respuestas que puedes obtener de una integración manual pueden ser:
JSON
XML
TEXT
La configuración de una integración manual se divide en tres pasos:
¿Cómo agregar una integración manual REST sin parámetros?
Haz clic en la opción “Integraciones manuales” del menú de módulos.
Haz clic en “Agregar integración”.
En “Detalles” haz clic en “Ver más”.
En “Tipo de servicio” marca el checkbox de “REST”
En “Nombre de la integración” escribe el nombre que le vas a asignar a la integración.
En “Descripción de la integración”, redacta una pequeña descripción del servicio web.
(Opcional) Activa el Checkbox de “Usar distintas configuraciones para vista previa y publicar” si vas a configurar en Endpoint distinto para cada ambiente.
En “Configuración” haz clic en “Ver más”.
(Opcional) Si activaste la función “Usar distintas configuraciones para vista previa y publicar” selecciona una pestaña del ambiente que vas a configurar. Para cada ambiente sigue los siguientes pasos.
En “Endpoint” ingresa la URL que vas a utilizar para acceder al servicio web.
En “Timeout” ingresa el tiempo (en segundos) límite para esperar la respuesta.
En “Método HTTP” elige el método HTTP con el que te vas a comunicar con el servicio web. Las opciones disponibles son:
GET: este método se utiliza para solicitar datos de un servidor web.
POST: este método se utiliza para enviar datos a un servidor web.
PUT: este método se utiliza para actualizar información en un servidor web.
DELETE: este método se utiliza para eliminar información de un servidor web.
HEAD: este método es similar al método GET, pero solo solicita la información de encabezado de una respuesta del servidor web.
PATCH: este método se utiliza para realizar cambios parciales en la información en un servidor web.
En “Tipo de respuesta esperada” selecciona el tipo de respuesta que esperas. Las opciones son JSON, XML y TEXT.
Haz clic en “Siguiente” para ir a “Prueba tu servicio”.
(Opcional) Si activaste la función “Usar distintas configuraciones para vista previa y publicar” elige la pestaña con el ambiente que vas a probar.
En “Params”, opcionalmente, puedes agregar parámetros para probar el servicio.
En “Authentication”, agrega el método de autenticación indicado por el sitio web. En caso de no necesitar un método de autenticación, deja la opción predeterminada “No Auth”.
En “Headers”, en caso de que el servicio web solicita headers, agrégalos en esta pestaña:
Haz clic en “+Agregar Header”.
En la columna Key, escribe el nombre de tu Header.
En la columna Value, escribe el valor del Header.
Repite el proceso para todos los Headers.
En caso que la integración sea de tipo “PUT”, agrega tu body en la pestaña “Body”.
Haz clic en “Probar” y comprueba que la respuesta de tu servicio es correcta.
(Opcional) Si activaste la función “Usar distintas configuraciones para vista previa y publicar” los botones son diferentes
“Probar vista previa” para probar la configuración del ambiente vista previa.
“Probar publicar” para probar la configuración del ambiente de producción.
Haz clic en “Siguiente” para ir a “Funciones de Parseo”.
En “Función” escribe tu código utilizando SimpleVariables o ComplexVariables (según tus necesidades).
Para funciones complejas, puedes complementar con Código JavaScript.
En “Test”, corrobora que el código coincide con el body que obtuviste en “Prueba tu servicio.
Haz clic en “Ejecutar”.
En “Resultado”, comprueba que las variables, arreglos u objetos que solicitaste con simpleVariables o complexVariables, son correctos.
Haz clic en “Finalizar” para guardar tu integración.
Si quieres editar o eliminar una integración haz clic en el ícono correspondiente.
“Eliminar” representado con un ícono de papelera.
“Editar” representado con un ícono de lápiz.
¿Cómo agregar una integración manual REST con parámetros?
Haz clic en la opción “Integraciones manuales” del menú de módulos.
Haz clic en “Agregar integración”.
En “Detalles” haz clic en “Ver más”.
En “Tipo de servicio” marca el checkbox de “REST”
En “Nombre de la integración” escribe el nombre que le vas a asignar a la integración.
En “Descripción de la integración”, redacta una pequeña descripción del servicio web.
(Opcional) Activa el Checkbox de “Usar distintas configuraciones para vista previa y publicar” si vas a configurar en Endpoint distinto para cada ambiente.
En “Parámetros de entrada” haz clic en “Ver más”.
Haz clic en “+Agregar nuevo parámetro”
En “Nombre del parámetro", asigna un nombre para tu parámetro.
En “Tipo de parámetro” despliega la lista y elige el tipo de parámetro. Las opciones son:
Cadena de caracteres
Número
Objeto
Arreglo
Booleano
Documento
Repite el proceso para todos los parámetros que necesites.
En “Configuración” haz clic en “Ver más”.
(Opcional) Si activaste la función “Usar distintas configuraciones para vista previa y publicar” selecciona una pestaña del ambiente que vas a configurar. Para cada ambiente sigue los siguientes pasos.
En “Endpoint” ingresa la URL que vas a utilizar para acceder al servicio web.
Si tus parámetros son QueryParams, agréganos en la URL del endpoint con la fórmula #parámetro. Por ejemplo: http://www.servicio.com/451356545?q=#parametro
En “Timeout” ingresa el tiempo (en segundos) límite para esperar la respuesta.
En “Método HTTP” elige el método HTTP con el que te vas a comunicar con el servicio web. Las opciones disponibles son:
GET: este método se utiliza para solicitar datos de un servidor web.
POST: este método se utiliza para enviar datos a un servidor web.
PUT: este método se utiliza para actualizar información en un servidor web.
DELETE: este método se utiliza para eliminar información de un servidor web.
HEAD: este método es similar al método GET, pero solo solicita la información de encabezado de una respuesta del servidor web.
PATCH: este método se utiliza para realizar cambios parciales en la información en un servidor web.
En “Tipo de respuesta esperada” selecciona el tipo de respuesta que esperas. Las opciones son JSON, XML y TEXT.
Haz clic en “Siguiente” para ir a “Prueba tu servicio”.
(Opcional) Si activaste la función “Usar distintas configuraciones para vista previa y publicar” elige la pestaña con el ambiente que vas a probar.
En “Params”, opcionalmente, puedes agregar parámetros para probar el servicio.
En la columna “PARÁMETRO” verás tus parámetros de entrada, escribe el valor para cada uno de tus parámetros en la columna “VALOR”.
Estos valores sólo son para probar el servicio.
En “Authentication”, agrega el método de autenticación indicado por el sitio web. En caso de no necesitar un método de autenticación, deja la opción predeterminada “No Auth”.
En “Headers”, en caso de que el servicio web solicita headers, agrégalos en esta pestaña:
Haz clic en “+Agregar Header”.
En la columna Key, escribe el nombre de tu Header.
En la columna Value, escribe el valor del Header.
Repite el proceso para todos los Headers.
En caso que la integración sea de tipo “PUT”, agrega tu body en la pestaña “Body”.
Haz clic en “Probar” y comprueba que la respuesta de tu servicio es correcta.
(Opcional) Si activaste la función “Usar distintas configuraciones para vista previa y publicar” los botones son diferentes
“Probar vista previa” para probar la configuración del ambiente vista previa.
“Probar publicar” para probar la configuración del ambiente de producción.
Haz clic en “Siguiente” para ir a “Funciones de Parseo”.
En “Función” escribe tu código utilizando SimpleVariables o ComplexVariables (según tus necesidades).
Para funciones complejas, puedes complementar con Código JavaScript.
En “Test”, corrobora que el código coincide con el body que obtuviste en “Prueba tu servicio.
Haz clic en “Ejecutar”.
En “Resultado”, comprueba que las variables, arreglos u objetos que solicitaste con simpleVariables o complexVariables, son correctos.
En integraciones con parámetros, recuerda que debes escribir tu código con el nombre de tus parámetros de entrada, para asignar un valor, o valores, de la respuesta, a ese parámetro.
Haz clic en “Finalizar” para guardar tu integración.
Si quieres editar o eliminar una integración haz clic en el ícono correspondiente.
“Eliminar” representado con un ícono de papelera.
“Editar” representado con un ícono de lápiz.
¿Cómo agregar una integración manual SOAP sin parámetros?
Haz clic en la opción “Integraciones manuales” del menú de módulos.
Haz clic en “Agregar integración”.
En “Detalles” haz clic en “Ver más”.
En “Tipo de servicio” marca el checkbox de “SOAP”
En “Nombre de la integración” escribe el nombre que le vas a asignar a la integración.
En “Descripción de la integración”, redacta una pequeña descripción del servicio web
(Opcional) Activa el Checkbox de “Usar distintas configuraciones para vista previa y publicar” si vas a configurar en Endpoint distinto para cada ambiente.
En “Configuración” haz clic en “Ver más”.
Si el servicio web requiere un VPN para una conexión encriptada, activa la función “Habilitar VPN”.
Ingresa tu “Host Remoto del Túnel”.
Ingresa tu “Puerto Remoto del Túnel”.
En “WSDL URL” ingresa la URL del WSDL del servicio.
Haz clic en el botón “Obtener WSDL”.
En “Timeout” ingresa el tiempo (en segundos) límite para esperar la respuesta.
En “Operaciones”, comprueba que el XML es correcto.
Haz clic en “Siguiente” para ir a “Prueba tu servicio”.
Puedes modificar el XML si lo deseas para realizar la prueba
Haz clic en el botón “Probar”.
Haz clic en “Siguiente” para ir a “Funciones de Parseo”.
En “Función” escribe tu código utilizando SimpleVariables o ComplexVariables (según tus necesidades).
Para funciones complejas, puedes complementar con Código JavaScript.
En “Test”, corrobora que el código coincide con el body que obtuviste en “Prueba tu servicio.
Haz clic en “Ejecutar”.
En “Resultado”, comprueba que las variables, arreglos u objetos que solicitaste con simpleVariables o complexVariables, son correctos.
Haz clic en “Finalizar” para guardar tu integración.
Si quieres editar o eliminar una integración haz clic en el ícono correspondiente.
“Eliminar” representado con un ícono de papelera.
“Editar” representado con un ícono de lápiz.
¿Cómo agregar una integración manual SOAP con parámetros?
Haz clic en la opción “Integraciones manuales” del menú de módulos.
Haz clic en “Agregar integración”.
En “Detalles” haz clic en “Ver más”.
En “Tipo de servicio” marca el checkbox de “SOAP”
En “Nombre de la integración” escribe el nombre que le vas a asignar a la integración.
En “Descripción de la integración”, redacta una pequeña descripción del servicio web.
(Opcional) Activa el Checkbox de “Usar distintas configuraciones para vista previa y publicar” si vas a configurar en Endpoint distinto para cada ambiente.
En “Configuración” haz clic en “Ver más”.
Si el servicio web requiere un VPN para una conexión encriptada, activa la función “Habilitar VPN”.
Ingresa tu “Host Remoto del Túnel”.
Ingresa tu “Puerto Remoto del Túnel”.
En “WSDL URL” ingresa la URL del WSDL del servicio.
Haz clic en el botón “Obtener WSDL”.
En “Timeout” ingresa el tiempo (en segundos) límite para esperar la respuesta.
En “Operaciones”, comprueba que el XML es correcto.
En “Parámetros de entrada” haz clic en “Ver más”.
Haz clic en “+Agregar nuevo parámetro”
En “Nombre del parámetro", asigna un nombre para tu parámetro.
En “Tipo de parámetro” despliega la lista y elige el tipo de parámetro. Las opciones son:
Cadena de caracteres
Número
Objeto
Arreglo
Booleano
Documento
Repite el proceso para todos los parámetros que necesites.
Haz clic en “Siguiente” para ir a “Prueba tu servicio”.
Puedes modificar el XML si lo deseas para realizar la prueba
En la columna “PARÁMETRO” verás tus parámetros de entrada, escribe el valor para cada uno de tus parámetros en la columna “VALOR”.
Estos valores sólo son para probar el servicio.
Haz clic en el botón “Probar”.
Haz clic en “Siguiente” para ir a “Funciones de Parseo”.
En “Función” escribe tu código utilizando SimpleVariables o ComplexVariables (según tus necesidades).
Para funciones complejas, puedes complementar con Código JavaScript.
En “Test”, corrobora que el código coincide con el body que obtuviste en “Prueba tu servicio.
Haz clic en “Ejecutar”.
En “Resultado”, comprueba que las variables, arreglos u objetos que solicitaste con simpleVariables o complexVariables, son correctos.
Haz clic en “Finalizar” para guardar tu integración.
Si quieres editar o eliminar una integración haz clic en el ícono correspondiente.
“Eliminar” representado con un ícono de papelera.
“Editar” representado con un ícono de lápiz.
Preguntas frecuentes
¿Qué significa x-www-form-urlencoded?
Es un tipo de codificación de datos utilizada para enviar datos de formulario en una solicitud HTTP. Cuando se utiliza esta codificación, los datos se envían en el cuerpo de la solicitud en formato de texto plano, donde cada campo y su valor se separan con el carácter "&", y el nombre del campo y su valor se separan con el signo igual "=".
Por ejemplo, si se está enviando información de un formulario que contiene el campo "nombre" con el valor "Juan" y el campo "edad" con el valor "30", la solicitud codificada en x-www-form-urlencoded se vería así:
nombre=Juan&edad=30
Esta codificación es ampliamente utilizada en aplicaciones web y en integraciones de servicios web REST, ya que es fácil de leer y procesar tanto para el cliente como para el servidor. Además, la mayoría de los lenguajes de programación tienen funciones incorporadas para codificar y decodificar datos en este formato.