Consultar el catálogo

Cuando el catálogo externo está activo y un cliente pregunta por un producto, Astro hace POST a {origen}/astro/producto/webhook con el evento catalogo.consultar. La conversación espera tu respuesta. El límite es de 5 segundos.

Astro recuerda la misma búsqueda unos 45 segundos y después puede repetirla. Responde siempre el precio y la existencia actuales.

Si tu sistema no responde a tiempo, o la respuesta no trae el sobre, Astro no usa el catálogo cargado en la cuenta. Le dice al cliente que no pudo consultar y pasa la conversación a una persona.

Petición

data trae el texto de búsqueda y el máximo de productos que Astro va a usar.

{
  "version": "2026-10-01",
  "evento": "catalogo.consultar",
  "id_evento": "3c2a1b0d-4e5f-6789-abcd-ef0123456789",
  "fecha": "2026-10-07T15:04:05.120000+00:00",
  "tenant_id": "0b1d5c2e-7a11-4e3a-9c2d-111111111111",
  "sucursal": { "codigo": "PTY", "nombre": "Punta Pacífica" },
  "data": { "query": "hamburguesa", "limite": 10 }
}

query es texto libre: un nombre, un código o una frase del cliente. sucursal es null cuando el negocio tiene una sola sede. Si viene informada, filtra precio y existencia por sucursal.codigo.

Cada búsqueda usa un id_evento nuevo. Este evento no hay que deduplicarlo.

Respuesta

{
  "RESPUESTA": "OK",
  "MENSAJE": "Productos encontrados",
  "DATA": {
    "productos": [
      {
        "codigo": "MB-01",
        "nombre": "Mega Burger",
        "precio": 8.5,
        "moneda": "USD",
        "descripcion": "Doble carne y queso",
        "categoria": "Hamburguesas",
        "tipo": "producto",
        "existencia": 12,
        "activo": true
      }
    ]
  }
}

Campo	Regla
codigo	Obligatorio. Hasta 64 caracteres. Es el identificador que volverá en el pedido
nombre	Obligatorio. Hasta 200 caracteres
precio	Obligatorio. Número mayor o igual a 0
moneda	Opcional. Por defecto USD. Hasta 8 caracteres
descripcion	Opcional. Hasta 2000 caracteres
categoria	Opcional. Hasta 120 caracteres
tipo	Opcional. Por defecto producto. Hasta 16 caracteres. Usa servicio para algo que se agenda
existencia	Opcional. Entero. Si la omites, Astro no habla de stock. 0 o menos se muestra como agotado
activo	Opcional. Por defecto true. Con false, Astro no muestra el producto

Devuelve como máximo el limite pedido, hoy 10, y solo coincidencias de esa búsqueda. Un producto mal formado se descarta y el resto se muestra. Una lista vacía significa que no hubo coincidencias, y es una respuesta válida.

DATA es un objeto con la lista en productos. Si productos no es una lista, Astro entiende que no hubo coincidencias.