Configurar la tarjeta Solicitud HTTP
Ruta: Configuraciones → Flujo de comunicación → (flujo) → Abrir flujo → + → Herramientas del sistema → Solicitud HTTP
Visión general
La tarjeta Solicitud HTTP hace que el agente virtual llame a la API de un sistema externo durante la atención, para consultar un pedido, enviar una factura o registrar un contacto, por ejemplo. La respuesta de la API puede guardarse en variables, usadas por las tarjetas siguientes, o convertirse en un menú de opciones para que el contacto elija.
Esta página explica todos los campos de la tarjeta. Para un ejemplo completo, con pregunta, consulta y decisión, consulta Crear un flujo de comunicación low code con solicitud HTTP.
Requisitos previos
- Una integración HTTP instalada en ¡Hola! Store → Http, con la dirección del sistema y la autenticación. Consulta Configurar la integración HTTP.
- Los datos de la API: ruta (endpoint), método, encabezados, cuerpo y formato de la respuesta.
- Permiso para editar flujos de comunicación.
Paso a paso
- Abre el flujo de comunicación.
- Haz clic en el + debajo de la tarjeta después de la cual se debe hacer la solicitud.
- En la ventana Nueva etapa, marca Herramientas del sistema en el campo Tipo y elige Solicitud HTTP en Herramienta.
- Completa la sección Configuración (consulta la tabla a continuación).
- En la sección Respuesta, completa la Asignación de propiedades de respuesta a variables (JSON).
- Haz clic en Probar request para verificar el resultado.
- Haz clic en Guardar.
Campos de la configuración
| Campo | Qué hace |
|---|---|
| Integración | La integración HTTP que se usará. Es obligatoria. |
| Endpoint | La ruta a llamar, sumada a la dirección de la integración. Acepta variables entre llaves dobles, como /pedidos/. |
| Método | GET, POST, PUT, PATCH o DELETE. Es obligatorio. |
| Headers (JSON) | Encabezados de la solicitud, en formato JSON. |
| Body (JSON) | Cuerpo de la solicitud, en formato JSON. |
| Parámetros de consulta (JSON) | Parámetros de búsqueda de la solicitud, en formato JSON. |
| Utilizar Script de pre-solicitud | Activa un script en JavaScript que se ejecuta antes de la llamada. |
| Utilizar Script de post-solicitud | Activa un script en JavaScript que se ejecuta después de la llamada. |
Los campos Headers, Body y Parámetros de consulta deben estar en JSON válido. Puedes usar variables del flujo entre llaves dobles. El botón Biblioteca de variables lista las variables disponibles para esta tarjeta: elige una y haz clic en su nombre para copiarlo. Si la integración usa autenticación por token, también puedes usar para colocar el token en otro punto de la solicitud.
Scripts antes y después de la llamada
Los scripts sirven para preparar datos antes de la llamada o tratar la respuesta después. Dentro de ellos, accedes a las variables así:
FLOW.nome_da_variavel: variables creadas en las tarjetas del flujo.SYSTEM.nome_da_variavel: variables del sistema, como el protocolo.RESPONSE.data,RESPONSE.erroryRESPONSE.statusCode: el resultado de la llamada (solo en el Script de post-solicitud).
Usa SETVARS({ ... }) para crear variables. El valor pasado debe ser un objeto. Las variables creadas en el Script de pre-solicitud pueden usarse en el endpoint, en los headers, en el body y en los parámetros de consulta. Las creadas en el Script de post-solicitud quedan disponibles para las tarjetas siguientes.
Asignación de la respuesta
El campo Asignación de propiedades de respuesta a variables (JSON) indica de dónde sacar cada dato de la respuesta. La respuesta tiene tres partes: data (el contenido devuelto), error (el error, si lo hay) y statusCode (el código de respuesta). Ejemplo:
{ "status_pedido": "data.status", "codigo_http": "statusCode" }Los nombres de las variables deben estar en lowercase, camelCase o snake_case y no pueden repetirse en otra tarjeta del flujo.
Generar pregunta de elección con la respuesta
Marca Generar pregunta de elección con la respuesta cuando la API devuelva una lista y el contacto necesite elegir un elemento. Completa:
- Propiedad de la respuesta que contiene el array de datos (opcional): dónde está la lista en la respuesta, como
data.pedidos. Si queda en blanco, la tarjeta usa la respuesta completa. - Mensaje de la pregunta: el texto enviado antes de la lista.
- Descripción de la opción de elección: cómo aparece cada elemento, con los atributos entre llaves. Ejemplo:
Pedido {id} - {status}. - Asignación de propiedades de la elección a variables (JSON): qué datos del elemento elegido se convierten en variables. Ejemplo:
{ "id_pedido": "id" }. - Mensaje de error en la elección, Cantidad de intentos, Mensaje que será enviado al cliente después de exceder el número máximo de intentos y Flujo que será ejecutado después de exceder el número máximo de intentos: tratan las respuestas inválidas. Si la Cantidad de intentos queda en blanco, el límite es 3.
El contacto recibe los elementos numerados y responde con el número. Si la lista viene vacía, el agente virtual no hace la pregunta y sigue a la siguiente tarjeta.
Reglas y comportamientos
- Prueba de la solicitud: el botón Probar request abre la ventana Resultado de la prueba con la respuesta de la API. La prueba ejecuta el Script de pre-solicitud, pero no el Script de post-solicitud ni la asignación de la respuesta.
- Integración no disponible: si la integración elegida fue eliminada o no está disponible en el momento de la atención, el agente virtual cierra la atención.
- Error de la API: la tarjeta no interrumpe el flujo cuando la API responde con error. Para tratar el error, asigna
statusCodeoerrora una variable y usa una tarjeta Condicional. - Datos sensibles: las respuestas marcadas como Campo con información sensible en una tarjeta Enviar pregunta pueden usarse en esta tarjeta. Consulta Configurar la tarjeta Enviar pregunta.
Problemas comunes
| Síntoma | Qué verificar |
|---|---|
| El sistema no guarda y señala el campo Headers, Body o Parámetros de consulta | El contenido debe ser JSON válido. Verifica comillas, comas y llaves. |
| Se rechaza el nombre de la variable | Usa lowercase, camelCase o snake_case, sin espacios ni acentos, y sin repetir el nombre de una variable de otra tarjeta. |
| La variable de la asignación queda vacía | Usa Probar request y verifica la ruta en la asignación, como data.status. |
| La atención se cierra en la solicitud | Verifica si la integración HTTP sigue instalada en ¡Hola! Store → Http y si el método elegido está completado. |
Buenas prácticas
- Prueba la solicitud antes de guardar el flujo.
- Trata el camino de error con un Condicional, para que el contacto no se quede sin respuesta cuando falle la API.
- Da a las variables nombres que digan lo que guardan, como
status_pedido.