> ## Documentation Index > Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt > Use this file to discover all available pages before exploring further. # Conecta tu agente a un sistema de pedidos > Configura una consulta de pedidos, solicita el número y sigue la solicitud HTTP y su respuesta hasta la conversación. Para la configuración general, empieza por la [guía de conexión API](/es/product-guides/ai-agent/custom-tools). Esta página desarrolla un ejemplo práctico. Un cliente pregunta: «¿Dónde está mi pedido?». El agente solicita el número, consulta tu servidor y explica el estado del envío y la fecha estimada. **Conectar un sistema** es la opción de Acciones para estas integraciones HTTP. Esta guía usa un servidor local temporal y pedidos ficticios. La [guía para desarrolladores](/es/api-docs/guides/order-status-tool) incluye el servidor ejecutable y explica su código. Crear la acción no crea el backend ni conecta directamente una base de datos. ## Elige el tipo de conexión | Tu sistema | Cómo conectarlo | | - | - | | GET con parámetros de consulta y respuesta JSON | Haz coincidir los parámetros de la acción con los de la URL | | POST que acepta el formato de Visito | Conéctalo directamente con su autenticación | | Otro cuerpo, rutas dinámicas, OAuth con renovación o varias llamadas | Crea un endpoint adaptador que traduzca la solicitud | | Base de datos sin API | Expón un endpoint de consulta específico y autorizado | Usa Conocimiento para políticas y preguntas generales. Usa esta acción para datos que dependen del número de pedido y de una consulta actual al servidor. Mantén reembolsos, cancelaciones y otras modificaciones en acciones autorizadas por separado. ## 1. Prepara el servidor Necesitas un espacio de pruebas, acceso de administrador, un endpoint accesible y pedidos ficticios. El servidor acepta `POST /visito/order-status`, comprueba un token Bearer, lee `arguments.order_number` y devuelve: | Número | Resultado | | - | - | | `A-1003` | Enviado con Demo Courier, seguimiento DEMO1003 y entrega estimada el 3 de octubre de 2026 | | `A-1004` | En preparación, todavía sin transportista ni seguimiento | | `A-9999` | Consulta correcta, pero sin pedido coincidente | | `A-5000` | Fallo simulado del servicio con HTTP 503 | Son ejemplos, no entregas reales. Actualiza fechas y registros al reutilizarlos. La URL debe ser accesible **desde el servidor de Visito**, no solo desde tu navegador. Las capturas usan un nombre de host de Docker local que Visito alojado no puede alcanzar. Consulta la [configuración de red](/es/api-docs/guides/order-status-tool#haz-accesible-el-endpoint). ## 2. Crea la acción Ve a **Configuración → Acciones → Conectar un sistema**. El editor se titula **Nueva acción HTTP**. Las capturas usan la interfaz en inglés. Nombre, propósito, conexión y autenticación de la acción en el dashboard en inglés. | Campo | Valor del ejemplo | | - | - | | Nombre | `get_order_status_demo` | | Disponible en | Negocios previstos; Todos los negocios solo para una consulta global | | Método | POST | | Timeout (ms) | 8000 | | URL del endpoint | Tu URL accesible, terminada en `/visito/order-status` | | Autenticación | Bearer | | Secreto | Token del endpoint, sin el prefijo `Bearer ` | | Solo lectura | Activado: el servidor consulta sin modificar el pedido | Escribe un propósito claro en **Cuándo y cómo debe usarla la IA**: ```text theme={null} Consulta un pedido cuando el cliente pregunta dónde está, si se envió o cuándo llegará. Pide el número si falta; usa el proporcionado, no lo inventes. Explica el estado, transportista, seguimiento y fecha estimada devueltos. Una estimación no es una garantía. Si found es false, pide revisar el número. Si falla la solicitud, indica que no se pudo consultar; no inventes datos. Esta acción no crea, cancela, modifica ni reembolsa pedidos. ``` ### Define la información que se necesita Pega esto en **Esquema JSON de parámetros**: ```json theme={null} { "type": "object", "properties": { "order_number": { "type": "string", "description": "El número de pedido proporcionado por el cliente, por ejemplo A-1003." } }, "required": ["order_number"], "additionalProperties": false } ``` Es una definición de entrada, no el cuerpo HTTP. El agente obtiene `order_number` de la conversación. `required` indica que necesita ese dato; tu servidor también debe validar la solicitud. Esquema de entrada, modo Active para Webchat y Solo lectura activado. ### Elige un modo * **Inactiva:** el agente no puede usarla. * **Solo área de pruebas:** permite probar sin habilitar canales de clientes. * **Activa:** disponible en conversaciones elegibles y en el área de pruebas. Las capturas usan Activa porque la prueba controlada se hizo por Webchat local. Empieza tu configuración en Solo área de pruebas. **Solo lectura** describe la operación, pero no impide cambios si el servidor está implementado de otra forma. El área de pruebas envía solicitudes reales; usa datos de prueba. Pulsa **Crear acción**. Al editar, deja Secreto vacío para conservar la credencial. Con autenticación API key, configura el nombre de encabezado exacto que espera el backend. Una clave API de Visito sirve para llamar **a Visito**, no para autenticar este servidor de pedidos. La acción guardada bajo el filtro Connect a system. ## 3. Entiende qué recibe el servidor Cuando el cliente dice «Mi pedido es A-1003», la entrada generada es: ```json theme={null} { "order_number": "A-1003" } ``` Para POST, Visito coloca esa entrada dentro de **arguments** y agrega metadatos de conversación. Un cuerpo representativo es: ```json theme={null} { "arguments": { "order_number": "A-1003" }, "meta": { "tenantId": "YOUR_TENANT_ID", "conversationKey": "YOUR_CONVERSATION_KEY", "conversationId": "YOUR_CONVERSATION_ID", "channel": "webchat", "eventId": "YOUR_EVENT_ID" } } ``` El servidor lee `body.arguments.order_number`, valida el dato, busca esa clave y devuelve los hechos. El ejemplo usa un mapa en memoria. En tu aplicación, esa búsqueda consultaría un registro autorizado de la base de datos o la API de tu proveedor. ```json theme={null} { "found": true, "order_number": "A-1003", "status": "shipped", "carrier": "Demo Courier", "tracking_number": "DEMO1003", "estimated_delivery": "2026-10-03", "last_update": "Package left the distribution center." } ``` Visito devuelve el resultado estructurado al modelo al continuar la conversación. El modelo explica después esos hechos en lenguaje natural. El propósito indica cuándo consultar; no debe contener el estado actual del envío. Ese dato viene de la respuesta del servidor. GET usa parámetros de consulta. Visito no sustituye `order_number` en rutas arbitrarias ni en una plantilla de cuerpo personalizada. Si tu proveedor espera `/orders/A-1003` o un cuerpo plano, tradúcelo en tu adaptador. Consulta el [contrato de la API conversacional](/es/api-docs/conversational-ai-api). ### Revisa el controlador La ilustración sigue el código esencial del servidor descargable: extraer `body.arguments.order_number`, validarlo, buscar el registro y devolver JSON. Es un extracto de código anotado, no una pantalla del panel; el servidor completo también maneja autenticación, límites del cuerpo, tiempos de espera y errores. Extracto anotado del controlador con el número recibido, la búsqueda y la respuesta JSON. ## 4. Prueba la conversación Inicia una conversación nueva. En el área de pruebas, usa su modo exclusivo. Para una prueba controlada de Webchat, activa la acción explícitamente con un backend ficticio. 1. Pregunta «¿Dónde está mi pedido? ¿Ya se envió?». El agente debe solicitar el número sin inventarlo para llamar al sistema. 2. Proporciona `A-1003`. Comprueba que diga enviado, use Demo Courier y DEMO1003 y presente el 3 de octubre como estimación. 3. Consulta `A-9999`. Debe indicar que no encontró el pedido y pedir verificar el número. 4. Consulta `A-5000`. Debe explicar que no pudo consultar el estado, sin inventar datos de entrega. Webchat solicita el número y muestra los datos del envío en inglés. La respuesta para un pedido inexistente pide revisar el número. Fallo simulado del servicio y respuesta que reconoce que no pudo consultar el estado. Estas capturas proceden de la prueba local. No validan conectividad ni reglas de escalamiento de producción. El planner local estaba deshabilitado para aislar esta prueba; verifica el enrutamiento real antes del lanzamiento. ## 5. Revisa Historial y el detalle de conversación Abre **Acciones → Historial**, selecciona entorno y acción y abre una ejecución. Compara fecha y número de pedido con tu conversación. Ejecución con parámetros, método, endpoint, estado HTTP y duración. Revisa **Parámetros**, **Datos guardados de la solicitud**, **Encabezados guardados** y **Respuesta**. Los datos guardados pueden contener solo argumentos, no todo el cuerpo POST transmitido. No interpretes `{ "order_number": "A-1003" }` en ese panel como el cuerpo completo que debe analizar el endpoint. Los datos de autenticación se ocultan o se redactan. Datos y encabezados guardados junto a la respuesta completa de estado del pedido. La consulta demostrada mostró HTTP 200, 17 ms de HTTP y 26 ms en total. Son observaciones de una ejecución local, no una garantía de latencia. **Respuesta HTTP recibida** significa que terminó la solicitud. No significa que exista el pedido ni que se haya entregado: revisa `found` y `status`. Un pedido inexistente puede devolver correctamente HTTP 200 con `found: false`. HTTP 503 representa una consulta fallida, no un pedido ausente. Expande **Detalles técnicos** para ver identificadores. Selecciona **Abrir conversación** y expande el comprobante junto a la respuesta para revisar resultado, integración, inicio y duración. Detalle de conversación con número proporcionado, comprobante completado y respuesta basada en el servidor. El JSON completo está en **Acciones → Historial**; el comprobante de conversación resume la operación. La pestaña Historial del panel lateral contiene otro historial de actividad. Según el canal, el cliente puede ver una etiqueta compacta de actividad, pero debe recibir una respuesta útil, no datos de diagnóstico sin procesar. ## 6. Resuelve problemas y prepara producción | Síntoma | Qué revisar | | - | - | | No se llama a la acción | Modo, negocios, propósito, número ausente y enrutamiento o escalamiento | | HTTP 401/403 | Credencial del endpoint y encabezado esperado | | HTTP 400 | `arguments.order_number`, formato y validación del servidor | | Timeout o fallo de conexión | Acceso desde el backend, salud del servidor y timeout | | HTTP 200 con `found: false` | La consulta funcionó, pero no hubo coincidencia | | JSON correcto y respuesta de chat incorrecta | Compara campos, elimina instrucciones contradictorias y repite la prueba | Antes de usar pedidos reales, el servidor debe comprobar qué registros puede ver el solicitante. Un número de pedido o los metadatos de conversación no demuestran propiedad. Devuelve solo datos necesarios y aptos para el cliente. Conserva credenciales en el servidor y en la autenticación de la acción, nunca en instrucciones para la IA. Para detener llamadas futuras, pon la acción Inactiva; no deshace solicitudes en curso. Al terminar la demostración, desactívala antes de detener el servidor y conserva el historial. Para gestión y pruebas por API, consulta [Acciones e historial de ejecución](/es/api-docs/actions-api). Los IDs HTTP estables usan `http:`. Descubrimiento, gestión, diagnóstico y acceso a parámetros del cliente tienen permisos separados; los clientes antiguos de Tools siguen siendo compatibles. Los enlaces antiguos de Herramientas de desarrollador redirigen a Acciones. El mismo patrón sirve para inventario: recopila `sku`, devuelve `available` y `quantity_available` y explica el resultado. Consultar inventario no lo reserva. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.