> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://docs.flokzu.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # 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** ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/ws_cjc8se.gif) 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). 5. Configurar el Manejo de Errores 6. Por último puedes seleccionar la [autenticación que utiliza tu servicio](/es/article/autenticacion-de-servicios-rest-cezrf3/) 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. ![](https://storage.crisp.chat/users/helpdesk/website/5a899047-9b38-48ab-9475-31c8c63a3183/4606adf7-571c-4fd8-a898-a06c1ca93f2b.png) 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 * PATCH * DELETE ||| Los *queryParam* deben ser incluidos explícitamente en la URL, excepto en el caso de métodos GET que los tomará de los parámetros de entrada (ver el punto 2) ## 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. ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_1pjh7ke.png) 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 ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_5qja4i.png) invocará a la siguiente URL: https://api.myapp.com/v1/service?param1=value_1¶m2=value_2 Con métodos **PUT, POST, PATCH y DELETE**, una configuración como la siguiente ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_15iyhso.png) enviará el siguiente JSON en el *request*: ```json { "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. ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_mcsb4k.png) | Para habilitar los mustaches debes escribir un espacio seguido por una doble llave: " {{" ###### 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* ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_uls280.png) ###### 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](/es/article/enviar-y-recibir-archivos-adjuntos-por-web-service-9ze1bw/). | Si seleccionas esta opción y no agregas un encabezado *Content-Type*, Flokzu agregará automáticamente este encabezado con valor *multipart/form-data* ## 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/](http://jsonviewer.stack.hu/) * **BINARY**: Un archivo que podrás adjuntar en la [Pestaña Adjuntos](/es/article/pestana-adjuntos-17yrlyk/) o en un [campo del formulario](/es/article/campo-tipo-adjunto-1u5qx49/). ###### 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: ```json { "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"] } ] } ``` | Puedes obtener los distintos valores navegando entre las propiedades utilizando un punto (.) o indicando el índice de los arreglos entre paréntesis rectos. A continuación veremos como configurar los parámetros de salida para acceder a algunas de las propiedades. ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_1x51ea1.png) | Caso de uso | Configuración | Valor retornado | | ---- | | Propiedad en el primer nivel | nombre | *Ejemplo de JSON* | | Propiedad en segundo nivel | autor.activo | *true* | | Valor dentro de un arreglo | valores[2] | *30* | | Navegación dentro de arreglos | usuarios[0].roles[0] | *administrador* | | Navegación dentro de arreglos y propiedades | usuarios[1].nombre | *Bob* | ###### 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. ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/unnamed_9mbvfd.png) ## 4. Configurar Encabezados HTTP Introduce los Encabezados HTTP (opcional), por temas de seguridad, por ejemplo. ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/imagen_1tej7go.png) ## 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 ![](https://storage.crisp.chat/users/helpdesk/website/-/c/c/c/3/ccc3fbb5dc442800/manejoerroreses_xjz3jn.gif) 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. | **Ejemplo:** Si el servicio devuelve `{"error": {"message": "Saldo insuficiente"}}`, puedes mapear `error.message` a un campo de tu formulario llamado "Motivo de Rechazo". ###### 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](/es/article/autenticacion-de-servicios-rest-cezrf3/) en la pestaña *Autenticaciones*. ![](https://storage.crisp.chat/users/helpdesk/website/ccc3fbb5dc442800/aut_roz0po.gif) --- ### 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. ![](https://storage.crisp.chat/users/helpdesk/website/-/c/c/c/3/ccc3fbb5dc442800/imagen_flb6nd.png) | **Escenario** | **Código HTTP** | **Pestaña "Manejo de Errores"** | **Acción del Motor de Flokzu** | **Valor de flokzu\_ws\_status** | | ---- | | **Éxito** | **200 - 299** | *Cualquiera* | Se procesa el mapeo de **Datos de Salida**. | Devuelve **200** | | **Error (Legacy)** | **4XX / 5XX** | **OFF** | Se ignora "Datos de Salida", pero se captura el código en `flokzu_ws_status`. | Devuelve el **código de error** (ej. 404) | | **Error Gestionado** | **4XX / 5XX** | **ON** | Se ignora "Datos de Salida". Se procesa **solo** el mapeo de "Manejo de Errores". | Se captura **solo si se mapea** en la nueva pestaña. | ## 7. Servicio con callback Una Tarea de Servicio REST puede configurarse para trabajar de forma asíncrona mediante un callback. Esta modalidad permite integrar servicios externos que requieren más tiempo de procesamiento y que no pueden responder inmediatamente. A diferencia de un servicio síncrono, donde Flokzu espera la respuesta durante la misma ejecución, con un servicio con callback la instancia queda esperando la respuesta del sistema externo sin bloquear al usuario ni mantener una ejecución activa. ### ¿Cuándo usarlo? El servicio con callback es útil cuando el sistema externo puede demorar en procesar la solicitud, por ejemplo: * Generación de documentos complejos. * Procesamiento de archivos grandes. * Ejecución de análisis con IA. * Verificaciones o validaciones que requieren más tiempo. Para operaciones que necesitan una respuesta inmediata, continúa utilizando la configuración síncrona habitual. ### Configuración Para utilizar un servicio con callback: 1. Configura la Tarea de Servicio REST como asíncrona activando la opción **Servicio con callback (esperar respuesta)**. 2. Mantén la configuración de entrada, salida y demás parámetros del servicio según los requerimientos de la integración. ![](https://storage.crisp.chat/users/helpdesk/website/-/c/c/c/3/ccc3fbb5dc442800/image_olxmb9.png =583xauto) Una vez configurada, la Tarea de Servicio REST funcionará de forma asíncrona y esperará la respuesta del servicio externo antes de continuar con el flujo. Cuando Flokzu realiza la solicitud al servicio externo, envía automáticamente en los headers la información necesaria para identificar la instancia y validar la respuesta posterior: * `X-Flokzu-Correlation-Id`: identificador utilizado para asociar la respuesta con la instancia y la Tarea de Servicio REST correspondiente. * `X-Flokzu-Callback-Signature`: firma utilizada para validar la comunicación. ||| Estos valores son generados automáticamente por Flokzu y no deben configurarse manualmente. ### Respuesta inicial y callback El servicio externo debe responder inicialmente a la solicitud en menos de 15 segundos con código HTTP 200. Esta respuesta solo confirma que la solicitud fue recibida correctamente y no debe incluir la respuesta final del procesamiento. Una vez finalizado el procesamiento, el servicio externo debe enviar la respuesta a Flokzu mediante una llamada callback al siguiente endpoint: * POST : https://app.flokzu.com/flokzuopenapi/api/callback/{correlationId}?sig={signature} * Se debe agregar como parámetros el **correlationId** y **signature** que previamente enviamos en los encabezados de la solicitud. La llamada debe incluir la respuesta final del servicio en formato JSON. Flokzu utilizará esta información para completar el mapeo configurado en los Datos de Salida de la Tarea de Servicio REST. Una vez configurada, la Tarea de Servicio REST funcionará de forma asíncrona y esperará la respuesta del servicio externo antes de continuar con el flujo. ### Comportamiento de la instancia Mientras espera la respuesta del servicio externo: * La instancia no queda bloqueada para el usuario. * El usuario puede continuar trabajando con otras instancias o cerrar sesión. * La instancia puede ser consultada mediante búsqueda o editada mediante API. Cuando el servicio externo envía la respuesta, Flokzu procesa la información recibida, actualiza los campos configurados en los Datos de Salida y continúa la ejecución del proceso por la salida definida en la Tarea de Servicio REST. ### Timeout Para evitar que una instancia quede esperando indefinidamente ante un problema del servicio externo, Flokzu agrega automáticamente un timer interruptivo con un tiempo máximo de espera de 30 días. Este timer no puede eliminarse ni modificarse. Si la respuesta no llega dentro de ese período, la instancia continúa por la salida configurada en el timer. El administrador puede agregar timers adicionales para definir tiempos de espera más cortos y configurar comportamientos específicos según las necesidades del proceso. ![](https://storage.crisp.chat/users/helpdesk/website/-/c/c/c/3/ccc3fbb5dc442800/image_1di4y9g.png) ||| **Es responsabilidad del administrador configurar la acción que se ejecuta en el timeout. Si no se agrega** una salida configurada para ese caso, la **instancia quedará finalizada en esa rama de ejecución.** ## ¿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](http://zapier.com/). Simplemente coloca una Tarea de Servicio en el workflow, selecciona “Zapier” y sigue los pasos para [integrar Flokzu y Zapier.](https://docs.flokzu.com/es/article/integracion-zapier-para-conectar-con-otras-aplicaciones-web-f8xe2n/?1542911282734) Una vez configurada la integración, podrás conectar Flokzu con más de 6.000 apps (Facebook, Google Drive, Gmail, SalesForce, etc).