Crea un endpoint para consultar pedidos

Este backend sirve a la guía Conectar un sistema. Implementa Visito → tu endpoint con módulos incluidos en Node.js, pedidos ficticios y sin base de datos ni paquetes adicionales.

Ejecuta el ejemplo

Descarga order-status-server.mjs, guárdalo y ejecútalo con Node.js:

TOOL_DEMO_SECRET=local-demo-only node order-status-server.mjs

La URL predeterminada es http://127.0.0.1:4191/visito/order-status. local-demo-only es un token público de ejemplo para una prueba local restringida. Usa un secreto privado y HTTPS antes de exponer un servicio real. El ejemplo no verifica la identidad del cliente y no debe servir datos reales sin cambios. El servidor contiene dos registros ficticios:

const orders = new Map([
  ['A-1003', {
    status: 'shipped', carrier: 'Demo Courier', tracking_number: 'DEMO1003',
    estimated_delivery: '2026-10-03',
    last_update: 'Package left the distribution center.'
  }],
  ['A-1004', {
    status: 'processing', carrier: null, tracking_number: null,
    estimated_delivery: '2026-10-06', last_update: 'Your order is being prepared.'
  }]
]);

La consulta se elige dinámicamente según el número recibido, pero los registros son datos fijos de demostración. Actualiza las fechas al reutilizarlos. No se conecta a una paquetería ni envía paquetes reales.

Sigue la solicitud dentro del servidor

Este extracto anotado muestra el recorrido por el controlador. La autenticación, los límites del cuerpo y el manejo de errores están en el código completo descargable.

Controlador de pedidos: extraer el número, validar, buscar el registro y devolver el resultado.

1. Comprueba ruta y autenticación

Solo acepta POST a /visito/order-status. Antes de buscar, compara Authorization: Bearer ... con TOOL_DEMO_SECRET. Otras rutas devuelven 404; credenciales ausentes o incorrectas devuelven 401.

2. Lee un cuerpo JSON limitado

El ejemplo lee hasta 4 KiB. Un cuerpo mayor devuelve 413, JSON inválido devuelve 400 y los timeouts de solicitud y encabezados son de 10 segundos. El log registra número ficticio, coincidencia y origen; no imprime el encabezado de autenticación.

3. Extrae el parámetro

Para POST, Visito envía la entrada dentro de arguments:

const number = body?.arguments?.order_number;
if (typeof number !== 'string' || !/^A-[0-9]{4}$/.test(number)) {
  return reply(400, { error: 'invalid_order_number' });
}

order_number viene del cliente a través del esquema de entrada. No se lee de la ruta ni de body.order_number. El formato aceptado es A- seguido de cuatro dígitos. Valida también en el servidor aunque el esquema declare un texto obligatorio.

4. Busca y devuelve el registro

if (number === 'A-5000') {
  return reply(503, { error: 'order_service_unavailable' });
}
const order = orders.get(number);
return reply(200, order
  ? { found: true, order_number: number, ...order }
  : { found: false, order_number: number });

En una integración real, sustituye orders.get(number) por una consulta autorizada o una llamada al proveedor. Comprueba el acceso antes de devolver el registro y conserva las credenciales del proveedor en tu servidor. Un pedido ausente y un proveedor caído son resultados distintos; no representes una caída con found: false.

5. Devuelve el resultado a Visito

Visito lee el JSON y lo devuelve al modelo como resultado de la herramienta. El modelo continúa la conversación con esos hechos y redacta la respuesta al cliente. Por eso conviene separar estado, fecha estimada y found. HTTP 200 no demuestra por sí solo el resultado de negocio.

Comprueba solicitud y respuesta

En otra terminal:

curl --fail-with-body http://127.0.0.1:4191/visito/order-status \
  -H 'Authorization: Bearer local-demo-only' \
  -H 'Content-Type: application/json' \
  --data '{"arguments":{"order_number":"A-1003"},"meta":{"source":"developer_test"}}'

Respuesta esperada con HTTP 200:

{
  "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."
}

Variante	Resultado
`A-1004`	200, en preparación, transportista y seguimiento null
`A-9999`	200, `found: false`
`A-5000`	503, `order_service_unavailable`
Número ausente, valor numérico o formato inválido	400, `invalid_order_number`
JSON inválido	400, `invalid_json`
Token ausente o incorrecto	401, `unauthorized`
Más de 4 KiB	413, `request_too_large`

La verificación local capturada probó directamente pedidos conocidos/desconocidos, entrada numérica, autenticación ausente y fallo simulado. Webchat probó la solicitud del número faltante, un pedido conocido, uno inexistente y el fallo del proveedor. Las demás filas describen validaciones del código, no pruebas adicionales capturadas en Webchat. Los metadatos de conversación pueden incluir tenantId, conversationKey, conversationId, channel y eventId. La prueba directa de Visito usa tenantId y source: "developer_test"; no exijas un ID de conversación real para esas pruebas. Los metadatos aportan contexto, no acreditan propiedad del pedido.

Haz accesible el endpoint

Entorno	URL y acceso
Procesos en la misma máquina	Puede funcionar la URL loopback
Visito local en Docker	Usa un servicio o dirección de host accesible; localhost dentro del contenedor apunta al propio contenedor
Visito alojado	Usa HTTPS autenticado y accesible desde Visito; no puede llamar al localhost de tu computadora

La prueba capturada ejecutó el servidor en la misma red local de Docker que el servicio de herramientas. Para una configuración Compose similar, sustituye YOUR_LOCAL_NETWORK por la red real y ejecuta desde la carpeta del archivo descargado:

docker run --rm --name visito-order-status-docs \
  --network YOUR_LOCAL_NETWORK \
  -p 127.0.0.1:4191:4191 \
  -e HOST=0.0.0.0 -e TOOL_DEMO_SECRET=local-demo-only \
  -v "$PWD/order-status-server.mjs:/demo/server.mjs:ro" \
  node:20 node /demo/server.mjs

En la acción local, usa http://visito-order-status-docs:4191/visito/order-status. El puerto publicado queda restringido al loopback del host; el servidor también es accesible en la red Docker seleccionada. No reutilices ese nombre en Visito alojado. La prueba capturada no usó un túnel público. Para GET, Visito agrega entradas como parámetros de consulta. POST envía { "arguments": { ... }, "meta": { ... } }. Las rutas dinámicas del proveedor, otros cuerpos o la renovación OAuth corresponden al adaptador. Consulta el contrato completo.

Prueba la definición guardada

Configúrala en Acciones → Conectar un sistema, con POST, Bearer, timeout de 8 segundos y Solo lectura. Usa Solo área de pruebas para ese entorno o Activa para una prueba expresamente controlada por Webchat. Para una prueba por API, obtén http:<toolId> de Configuraciones de acciones. Puedes mantener la acción Inactiva para esta prueba explícita. La clave de Visito necesita actions:http:execute; listar definiciones requiere además action_configurations:read.

curl --fail-with-body \
  "https://platform-api.visitoai.com/m2m/v1/actions/http:YOUR_TOOL_ID/test" \
  -H "Authorization: Bearer $VISITO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"input":{"order_number":"A-1003"}}'

Se envía una solicitud real y se crea un log. Revisa ok, output y error: HTTP 200 de la API de pruebas puede contener ok: false. Cada repetición es otra invocación. Para escrituras, no repitas a ciegas una solicitud cuyo resultado sea incierto. La clave API de Visito es distinta de TOOL_DEMO_SECRET.

Revisa y limpia

En Acciones → Historial revisa entrada, respuesta, estado HTTP, método, endpoint y duración. Datos guardados de la solicitud puede mostrar solo argumentos, no una captura completa de lo transmitido. El contrato sigue siendo el cuerpo POST descrito arriba.

Datos guardados, encabezados sin información sensible y respuesta del servidor.

Pulsa Abrir conversación y compara los campos devueltos con la respuesta. La consulta local correcta duró 17 ms de HTTP y 26 ms en total; una consulta ficticia local no representa la latencia de un proveedor de producción. Al terminar, desactiva la acción y detén el proceso con Ctrl+C o el contenedor con docker stop visito-order-status-docs. Conserva el historial. Antes de producción, agrega autorización de clientes, datos reales, respuestas limitadas y pruebas de errores y enrutamiento. Esta demostración no desplegó ningún endpoint de producción.

Desarrollar con Visito

Asistentes de programación con IA

Crea un endpoint para consultar pedidos

Ejecuta el ejemplo

Sigue la solicitud dentro del servidor

1. Comprueba ruta y autenticación

2. Lee un cuerpo JSON limitado

3. Extrae el parámetro

4. Busca y devuelve el registro

5. Devuelve el resultado a Visito

Comprueba solicitud y respuesta

Haz accesible el endpoint

Prueba la definición guardada

Revisa y limpia

​Ejecuta el ejemplo

​Sigue la solicitud dentro del servidor

​1. Comprueba ruta y autenticación

​2. Lee un cuerpo JSON limitado

​3. Extrae el parámetro

​4. Busca y devuelve el registro

​5. Devuelve el resultado a Visito

​Comprueba solicitud y respuesta

​Haz accesible el endpoint

​Prueba la definición guardada

​Revisa y limpia

Ejecuta el ejemplo

Sigue la solicitud dentro del servidor

1. Comprueba ruta y autenticación

2. Lee un cuerpo JSON limitado

3. Extrae el parámetro

4. Busca y devuelve el registro

5. Devuelve el resultado a Visito

Comprueba solicitud y respuesta

Haz accesible el endpoint

Prueba la definición guardada

Revisa y limpia