POST/api/mod/comprension/{espacio}/comandos

Interpreta un mensaje del cliente

Le das el mensaje que escribió tu cliente y lo que ya sabes de la conversación. Te devuelve hasta cuatro comandos: qué pide (un precio, agregar al carrito, pagar, hablar con una persona…), de qué producto y cuántos. No ejecuta nada: tú decides qué hacer con cada uno.

PERMISOlee (vale cualquier clave)
CRÉDITOSgasta créditos
AUTENTICACIÓNBearer bth_…

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Comprensión.

CUERPO · JSON

CAMPO	TIPO	REQUERIDO	QUÉ ES
mensaje	string	SÍ	Lo que escribió el cliente, tal cual. De 1 a 4000 caracteres.
contexto	object	no	Lo que ya sabes de la conversación: carrito, productos candidatos, la pregunta que le hiciste… Ver contexto.

RESPUESTA 200

CAMPO	TIPO	QUÉ ES
comandos	array	De 0 a 4, en el orden del mensaje. Cada uno, con su `tipo` y solo los campos que aplican: ver un comando.
schema_version	integer	La versión del catálogo de comandos. Hoy, 2.
latencia_ms	integer	Lo que tardó, en milisegundos.
error	string \| null	`null` si fue bien. Si no se pudo interpretar, `comandos` llega vacío y aquí va un texto para tus registros: sigue con tu lógica de respaldo.

CONTEXTO

CAMPO	TIPO	QUÉ ES
candidatos	[{ id, nombre, linea? }]	Los productos de tu catálogo que pueden ser aquello de lo que habla el cliente, con tu id. Se usan los 12 primeros. Con ellos, cada comando trae `producto_id`: uno de tus ids, o `?` si no es ninguno. `linea` es opcional: una línea o gama que distinga productos que se llaman igual.
carrito	string	Lo que lleva ya, en texto: «1 × Café Huila molido 250 g».
producto_foco	string	El producto del que se está hablando ahora.
pregunta_pendiente	string	Lo último que le preguntaste al cliente. Si el mensaje la contesta, sale responder_pendiente.
dialogo	string[]	Los últimos turnos, uno por elemento («Cliente: …», «Tú: …»). Se usan los 25 últimos, solo para entender «ese» o «el anterior».
resumen	string	Un resumen de la conversación hasta ahora.
destino · metodo_pago	string	La ciudad de envío y el método de pago, si ya los sabes.
tiene_orden	boolean	true si el cliente ya tiene un pedido creado en esta conversación.
intencion_turno_anterior	string	El tipo de comando del mensaje anterior. Ayuda con elipsis como «¿y el grande?».
menciones · menciones_ordenadas	string	Los productos que nombró antes; en orden, para entender «el primero» o «el segundo».

UN COMANDO

CAMPO	TIPO	QUÉ ES
tipo	string	Qué pide: ver tipos. Siempre viene.
producto_id	string	Solo si mandaste `candidatos`: el id del producto, o `?` si no es ninguno de la lista o el comando no va de un producto.
producto · producto_b	string	El producto con las palabras del cliente; producto_b, el segundo de comparar. Búscalos tú en tu catálogo si no mandaste candidatos.
cantidad_total	integer	La cantidad final que quiere («ponme dos», «deja una»), de 1 a 1000. En precio puede ser 0: «¿y sin ese, cuánto queda?».
cantidad_extra	integer	Lo que suma a lo que ya lleva («dos más», «otro»), de 1 a 1000.
unidades	integer	Solo en quitar: cuántas unidades saca. Sin él, quita la línea entera.
solo	boolean	true en agregar o cambiar_cantidad cuando pide «solo ese»: lo demás sale.
reemplaza	string	En reemplazar: el id del producto que sale. El que entra va en producto_id.
opciones	string[]	En clarify: los ids que casan igual de bien (dos o más). Pregúntale cuál quiere.
referente	"carrito" \| "foco" \| "ultimo_anotado"	Señala sin nombrar («eso», «uno más de ese»): a qué apunta. Resuélvelo tú con tu estado.
destino	string	La ciudad de envío que nombra.
metodo	"transferencia" \| "contra" \| "mixto" \| "otro"	En metodo_pago: contra es contraentrega. otro, un medio que no es ninguno de los tres: trátalo como sin elegir.
respuesta	string	En responder_pendiente: lo que contestó («si», «no» o la opción elegida). En vaciar_carrito, «si» si ya lo confirmó en el mismo mensaje.
pregunta	string	En responder_docs: la pregunta del cliente, tal cual.

TIPOS DE COMANDO

CAMPO	TIPO	QUÉ ES
precio	producto	Pregunta el precio de un producto.
stock	producto	Pregunta si hay o cuántas unidades quedan.
comparar	producto	Pide la diferencia entre dos productos.
responder_docs	información	Una pregunta informativa: uso, contenido, políticas, si le sirve.
ver_catalogo	información	Pide el catálogo.
agregar	carrito	Añadir un producto al carrito.
quitar	carrito	Quitar una línea, o unidades de ella.
reemplazar	carrito	Cambiar un producto del carrito por otro.
cambiar_cantidad	carrito	Fijar la cantidad de una línea («cambia a 2»).
vaciar_carrito	carrito	Vaciarlo y empezar de cero.
ver_carrito	carrito	Pregunta qué lleva.
cotizar_envio	pedido	Pide el valor del envío, o el total, a una ciudad.
desglose	pedido	Pide el detalle de su pedido línea a línea.
objecion_precio	pedido	Cuestiona una cifra: «¿por qué tanto?», «muy caro».
cerrar_pedido	pedido	Confirma la compra o quiere pagar.
metodo_pago	pedido	Elige o pregunta el método de pago.
estado_pago	pedido	Pregunta por su pago o su pedido.
datos_despacho	pedido	Da o pregunta datos de entrega.
cancelar	pedido	Cancela el pedido.
responder_pendiente	conversación	Contesta a lo que le preguntaste (pregunta_pendiente).
clarify	conversación	Nombró algo que casa con varios candidatos: mira opciones y pregúntale cuál.
saludo · despedida	conversación	Saluda o se despide.
pedir_humano	conversación	Quiere hablar con una persona.
otro	conversación	Nada de lo anterior.

ERRORES DE ESTA RUTA · SIEMPRE {"detail": …}

STATUS	CUÁNDO	DETAIL LITERAL
403	El espacio no tiene el módulo Comprensión	módulo no habilitado para este espacio.
402	La cuenta agotó sus créditos del ciclo	La cuenta de este espacio agotó sus créditos de este ciclo.
422	Falta mensaje, o pasa de 4000 caracteres (detail es una lista)	—

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

CONVIENE SABER

Vale con cualquier clave, también la de solo lectura: interpretar no cambia nada del espacio. Gasta créditos de la bolsa, como una pregunta.
No guarda nada entre llamadas: ni carrito ni historial. Lo que quieras que tenga en cuenta, mándalo en contexto cada vez.
Con candidatos, el id que devuelve siempre es uno de los tuyos (o ?): no se inventa productos. Sin ellos, solo trae producto con las palabras del cliente.
Si la interpretación falla, responde 200 con comandos vacío y error: no es un 5xx. Tu conversación sigue; responde con tu lógica de siempre.