Comprensión: cómo funciona

Comprensión lee el mensaje que escribe un cliente en un chat de ventas y te dice qué pide, en comandos que tu programa entiende: un precio, agregar dos unidades de un producto, cotizar el envío a una ciudad, pagar, hablar con una persona.

Sirve si llevas tu propio bot o tu propio carrito: tú pones la conversación y el catálogo, Comprensión interpreta cada mensaje, y tu código decide qué hacer. No contesta al cliente, no toca carritos ni pedidos y no guarda nada. Está hecho para chats de venta en español.

En la consola, el módulo aparece en el Estudio del espacio, sin nada que configurar: todo va en cada llamada.

Antes de empezar

• El espacio tiene que tener el módulo Comprensión: comprension sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
• Vale cualquier clave, también una de solo lectura: interpretar no cambia nada del espacio.
• Las rutas cuelgan de /api/mod/comprension/{espacio}/, con la misma clave y los mismos límites que el resto de la API.
• Cada mensaje interpretado gasta créditos de la bolsa de tu cuenta. Con la bolsa agotada, 402 (bolsa_agotada). Lo gastado, en consumo.

Un mensaje, paso a paso

1. Llega un mensaje de tu cliente. Busca en tu catálogo los productos que puede estar nombrando (hasta 12) y prepara lo que sabes: su carrito, la última pregunta que le hiciste.
2. Manda el mensaje y ese contexto a comandos.
3. Recorre los comandos en orden y ejecútalos tú: añade al carrito, da el precio, cotiza el envío, pasa la conversación a una persona.
4. Si viene clarify, pregúntale cuál de las opciones quiere y guarda la pregunta: en el mensaje siguiente mándala como pregunta_pendiente.

{
  "mensaje": "ponme el grande y quita el molido",
  "contexto": {
    "carrito": "1 × Café Huila molido 250 g",
    "candidatos": [
      { "id": "huila-500", "nombre": "Café Huila en grano 500 g" },
      { "id": "huila-250", "nombre": "Café Huila en grano 250 g" },
      { "id": "huila-molido-250", "nombre": "Café Huila molido 250 g" }
    ]
  }
}

Qué mandar en contexto

• candidatos es lo que más ayuda: con ellos, cada comando trae producto_id con uno de tus ids, o ? si no es ninguno. Nunca un id que no mandaste.
• Si dos candidatos se llaman casi igual (dos tamaños, dos líneas) y el mensaje no dice cuál, no apuesta: devuelve clarify con los dos.
• carrito, en texto, para que «quita uno» o «el doble» sepan sobre qué actuar.
• pregunta_pendiente, para que un «sí» o «el segundo» se entienda como respuesta.
• dialogo o resumen, para entender «ese» o «el anterior». No hace falta mandar la conversación entera.

Los comandos

Hasta cuatro por mensaje, uno por cada cosa que pide, en el orden en que la pide. Cada uno trae su tipo y solo los campos que le aplican.

• Las cantidades van en uno de dos campos: cantidad_total es la cantidad final («ponme dos»); cantidad_extra, lo que suma a lo que lleva («dos más»). Sin ninguno, no dijo cantidad: decide tú.
• Si señala sin nombrar («uno más de ese»), viene referente: carrito, foco o ultimo_anotado. Lo resuelves tú con tu estado.
• Las preguntas de «¿cuánto sería si llevo tres?» son precio con cantidad_total: no cambies el carrito.
• Cada tipo y cada campo, en la ficha de comandos.

Si no se puede interpretar

Comprensión no rompe tu conversación: si algo falla por dentro, responde 200 con comandos vacío y un texto en error. Sigue con tu lógica de respaldo (por ejemplo, contestar que no entendiste o pasar a una persona). Lo mismo si llega vacío sin error: el mensaje no pedía nada que encaje.

Rutas