# Integraciones REST > Conectar Audara con las APIs de tus propios servicios ## Vista general del módulo El módulo API Rest permite integrar Audara con servicios externos por medio de sus APIs: defines la URL del servicio, cómo autenticarte y las solicitudes que quieres ejecutar, y esas solicitudes quedan disponibles para tus flujos de chatbot y voicebot. Lo encuentras en **Configuración > General > Integraciones**, en la tarjeta **API**. ![Integraciones, tarjeta API](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-card.jpg) *Integraciones, tarjeta API* - **1.** Abre la tarjeta **API** para ver la lista de integraciones REST. La tarjeta muestra cuántas integraciones tienes configuradas. ![Lista API](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-lista.jpg) *Lista API* - **1.** Crea una nueva integración con el botón (+) del encabezado. - **2.** Abre el menú de más opciones (⋮) de cada integración para editarla, desactivarla o eliminarla. La lista muestra el **Nombre** de cada integración y su **Estado** (activo o inactivo). Haz clic en el nombre para abrirla y editarla. ## Crear una integración Presiona el botón (+) en el encabezado de la lista. La configuración se organiza en tres pestañas: **Ajustes**, **Solicitudes** y **Autenticación**. Los campos obligatorios están marcados con un asterisco (*). Al completarlos se activa el botón **Guardar**. ![Nuevo REST, pestaña Ajustes](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-ajustes.jpg) *Nuevo REST, pestaña Ajustes* - **1.** Campos de identificación de la integración. - **2.** URL a la que apuntan todas las solicitudes de esta integración. - **3.** Guarda la integración cuando completes los campos obligatorios. - **Nombre***: Nombre de la integración. Es el que verás al usarla desde otros módulos. - **URL Base***: URL base para las peticiones REST de esta integración. La ruta de cada solicitud se agrega a esta URL. ## Variables Globales En la misma pestaña **Ajustes** defines las variables globales que se usarán en tus solicitudes, como tokens de autenticación o claves API. Defines el valor una sola vez y lo reutilizas en los headers de la integración. ![Variables Globales](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-variables.jpg) *Variables Globales* - **1.** Nombre con el que identificas la variable. - **2.** Valor de la variable. Si es secreta, se muestra oculto. - **3.** Interruptor **Secreto** para proteger el valor. - **4.** Agrega otra variable con el botón (+). - **Nombre***: Nombre de la variable. No puede repetirse dentro de la integración. - **Valor***: Valor de la variable, por ejemplo el token o la clave que entrega el servicio externo. - **Secreto**: Si la variable es secreta, su valor se oculta al editar la integración y en los logs. > **Buenas prácticas** > Guarda los tokens y claves como variables globales secretas en lugar de escribirlos directamente en cada header. Así los actualizas en un solo lugar y no quedan visibles para otros administradores. ## Headers predeterminados Aquí defines los headers que se enviarán en todas las solicitudes de la integración, como los headers Authorization o Bearer. ![Headers predeterminados](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-headers.jpg) *Headers predeterminados* - **1.** Key del header, por ejemplo **Authorization**. - **2.** Variable global que se usará como valor del header. - **3.** Alterna entre usar una variable global y un valor fijo con el ícono junto al campo. El valor de un header puede venir de dos fuentes: - **Variable***: Usa una de las variables globales definidas en Ajustes. Ideal para tokens y claves que quieres reutilizar. - **Valor fijo***: Usa un valor estático, como "application/json" o un número de versión. En este modo aparece su propio interruptor **Secreto** por si el valor fijo también debe ocultarse. ## Autenticación En la pestaña **Autenticación** configuras cómo la integración se autentica con el servicio externo. Úsala para APIs que requieren OAuth 2.0. ![Autenticación con OAuth 2.0 (Client Credentials)](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-auth.jpg) *Autenticación con OAuth 2.0 (Client Credentials)* - **1.** Tipo de autenticación de la integración. - **2.** Endpoint que emite el token, según el proveedor. - **3.** Dónde se envían las credenciales al pedir el token. - **Tipo de autenticación**: Selecciona **Ninguna** para usar solo headers estáticos, **Bearer Token** para un token fijo, u **OAuth 2.0 (Client Credentials)** para obtener y renovar un token automáticamente. ### Bearer Token - **Token***: Token que se enviará como header "Authorization: Bearer" en todas las solicitudes. Se almacena de forma segura y se oculta al editar. ### OAuth 2.0 (Client Credentials) - **Token URL***: Endpoint que emite el token. Para Microsoft tiene la forma https://login.microsoftonline.com//oauth2/v2.0/token. - **Client ID***: Identificador de la aplicación registrada en el proveedor. - **Client Secret***: Secreto de la aplicación. Se almacena de forma segura y se oculta al editar. - **Scope**: Alcance del token. Para Dynamics tiene la forma https://.crm.dynamics.com/.default. - **Ubicación de las credenciales**: Dónde se envían el Client ID y el Secret en la petición del token. La mayoría de proveedores los recibe en el cuerpo; algunos requieren un header Basic. - **Parámetros adicionales**: Parámetros extra para la petición del token, por ejemplo "resource" o "audience" según el proveedor. Cada uno se define como clave y valor. > **Nota** > Con OAuth 2.0 la plataforma pide el token y lo renueva automáticamente cuando expira. No necesitas actualizarlo a mano ni crear headers para él. ## Solicitudes En la pestaña **Solicitudes** defines las peticiones que se usarán desde tus integraciones, como GET o POST. Cada solicitud queda guardada en la integración y lista para usarse desde tus bots. ![Solicitudes de la integración](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-solicitudes.jpg) *Solicitudes de la integración* - **1.** Crea una solicitud con el botón **Nueva solicitud**. - **2.** Haz clic en el nombre de una solicitud para editarla. Al crear o editar una solicitud se abre el formulario junto al panel **Probar solicitud**: ![Editar solicitud](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-solicitud-editar.jpg) *Editar solicitud* - **1.** Nombre de la solicitud. - **2.** Método HTTP. - **3.** Ruta que se agrega a la URL Base. - **4.** Ejecuta la solicitud de prueba con el botón **Probar**. - **Nombre***: Nombre de la solicitud. No puede repetirse dentro de la integración. - **Método***: Método HTTP de la solicitud: **GET**, **POST**, **PUT** o **PATCH**. Cada uno tiene su color en la lista de solicitudes, para reconocerlos de un vistazo. - **Ruta***: Ruta de la solicitud. Se agrega a la URL Base de la integración y puede incluir parámetros. - **Body JSON***: Body de la solicitud para los métodos que lo envían. Debe ser un JSON válido. - **Enviar como**: Formato para enviar el body: **JSON** o **Form-data**. Cuando la solicitud envía datos, es decir con **POST**, **PUT** o **PATCH**, el formulario muestra además el formato de envío y el body. Con GET esos dos campos no aparecen. ![Solicitud POST con variables en el body](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-solicitud-post.jpg) *Solicitud POST con variables en el body* - **1.** Elige el formato de envío del body: **JSON** o **Form-data**. - **2.** Escribe el body de la solicitud. Puedes usar variables entre llaves, como {nombre} o {edad}, para llenarlas con datos de la conversación al ejecutar la solicitud desde un bot. - **3.** El panel Probar detecta las variables del body y te pide un valor de prueba para cada una. > **Nota** > Lo mismo aplica para la ruta: si usa variables, aparecen en la sección **Variables Ruta** del panel Probar. Los valores que escribas ahí solo se usan para la prueba. > **Nota** > Una solicitud tiene 60 segundos para responder. Si tu servicio se demora más, la petición se corta y el paso del bot sigue con el error, en vez de quedarse esperando. ## Mandar un archivo a tu API Cuando un chatbot le pide un archivo a la persona, ese archivo se puede guardar en una variable y mandárselo después a tu servicio desde una de estas solicitudes. Del lado del bot, el paso que lo pide es el de captura de archivo, y ahí se elige en qué variable queda guardado; del lado de la integración no tienes que configurar nada especial, solo usar esa variable en el body como cualquier otra. ![Solicitud que sube un archivo](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-archivo.jpg) *Solicitud que sube un archivo* - **1.** El método. Muchos servicios de subida usan **PUT**. - **2.** **Enviar como** decide si sube el archivo o un enlace a él. - **3.** La variable del archivo va en el body como cualquier otra, entre llaves. - **4.** En el panel Probar, el método se muestra con su color. Lo que decide la solicitud es **cómo** viaja el archivo, y eso sale del campo **Enviar como**: - **Form-data**: El archivo viaja dentro de la petición, como cuando lo subes desde un formulario web. Es lo que espera la mayoría de servicios que reciben archivos. - **JSON**: En lugar del archivo viaja un **enlace** para descargarlo, que vive una hora. Tu servicio recibe la dirección y baja el archivo por su cuenta dentro de ese plazo. No hay una tercera opción, y no te toca coordinar las dos puntas: eliges el formato y Audara arma la petición que corresponde. > **Importante** > Un archivo no puede pesar más de 20 MB. El paso que lo pide en el chatbot puede exigir menos, nunca más, así que si necesitas un tope más bajo para tu caso, se configura allá. > **Buenas prácticas** > Si tu endpoint de subida es un **PUT**, ya lo puedes usar: PUT es uno de los métodos que envían body y aparece en el selector junto a POST y PATCH. ## Probar y elegir campos de la respuesta El panel **Probar solicitud** muestra el método y la URL completa que se va a ejecutar. Presiona **Probar** para enviar la solicitud real al servicio y ver la respuesta. ![Respuesta de prueba y campos seleccionados](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-probar.jpg) *Respuesta de prueba y campos seleccionados* - **1.** Ejecuta la prueba con el botón **Probar**. - **2.** El **Status** indica el resultado de la petición. - **3.** Haz clic en los campos resaltados de la respuesta para seleccionarlos como variables. - **4.** Los campos seleccionados aparecen en **Campos respuesta**. Los campos que selecciones son los que quedan disponibles como variables al usar la solicitud desde otros módulos. En **Campos respuesta** puedes cambiarles el nombre por uno más informativo; si dejas el campo vacío, conserva el nombre original de la respuesta. > **Importante** > El botón Probar ejecuta la solicitud real contra el servicio externo. Ten cuidado al probar solicitudes que crean o modifican datos, como los POST. ## Respuestas tipo lista Cuando la respuesta trae un arreglo de elementos, por ejemplo una lista de contactos o de citas disponibles, puedes tratar todo el arreglo como una sola variable de tipo lista. ![Respuesta tratada como lista](https://docs.audara.io/integraciones-api-rest/imagenes/apirest-respuesta-lista.jpg) *Respuesta tratada como lista* - **1.** Presiona el ícono de lista junto al arreglo para tratarlo como lista. La respuesta se contrae y muestra solo el primer elemento como muestra. - **2.** Nombre de la variable que contendrá la lista. - **3.** Plantilla con la que se muestra cada elemento. - **4.** Texto que separa los elementos al unir la lista. - **Nombre de la variable**: Nombre con el que usarás la lista completa desde otros módulos. - **Campos del elemento**: Campos de cada elemento que quieres usar. Selecciónalos haciendo clic en los campos resaltados dentro del elemento de muestra, y renómbralos si necesitas nombres más claros. - **Plantilla del elemento (opcional)**: Cómo se muestra cada elemento. Inserta valores con {NombreCampo}, usando el nombre que le diste al campo, o con la ruta directa como {name.first}. Por ejemplo: {Nombre} <{email}>. Si la dejas vacía, se unen los campos seleccionados separados por espacio. - **Separador**: Texto que se coloca entre cada elemento al unir la lista. Por defecto es una coma con espacio, y el botón **Nueva línea** usa un salto de línea. ## Dónde se usan las integraciones Las solicitudes que configures quedan disponibles en los flujos de tus bots: - **Chatbots:** el paso de integración ejecuta una solicitud, le envía variables de la conversación y guarda los campos de la respuesta como variables del chat, listas para usarse en los mensajes y condiciones siguientes. - **Voicebots:** los flujos de voz ejecutan las mismas solicitudes y usan los campos de la respuesta dentro de la llamada. En ambos casos, los campos y listas que definiste en **Campos respuesta** son los que aparecen como variables disponibles. ## Editar, desactivar o eliminar Haz clic en el nombre de una integración para editarla. Desde el menú de más opciones (⋮) a la derecha de cada integración puedes **Editar**, **Desactivar** o **Eliminar**. Una integración desactivada conserva su configuración pero deja de estar disponible. > **Nota** > Antes de eliminar una integración, revisa qué bots la usan. Un flujo que dependa de una solicitud eliminada dejará de obtener esos datos.