Invocar Servicios Web Desde el Flujo del Proceso

Flokzu permite conectar tus procesos con sistemas externos mediante servicios web para automatizar el intercambio de información.

Casos de uso frecuentes:

• Sincronización de datos: Enviar automáticamente la información de un formulario (ej. un candidato seleccionado) a otros sistemas de la empresa (como un software de RRHH).
• Consulta de información: Obtener datos externos en tiempo real (ej. tipos de cambio o estados crediticios) e insertarlos directamente en el formulario.
• Disparar acciones externas: Ejecutar operaciones en terceros sistemas (ej. procesar un pago o dar de alta un usuario) tras una aprobación en el flujo.

¿Cómo invocar un Web Service desde el flujo del proceso?

Para invocar un Web Service desde el flujo del proceso, lo primero que debes hacer es colocar una Tarea de Servicio en la etapa del workflow el la cual deseas realizar la invocación y seleccionar la opción REST

Finalmente, debes configurar el Web Service que deseas invocar con lo siguientes pasos:

1. Introducir la URL y el tipo de servicio (método) que deseas invocar
2. Configurar los datos de entrada que se enviarán al Web Service
3. Configurar los datos de salida que se reciben del Web Service y pueden cargarse en campos de formulario en Flokzu.
4. Configurar los Encabezados HTTP (opcional), por temas de seguridad, por ejemplo.
5. Configurar el Manejo de Errores
6. Por último puedes seleccionar la autenticación que utiliza tu servicio en la pestaña Autenticaciones.

1. Configurar URL y método

Escribe o pega la URL del servicio (endpoint) que deseas invocar y selecciona el método en la lista de la derecha.

En caso de que sea necesario hacer referencia al contenido de un campo del formulario en la URL del webservice, se debe hacer utilizando mustaches {{Nombre Campo}}.

Los métodos soportados son:

• GET
• PUT
• POST
• DELETE

2. Configurar datos de entrada (Body de la llamada)

Para cada parámetros de entrada Flokzu te permite insertar el contenido de los campos de tu formulario o enviar valores literales. Haz clic en el ícono con forma de lápiz para alternar entre las dos opciones.

Los parámetros serán traducidos automáticamente en el body de la llamada, excepto cuando se utiliza el método GET en donde serán enviados como queryParam.

Veamos algunos ejemplos:

Con método GET los parámetros de entrada son enviados en la URL. Una configuración como la siguiente

invocará a la siguiente URL:

https://api.myapp.com/v1/service?param1=value_1&param2=value_2

Con métodos PUT, POST y DELETE, una configuración como la siguiente

enviará el siguiente JSON en el request:

{
    "param1":"value_1",
    "param2":"value_2"
}

Personalización del Body de la llamada

Es posible personalizar la llamada del servicio escribiendo directamente el body o indicando que los parámetros se deben enviar como url-encoded

RAW

La opción raw te permite escribir directamente el JSON de entrada. Además, utilizando mustaches podrás insertar el contenido de un campo del formulario directamente en el body.

URL-ENCODED

Si tu servicio requiere el envío de datos como url-encoded, selecciona la opción x-www-form-urlencoded dentro de la pestaña Parámetros de Entrada. Luego podrás agregar el par parámetro - valor

FORM-DATA

Form-data hace referencia a una forma de comunicación entre servicios web, donde los datos se envían como parejas clave/valor. Si bien es útil para enviar cualquier tipo de dato (texto, números, valores booleanos), es además el único mecanismo que soporta la codificación "multipart/form-data", necesario para poder enviar archivos adjuntos.

3. Configurar datos de salida (Body de la respuesta)

Flokzu admite dos tipos de respuesta en los servicios que deberás elegir en la pestaña Datos de Salida:

• RAW: La respuesta del servicio REST debe ser un JSON válido. Puedes comprobar el JSON utilizando la siguiente web http://jsonviewer.stack.hu/
• BINARY: Un archivo que podrás adjuntar en la Pestaña Adjuntos o en un campo del formulario.

RAW

Luego de elegir esta opción deberás indicar el nombre del parámetro del JSON de respuesta al que deseas acceder, y en la columna de la derecha el campo del formulario donde deseas insertar ese valor.

Supongamos que este es el JSON de salida:

{
  "nombre": "Ejemplo de JSON",
  "descripcion": "Este es un ejemplo de JSON con varios niveles y datos dentro de un array.",
  "autor": {
    "nombre": "Juan Pérez",
    "edad": 35,
    "activo": true
  },
  "valores": [10, 20, 30, 40],
  "usuarios": [
    {
      "id": 1,
      "nombre": "Alice",
      "email": "alice@example.com",
      "activo": true,
      "roles": ["administrador", "usuario"]
    },
    {
      "id": 2,
      "nombre": "Bob",
      "email": "bob@example.com",
      "activo": false,
      "roles": ["usuario"]
    }
  ]
}

A continuación veremos como configurar los parámetros de salida para acceder a algunas de las propiedades.

BINARY

Si el servicio web que estás invocando devuelve en su respuesta un archivo, podrás adjuntarlo en tu instancia de proceso. Luego de seleccionar la opción Binary, deberás elegir de la lista el campo donde se guardará el adjunto.

4. Configurar Encabezados HTTP

Introduce los Encabezados HTTP (opcional), por temas de seguridad, por ejemplo.

5. Manejo de Errores

¿Por qué configurar el manejo de errores?

En integraciones con sistemas externos, es común que un servicio no responda con un éxito (200 OK) debido a datos inválidos, falta de stock o caídas temporales del servidor externo. Sin una gestión de errores, el proceso ignora estas respuestas técnicas, dificultando que el usuario de negocio sepa qué falló. Al configurar el Manejo de Errores, transformas un fallo técnico en información accionable, permitiendo que el flujo del proceso sea resiliente y capaz de corregirse a sí mismo.

Cómo configurar el Manejo de Errores

Dentro de la configuración de tu Tarea de Servicio (REST), encontrarás la pestaña "Manejo de errores". Para activarla, sigue estos pasos:

1. Activar el interruptor "Procesar errores": Por defecto está en OFF. Al activarlo, Flokzu permitirá capturar la respuesta del servicio cuando el código HTTP sea de error.
2. Seleccionar el Tipo de error: Elige si deseas gestionar errores 4XX (errores de cliente/datos, como un campo mal formado) o 5XX (errores de servidor externo).
3. Configurar la Tabla de Mapeo: Al igual que en las respuestas exitosas, define qué dato del JSON de error quieres guardar y en qué campo del formulario.

Obtener el código HTTP de la respuesta

Adicionalmente a la respuesta del servicio web, Flokzu agrega una propiedad flokzu_ws_status que devuelve el código HTTP del error (ej: 400, 503). En ocasiones este parámetro puede ser útil para configurar Gateways condicionales posteriores. Para utilizarlo, simplemente agrega** flokzu_ws_status **en la tabla de mapeo y establece un campo de destino.

Casos de uso típicos

• Validación de Documentos: Si un servicio de validación de identidad devuelve un error 400 porque el documento es inválido, puedes capturar el mensaje de error y redirigir el flujo a una tarea de usuario para que el solicitante corrija el dato.
• Integración Bancaria: Ante un error 500 de un banco, puedes capturar el estado, notificar automáticamente al equipo de TI y programar un reintento del proceso tras un tiempo de espera.
• Gestión de Stock: Si una API de inventario responde que no hay existencias, el mensaje de error puede mostrarse directamente en el formulario para que el aprobador tome una decisión informada.

Buenas prácticas para el mapeo

1. Usa campos ocultos para códigos: Mapea los códigos de error técnicos (como INVALID_API_KEY) a campos ocultos y usa los mensajes descriptivos para los campos que verá el usuario final.
2. Define rutas alternativas en el Workflow: Siempre que configures el manejo de errores, utiliza un Gateway Exclusivo inmediatamente después de la Service Task que evalúe el valor de flokzu_ws_status.
3. Mapeo de JSON Path simple: Utiliza la notación de puntos (ej. response.error_details[0].description) para llegar al dato exacto. Asegúrate de que el campo de destino en Flokzu coincida con el tipo de dato que esperas recibir (Texto, Número, etc.).
4. No ignores el Monitor de Errores: Aunque el proceso ahora capture el error y continúe, el fallo seguirá registrándose en el Monitor de Errores de Flokzu para auditoría técnica.

6. Configurar Autenticaciones

Por último, si tu servicio tiene algún mecanismo de seguridad, puedes seleccionar la autenticación que utiliza tu servicio en la pestaña Autenticaciones.

Comportamiento de la ejecución

En Flokzu, las Tareas de Servicio se ejecutan de manera síncrona. Esto significa que cuando el flujo llega a este paso, el proceso se detiene y espera la respuesta del sistema externo antes de avanzar a la siguiente etapa.

El comportamiento del motor de procesos dependerá del resultado de la invocación y de tu configuración:

1. Respuesta Exitosa (Rango 200-299)

• Se aplica el mapeo definido en la pestaña Datos de Salida.
• El parámetro flokzu_ws_status devolverá siempre el código numérico 200.

2. Respuesta de Error (Códigos 4XX o 5XX)

En caso de error, el comportamiento varía según si has activado el Manejo de Errores:

• Si el Manejo de Errores está ACTIVADO:
• • Se ignora por completo la pestaña Datos de Salida.
  • Se aplica únicamente el mapeo configurado en la pestaña Manejo de Errores.
  • Para obtener el código de error (ej. 404), debes mapear flokzu_ws_status explícitamente dentro de esta pestaña.
• Si el Manejo de Errores está DESACTIVADO (Comportamiento por defecto):
• • Se ignora el mapeo de campos de Datos de Salida.
  • Excepción: El parámetro flokzu_ws_status sí se procesará si fue configurado en Datos de Salida, devolviendo el código de error correspondiente (ej. 500) para que puedas usarlo en gateways posteriores.

¿Existe alguna forma más simple de integrar Flokzu con otras aplicaciones?

Si no tienes conocimientos técnicos sobre integraciones o simplemente deseas configurar la integración rápidamente y de manera sencilla, puedes utilizar un conector como Zapier. Simplemente coloca una Tarea de Servicio en el workflow, selecciona “Zapier” y sigue los pasos para integrar Flokzu y Zapier. Una vez configurada la integración, podrás conectar Flokzu con más de 6.000 apps (Facebook, Google Drive, Gmail, SalesForce, etc).

Actualizado el: 17/03/2026