Saltar al contenido principal
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. Crea un sistema API personalizado para agrupar esta acción y su conexión. 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. El servidor puede ejecutarse localmente, pero Visito alojado no puede acceder a un host Docker local. Las nuevas capturas usan un host HTTPS de ejemplo; sustitúyelo por tu endpoint de prueba accesible. Consulta la configuración de red.

2. Crea la acción

Abre Conectores → Añade tu propio sistema → Basado en API. En Agregar tu sistema, usa Order system como nombre y configura la conexión compartida antes de definir la acción. Configuración de Order system con URL base compartida y acción de consulta. 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 del número de pedido, Solo lectura y modo de pruebas.

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 nuevas capturas de configuración usan Solo área de pruebas. Las capturas de conversación conservan una prueba controlada anterior por Webchat con modo Activa. 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 sistema. La acción queda dentro de Order system → Acciones. Para añadir más después, usa Agregar acción en ese conector. 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. Acción guardada dentro de Order 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. Este servidor requiere el cuerpo POST predeterminado. Para otra API, Opciones de la solicitud también permite JSON directo y parámetros de ruta declarados, como orders/{order_number}. Marca la entrada como obligatoria y añádela a Parámetros en la ruta. No cambies el formato del cuerpo para este servidor de ejemplo. 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 Actividad y la conversación

Abre Conectores → Actividad, selecciona entorno y acción y abre una ejecución. Compara fecha y número de pedido con tu conversació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. 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 Conectores → Actividad; 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. Consulta los filtros y diagnósticos actuales de Actividad.