> ## Documentation Index > Fetch the complete documentation index at: https://docs.diga.io/llms.txt > Use this file to discover all available pages before exploring further. # Integraciones HTTP > Conecta cualquier API REST a tus agentes telefónicos mediante integraciones HTTP ## ¿Qué son las Integraciones HTTP? Las integraciones HTTP te permiten conectar tus agentes con **cualquier API REST** que uses o controles. Es la forma más flexible de integrar sistemas externos, desde CRMs hasta plataformas de pagos, bases de datos o servicios internos. A diferencia de las integraciones MCP que sincronizan herramientas automáticamente, con HTTP **tú defines manualmente** cada herramienta: qué endpoint llamar, qué parámetros enviar y cómo autenticarse. ## Crear una Integración HTTP Desde el dashboard, ve a la sección **Integraciones** y haz clic en **Nueva Integración**. Selecciona el tipo **HTTP**. Define los detalles básicos de tu integración: **Nombre**: Identifica tu integración (ej. "Zendesk", "Apidetuempresa" ) **URL Base**: El dominio y ruta base de la API (ej. `https://api.tuempresa.com/v1`) **Descripción**: (Opcional) Explica para qué sirve esta integración **Credenciales**: Dependiendo del servidor, puede requerir: * Bearer Token * Headers personalizados * Sin autenticación Una vez confirmada la conexión, guarda la integración. Ahora puedes crear herramientas que usen esta integración. ## Crear Herramientas Una vez creada la integración, necesitas definir las **herramientas** (acciones específicas) que tus agentes pueden usar. En la lista de integraciones, selecciona la que acabas de crear. Haz clic en **Nueva Herramienta**. Configura los detalles de la acción: **Nombre**: Identificador único en formato snake\_case (ej. `buscar_cliente`, `crear_ticket`) **Descripción**: Explica cuándo el agente debe usar esta herramienta. Sé específico. **Buena descripción**: "Usa esta herramienta cuando el usuario proporcione su número de pedido y quiera saber el estado de su envío" **Mala descripción**: "Consulta pedidos" **Método HTTP**: GET, POST, PUT, PATCH, DELETE **Endpoint**: Ruta relativa a la URL base (ej. `/customers`, `/tickets/create`) **Headers Personalizados**: (Opcional) Añade headers específicos para esta herramienta, si es necesario. Especifica qué información necesita la herramienta. Los parámetros son opcionales (dependerá de la API) y podemos encontrar dos tipos: **Parametros de la query**: Se envían en la URL (ej. `?status=open&limit=5`) **Parametros del body**: Se envían en el cuerpo de la solicitud (JSON) Para cada parámetro define los siguientes campos: * **Nombre**: Identificador único (ej. `customer_id`, `status`). Debe ser el nombre del valor que espera la API. * **Descripción**: Qué información representa y cómo obtenerla * **Tipo de Dato**: string, number, boolean, array, object * **Obligatorio**: Si es requerido o no * **Modo de obtención**: Cómo el agente consigue este valor: * Prompt: El agente pregunta al usuario o lo infiere del contexto * Valor fijo: Un valor constante que defines al crear la herramienta La descripción del parámetro es clave para que el agente entienda qué valor debe proporcionar. Sé claro y específico. ## Ejemplo Completo: Integración con un CRM Vamos a crear una integración con un CRM ficticio para buscar clientes. ### 1. Crear la Integración Pantalla de creación de integración HTTP mostrando campos de nombre, URL base y credenciales ### 2. Crear Herramienta: Buscar Cliente * Configuración basica: Pantalla de creación de herramienta HTTP mostrando campos de nombre, descripción, método y endpoint * Endpoint y método: Configuración del endpoint y método HTTP para la herramienta de buscar cliente * Parámetros: Configuración del body JSON para la herramienta de buscar cliente con parámetro customer_id ### 3. Ejemplo de Uso en Llamada ``` Usuario: Mi email es juan@ejemplo.com, ¿qué pedidos tengo? Agente: [Llama a buscar_cliente con email="juan@ejemplo.com"] API responde: { "customers": [{ "id": "cust_123", "name": "Juan Pérez", "email": "juan@ejemplo.com", "phone": "+34612345678" }] } Agente: Hola Juan, veo que tienes una cuenta con nosotros. Déjame consultar tus pedidos... ``` ## Mejores Prácticas **Nombres de herramientas**: * Usa verbos que describan la acción: `buscar_`, `crear_`, `actualizar_`, `eliminar_` * Formato snake\_case: `consultar_inventario`, no `consultarInventario` * Sé específico: `crear_ticket_soporte`, no solo `crear` **Nombres de parámetros**: * Consistentes con la API: usa los mismos nombres que la documentación * Descriptivos: `customer_id` mejor que `id` Las descripciones ayudan al agente a decidir cuándo usar cada herramienta. **Buenas descripciones incluyen**: * Cuándo usar la herramienta (trigger) * Qué información necesita del usuario * Qué hace exactamente **Ejemplo**: ``` ✅ BIEN: "Usa esta herramienta cuando el usuario mencione su número de pedido y quiera conocer el estado de su envío. Requiere el número de pedido completo (ej. ORD-12345)." ❌ MAL: "Consulta pedidos" ``` Define qué debe hacer el agente si la herramienta falla: **En el prompt del agente**, añade instrucciones como: ```markdown theme={null} ## Manejo de Errores de Herramientas Si una herramienta falla: 1. No repitas el error técnico al usuario 2. Explica el problema en lenguaje simple 3. Ofrece una alternativa Ejemplo: "Lo siento, no puedo acceder a esa información en este momento. ¿Puedo ayudarte con algo más o prefieres que te transfiera con un agente humano?" ``` * **Rota credenciales regularmente**: Actualiza API keys cada 3-6 meses * **Usa credenciales de solo lectura** cuando sea posible * **Separa entornos**: Diferentes credenciales para staging y producción * **Nunca expongas credenciales** en prompts, logs o respuestas del agente Las llamadas lentas pausan la conversación. **Reduce latencia**: * Usa endpoints optimizados (solo pide los datos necesarios) * Limita el tamaño de respuestas (usa parámetros como `limit`, `fields`) * Considera cachear datos que no cambian frecuentemente * Monitorea tiempos de respuesta (objetivo: \< 2 segundos) **Ejemplo**: ``` ✅ BIEN: GET /customers/123?fields=name,email,phone ❌ MAL: GET /customers/123 (devuelve 50 campos innecesarios) ``` ## Solución de Problemas **Causa**: Credenciales incorrectas o expiradas. **Solución**: * Verifica que el tipo de autenticación sea correcto * Confirma que la API key o token esté activa * Revisa si el token tiene los permisos necesarios * Para Bearer tokens, verifica que no haya expirado **Causa**: El endpoint no existe. **Solución**: * Verifica la URL base (debe terminar en la versión de la API, ej. `/v1`) * Confirma que el endpoint esté correctamente escrito * Revisa la documentación para cambios en la API **Causa**: Parámetros faltantes o con formato incorrecto. **Solución**: * Verifica que los parámetros requeridos estén configurados * Confirma que los tipos de datos sean correctos (string, number, etc.) * Revisa que los parámetros estén en la ubicación correcta (path, query, body) **Causa**: Límite de rate limit excedido. **Solución**: * Verifica los límites de la API en su documentación * Reduce la frecuencia de llamadas * Considera upgradar tu plan con el proveedor de la API * Implementa caché para datos que no cambian frecuentemente **Causa**: El agente no sabe cuándo usar la herramienta. **Solución**: * Mejora la descripción de la herramienta (sé más específico) * En agentes de Prompt Único: añade instrucciones explícitas sobre cuándo usar la herramienta * En Caminos Conversacionales: asegúrate de que el nodo correcto esté configurado para usar la herramienta **Causa**: Parámetros mal configurados o descripción ambigua. **Solución**: * Revisa que los parámetros tengan descripciones claras * Asegúrate de que los tipos de datos sean correctos * Mejora las instrucciones en el prompt del agente * Usa confirmación de usuario para herramientas críticas ## Siguientes Pasos Aprende a asignar esta integración a tus agentes y filtrar herramientas. Descubre cómo sincronizar herramientas automáticamente con MCP.