Uso de integraciones por API REST

Integraciones por API REST para solicitudes GET y POST en agentes de IA

Modulo de integración por API REST

Para crear integraciones usando API REST debemos dirigirinos al modulo de integraciones y selecionar API REST como se ve en la imagen

Una vez dentro del módulo de API REST, puedes crear diferentes integraciones según los sistemas externos con los que necesites comunicarte.
Cada integración puede tener múltiples solicitudes configuradas de manera independiente, ya sea del tipo GET (para consultar datos) o POST (para enviar información). Esto permite estructurar tu conexión de forma modular, ordenada y flexible, manteniendo cada API bien identificada con sus respectivos endpoints y parámetros.

1. Crear nueva integración
Haz clic en el botón con el ícono de suma (+) para crear una nueva integración API REST. Esto abrirá el formulario donde podrás definir el nombre, URL base y otros ajustes.

2. Tabla de integraciones
Aquí se listan todas las integraciones creadas, mostrando:

  • El nombre de la integración (como “HubSpot” o “Postman Echo”).

  • Su estado actual (por ejemplo, “Activo”).

Puedes hacer clic sobre el nombre de cualquier integración para editarla, o usar la barra de búsqueda para localizar rápidamente alguna específica.

1. Pestaña “Ajustes”
Dentro del módulo de configuración de API REST en Audara, encontrarás diferentes pestañas que te permitirán organizar y controlar cada aspecto de tu integración. A continuación, una descripción breve de su función:

🧩 Ajustes generales

Esta es la pestaña inicial desde donde se configuran los datos básicos de la integración. Aquí defines:

  • El nombre de la integración.

  • La URL base del servicio externo.

  • Opcionalmente, cabeceras comunes, autenticación, o parámetros globales que se aplicarán a todas las solicitudes.

🔄 Solicitudes (GET y POST)

En esta pestaña se crean las solicitudes específicas que el SmartAgent o el flujo del bot ejecutará. Puedes añadir solicitudes tipo:

  • GET: para consultar información de un sistema externo.

  • POST: para enviar datos a un sistema externo.

Cada solicitud puede tener su propio cuerpo JSON, variables dinámicas, condiciones, encabezados, y respuesta esperada.

En la siguiente sección exploraremos con más detalle cómo se configura cada tipo de solicitud.

2. Nombre
Este campo corresponde al nombre identificador de la integración API REST dentro de la plataforma Audara. Es el nombre que verás listado cuando accedas al módulo de integraciones, así que debe ser claro y representativo.

3. URL Base
Este campo define la URL base del servicio externo con el que se realizará la integración por API REST.
Se refiere únicamente a la parte principal del dominio, por ejemplo:
https://www.postman-echo.com

Los subdirectorios, rutas específicas o endpoints se agregarán más adelante en cada solicitud GET o POST que configures dentro de esta integración.

Esto permite utilizar una misma URL base para múltiples solicitudes dentro del mismo dominio, facilitando la organización y el mantenimiento de tus integraciones.

4. Variables Globales
En esta sección puedes definir variables reutilizables que serán utilizadas en todas tus solicitudes API. Una de las más comunes es el API Token, el cual permite autenticarte ante el sistema externo al que te estás integrando.

Estas variables pueden marcarse como secretas para ocultar su valor por seguridad. Esto es útil si vas a compartir el acceso con otras personas del equipo sin mostrar credenciales sensibles.

Por ejemplo, puedes crear una variable llamada Api token que almacene tu token de autenticación, y luego referenciarla fácilmente en las solicitudes, encabezados (headers) u otros campos.

5 .Headers predeterminados
En esta sección puedes definir variables reutilizables que serán utilizadas en todas tus solicitudes API. Una de las más comunes es el API Token, el cual permite autenticarte ante el sistema externo al que te estás integrando.

Estas variables pueden marcarse como secretas para ocultar su valor por seguridad. Esto es útil si vas a compartir el acceso con otras personas del equipo sin mostrar credenciales sensibles.

Por ejemplo, puedes crear una variable llamada Api token que almacene tu token de autenticación, y luego referenciarla fácilmente en las solicitudes, encabezados (headers) u otros campos.

1. Botón “Nueva solicitud”
Este botón te permite crear una nueva solicitud para esta integración REST. Al hacer clic, podrás configurar el método (GET, POST, etc.), la ruta específica del endpoint, parámetros, headers adicionales, cuerpo de la solicitud, y más.

2. Ejemplo de solicitud GET
Este es un ejemplo de una solicitud tipo GET ya creada. El nombre “Test Get” es personalizado y sirve para identificarla fácilmente. Al ser de tipo GET, se utiliza principalmente para consultar o recuperar datos del sistema externo.

3. Ejemplo solicitud POST
Este es un ejemplo de una solicitud tipo POST. El nombre “Test Post” también es personalizable. Las solicitudes POST se usan para enviar datos al sistema externo, como crear un nuevo registro, enviar formularios o activar acciones.

Crear solicitud GET

Para crear una solicitud GET, lo primero es presionar el botón “Nueva solicitud” y luego seleccionar el tipo GET. Esto desplegará las opciones de configuración específicas para este tipo de solicitud, que serán necesarias para continuar con la integración.

1. Nombre
Este campo corresponde al nombre identificador de la solicitud dentro de la plataforma Audara. Es el nombre que verás listado cuando accedas al módulo de solicitudes, así que debe ser claro y representativo.

2. Metodo
Este parámetro permite definir el tipo de método HTTP que se va a utilizar en la solicitud. En este caso, se selecciona GET.

3. Ruta
Es la ruta específica que se añadirá a la URL base de la integración. 

Solo se trata de la uRL inicial.

URL: https://api.audara.cloud/

Los complementos de ruta deben ir en cada solicitud que se haga. 

Por ejemplo de complemento de ruta:

RUTA:
/clients?per_page=1&national_identification_number_eq={cedula}

 

4. Probar solicitud
Este sección permite ejecutar la solicitud en tiempo real para verificar que la integración esté funcionando correctamente y visualizar la respuesta. También es clave para seleccionar los datos necesarios que se esperan capturar con la solicitud.

5. Campos respuesta
Aquí puedes renombrar los campos que devuelve la API para que tengan nombres más comprensibles o útiles dentro de Audara, en especial al usar en los flujos de un agente de IA.

Por ejemplo: cambiar email por Correo.

Probar solicitud GET

Esta sección permite hacer una prueba real con datos específicos (como un ID) para ver qué devuelve la API antes de guardar la solicitud.
Es útil para validar que todo esté bien configurado y para seleccionar los campos que realmente se quieren capturar de la respuesta, evitando usar datos innecesarios.

1. URL base:
Muestra la URL completa que se usará en la prueba. Aquí se combina la URL base definida en la integración con la ruta ingresada en la solicitud GET. Puede incluir parámetros dinámicos encerrados entre llaves como {contactId}.

Ejemplo:

URL: https://api.audara.cloud/

RUTA (lo único que incluiremos en cada solicitud):
/clients?per_page=1&national_identification_number_eq={cedula}

Notemos que la variable debe estar en formato {variable}

2. Variables en ruta:
Las llaves {} indican variables dinámicas (como {contactId}), que deben ser reemplazadas temporalmente con un valor de prueba para ejecutar la solicitud.

3. Campo de valor de prueba:
Aquí ingresas el valor real que reemplazará la variable de la ruta. En este caso, el ID del contacto 108483507030.

4. Botón “Probar”:
Ejecuta la prueba real llamando a la API REST con los datos que hayas configurado. Devuelve la respuesta de ejemplo para revisión.

5. Status:
Indica el código de respuesta HTTP.

  • 200 significa que la solicitud fue exitosa.

  • Otros códigos (400, 500, etc.) indican errores que deben revisarse.

6. Respuesta cruda (JSON):
Aquí se muestra el contenido completo que devuelve la API, en formato JSON.
Desde aquí puedes visualizar los campos en azul y seleccionar con un clic los campos que deseas capturar (se marcarán en verde).
Esto asegura que solo extraes los datos necesarios para tu flujo (por ejemplo: email, firstname, hs_object_id), y no toda la respuesta completa.

Renombrar campos

1. Campo original (email)
Es el nombre exacto con el que viene el dato desde la API externa.
Este no se puede modificar, porque es el nombre real del campo en la respuesta JSON.

2. Nombre visible personalizado (Correo)
Aquí puedes escribir un nombre más amigable o claro, para facilitar la comprensión del dato.
Por ejemplo, puedes cambiar email por Correo del cliente si te ayuda a identificarlo mejor.

3. Eliminar campo
Con este botón puedes quitar un campo que hayas capturado por error o que ya no necesites.

Crear solicitud POST

Para crear una solicitud GET, lo primero es presionar el botón “Nueva solicitud” y luego seleccionar el tipo GET. Esto desplegará las opciones de configuración específicas para este tipo de solicitud, que serán necesarias para continuar con la integración.

1. Nombre
Este campo corresponde al nombre identificador de la solicitud dentro de la plataforma Audara. Es el nombre que verás listado cuando accedas al módulo de solicitudes, así que debe ser claro y representativo.

2. Metodo
Este parámetro permite definir el tipo de método HTTP que se va a utilizar en la solicitud. En este caso, se selecciona POST.

3. Ruta
Es la ruta a la que se enviará la solicitud, normalmente algo como /endpoint o /api/crear_usuario.

4. Body JSON
Aquí escribes el cuerpo de la solicitud en formato JSON.

  • Debe ser un JSON válido y bien formado.

  • Las variables dinámicas se escriben como {variable} (con llaves), y se marcan automáticamente en azul.

  • Los valores de tipo texto deben ir entre comillas: "nombre": "{nombre}"

  • Los valores numéricos no llevan comillas: "edad": {edad}

  • Puedes combinar variables con datos fijos si el endpoint lo requiere.

✅ Nota importante sobre el JSON

Al escribir el Body JSON:

  • Si ves texto en negro, significa que es un valor fijo que siempre se enviará igual.

  • Si el formato del JSON no es válido, no podrás guardar ni probar la solicitud.

5. Probar solicitud
Permite ejecutar una prueba con datos reales para verificar que la solicitud funcione correctamente y ver la respuesta.

6. Campos respuesta
Aquí puedes renombrar los campos que devuelve la API en la respuesta.
Esto no cambia la variable que usarás en el flujo, solo te ayuda a identificar los datos más fácilmente si vienen con nombres poco claros (por ejemplo, name → Nombre, ok → Resultado_OK).

Probar solicitud POST

Esta sección permite verificar que tu integración esté funcionando correctamente antes de usarla en un flujo real. Aquí puedes enviar datos de ejemplo y ver cómo responde el sistema externo.

1. URL base:
Aquí se muestra la URL completa de la solicitud que estás probando.
En este ejemplo:
POST https://postman-echo.com/post

🔹 El método aparece en color (POST, GET, etc.).
🔹 Esta URL se compone de la base configurada más la ruta.

2. Variables en ruta:
Este es un campo de ejemplo para la variable {nombre} que escribiste en el Body JSON.
Aquí puedes ingresar cualquier valor de prueba (en este caso, “Juan”) para verificar que la solicitud funcione con datos reales.

3. Campo de valor de prueba:
Lo mismo que el anterior, pero para la variable {edad}.
Aquí escribiste “8” como ejemplo de número.

4. Botón “Probar”
Presiona este botón para enviar la solicitud al servidor externo con los datos de ejemplo ingresados en los campos de arriba.

5. Status de la respuesta
Este es el resultado del servidor externo.
Un código 200 en verde significa que la solicitud fue exitosa.
Si aparece en rojo o con otro número (400, 500, etc.), algo falló y debes revisar la configuración o los datos enviados.

6. Respuesta prueba
Aquí se muestra todo lo que devolvió el servidor externo al recibir tu solicitud.
Puedes ver:

  • Los datos enviados

  • Los headers

  • Y el JSON completo de respuesta

Desde aquí puedes seleccionar qué campos quieres capturar como variables para usarlos en el flujo.

📌 Nota adicional

Aunque estás creando una solicitud POST, que usualmente se usa para enviar datos, el sistema también permite definir campos de respuesta igual que en una solicitud GET.
Esto es útil porque algunos POST devuelven información útil como:

  • Un mensaje de confirmación

  • Un ID creado

  • El objeto completo insertado
    Y esa respuesta puede usarse como variables dentro del flujo.

Renombrar campos

1. Campo original (email)
Es el nombre exacto con el que viene el dato desde la API externa.
Este no se puede modificar, porque es el nombre real del campo en la respuesta JSON.

2. Nombre visible personalizado (Correo)
Aquí puedes escribir un nombre más amigable o claro, para facilitar la comprensión del dato.
Por ejemplo, puedes cambiar email por Correo del cliente si te ayuda a identificarlo mejor.

3. Eliminar campo
Con este botón puedes quitar un campo que hayas capturado por error o que ya no necesites.

Usar integraciones API REST en un agente de IA (Voicebot, Chatbot)

Lo primero que debes hacer es insertar un nodo de tipo “Integración” dentro del flujo del bot. Este nodo es el que permite llamar a una de las integraciones REST que ya configuraste (GET o POST).

  • Integración:
    Aquí seleccionas la integración que ya creaste en el módulo de API REST (por ejemplo, “Postman Echo”).
    Esta integración contiene la URL base y el conjunto de solicitudes disponibles.

  • Solicitud:
    Una vez elegida la integración, seleccionas qué solicitud específica deseas usar dentro de esa integración.
    Puede ser un método GET o POST previamente configurado.
    Ejemplo: ObtenerDatosUsuario o RegistrarPersona.

Usar integracion tipo GET

Este nodo de “Integración” permite conectar el flujo del bot con una API externa (REST), utilizando una solicitud previamente configurada. En este caso una solicitud GET.

1. Solicitud
Aquí seleccionas la solicitud GET o POST configurada previamente dentro de la integración elegida.
En este caso es:
[GET] Buscar cliente por cédula.

2. Datos para enviar
En las solicitudes GET, se deben enviar los parámetros requeridos por la API, como parte de la URL o query string.
Aquí defines qué valor se enviará por cada parámetro, por ejemplo:

  • cedula: CEDULA
    Esto significa que se enviará el valor de la variable CEDULA (obtenida en pasos anteriores del flujo).

3. Alternar entre valor fijo y variable
Este ícono te permite cambiar entre escribir un dato fijo (por ejemplo, escribir directamente “103252365”)
o usar una variable del flujo (como CEDULA).
Sirve para decidir si ese dato viene de una variable capturada o si es fijo en esta llamada.

4. Renombrar variables de respuesta

Aquí defines cómo se llamarán las variables que devuelve la API dentro del flujo del bot.
Esto te permite que el bot reconozca los valores devueltos y los puedas usar en mensajes, condiciones, etc.
Ejemplo:

  • Nombre: NOMBRE_W

  • Celular: CEL_W

  • ID Cliente personalizable: CUSTOMID_W

Estas variables pueden ser luego usadas en otros nodos para mostrar al usuario, validar, o guardar en CRM.

5. Mensaje de error
Texto que el bot mostrará si la API falla o no responde correctamente.
Ejemplo: No pudimos obtener los datos del cliente. Intenta más tarde.

6. En caso de error, ir a paso
Si hay un error en la llamada (por ejemplo, si no hay datos para esa cédula), aquí defines a qué nodo del flujo debe continuar el bot.
Puede ser un paso de error, mensaje de ayuda, volver a pedir el dato, etc.

Usar integración tipo POST

Este nodo permite que el bot envíe información a una API externa a través de una solicitud de tipo POST (usada comúnmente para enviar datos y recibir respuestas).

1. Solicitud
Aquí se selecciona la solicitud de tipo POST que ya se haya creado previamente dentro de la integración elegida.
En este ejemplo, se seleccionó:
[POST] Test Post

2. Datos para enviar
Estos son los campos que se enviarán al hacer el POST.
Cada uno puede tener una variable del flujo como valor o un valor fijo.
Por ejemplo:

  • nombre: NAME_FOR_POST (envía el valor de la variable NAME_FOR_POST)

  • edad: -- (no se ha definido variable ni valor, por eso aparece vacío)

3. Cambiar entre valor fijo o variable Este ícono 🔧 permite cambiar si el valor del campo se toma desde una variable del flujo o se escribe directamente como valor fijo.

Al presionarlo:

  • Si estaba usando variable, permite escribir un valor fijo.

  • Si estaba en valor fijo, permite volver a usar una variable.

4. Renombrar variables de respuesta
Aquí puedes asignar nombres personalizados a los datos que la API devuelve.
Eso te permite usar las respuestas dentro del flujo del bot con nombres claros.
Ejemplo:

  • Nombre: → POST_NAME

  • Result_Ok: → POST_OK

5. Mensaje de error
Texto que el bot mostrará al usuario si hay un fallo en la integración.
Ejemplo sugerido:
No fue posible completar la solicitud, intenta más tarde.

6. En caso de error,, ir a paso
Define a qué paso del flujo debe ir el bot si la solicitud falla (por ejemplo, si el servidor no responde, o devuelve un código de error).
En este caso, redirige al paso Post Not OK (Flujo principal).

Otros temas de interés

Trabajamos para hacer más fácil tu vida

Comunícate con Nosotros

Visita Audara.co