Skip to main content
Para la configuración general, empieza por la guía de conexión API. 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 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

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: 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.

​
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. Escribe un propósito claro en Cuándo y cómo debe usarla la IA:

​
Define la información que se necesita

Pega esto en Esquema JSON de parámetros:
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:
Para POST, Visito coloca esa entrada dentro de arguments y agrega metadatos de conversación. Un cuerpo representativo es:
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.
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.

​
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

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. Los IDs HTTP estables usan http:<toolId>. 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.