# Lupulario

> Lupulario cotiza recetas de cerveza casera en 3 tiendas online de Chile (Mundo Cervecero, Enter Insumos, La Tienda del Cervecero), con despacho incluido, y dice dónde sale más barato comprar todos los ingredientes. Cotizar no pide cuenta ni datos personales. Precios referenciales en CLP con IVA, leídos una vez por semana; manda lo que diga la tienda al comprar.

## Cómo cotizar

La receta va en la URL: una línea por ingrediente, con cantidad, unidad (kg, g, oz, lb, sobre) y nombre, separadas por ";" o por salto de línea (%0A). La comuna de despacho va como slug en minúsculas y sin tildes (providencia, vina-del-mar, puerto-montt).

- Página legible sin JavaScript (HTML): https://lupulario.royarzun.dev/cotizar?receta=5%20kg%20Pale%20Ale%20Weyermann;50%20g%20Willamette;1%20sobre%20SafAle%20S-04&comuna=providencia
- Formato para máquinas (JSON): https://lupulario.royarzun.dev/api/cotizacion?receta=5%20kg%20Pale%20Ale%20Weyermann;50%20g%20Willamette;1%20sobre%20SafAle%20S-04&comuna=providencia

Parámetros (los dos endpoints usan los mismos):
- receta: obligatorio. Ejemplo: receta=5 kg Pale Ale Weyermann;50 g Willamette;1 sobre SafAle S-04
- comuna: obligatorio en la API; en /cotizar, sin comuna se muestra el paso de revisión.
- molida: 1 para malta molida; por defecto 0 (entera).
- retiro: tiendas donde se retira en persona, separadas por coma (mundo-cervecero, la-tienda-del-cervecero); el despacho de esa tienda queda en $0.
- acepto: ids de sustitutos aceptados (equivalencias o grupos), separados por coma. Un sustituto nunca entra a la canasta sin aceptarlo.
- interpretar: 1 para que Lupulario revise las líneas que sus reglas no reconocen (nombres en inglés, abreviaturas, marcas). La respuesta tarda hasta 7 s más. Esas líneas vuelven con via "interpretacion" y confianza "dudosa": revísalas antes de comprar. La respuesta trae "interpretacion": { "estado", "lineas" }.

## Qué devuelve la API

{ "cotizacion": { "fecha", "catalogo", "tiendas", "region", "lineas": [ { "indice", "texto", "cantidad", "emparejamientos": [ { "tienda", "producto", "confianza": "alta" | "dudosa" | "sin-match", "via", "sustituto", "url" } ] } ], "canastaUnaTienda", "canastaOptima": { "tiendas", "total", "pedidos": [ { "tienda", "lineas": [ { "producto", "etiqueta", "cantidad", "subtotal", "sobrante", "url", "carroUrl" } ], "subtotal", "despacho", "total" } ], "faltantes", "totalCompleto", "despachoNoPublicado" }, "canastaAlternativa", "referencia", "diferencia", "ahorro" }, "patrocinado": [], "avisos": [] }

- canastaOptima es la combinación de tiendas más barata con despacho. Primero van las canastas con total completo: solo si ninguna cubre la receta, canastaOptima es una con "totalCompleto": false. canastaAlternativa, si no es null, es la canasta más barata con un despacho sin publicar cuyo total (un piso) es menor que el de canastaOptima: sale más barata solo si ese despacho cuesta menos que canastaOptima.total − canastaAlternativa.total. canastaUnaTienda es comprar todo en una sola tienda. referencia es el precio más bajo de cada ingrediente sin despacho (no es una canasta); su porTienda trae el precio de cada tienda que lo vende, de menor a mayor.
- Cuidado con el despacho que una tienda no publica: su pedido trae "despacho": null y entonces "total" es un piso, no el total. Cada canasta trae "totalCompleto": false y "despachoNoPublicado" con los ids de esas tiendas. En ese caso "diferencia" y "ahorro" vienen en null a propósito: no se pueden calcular contra un total incompleto. Con "retiro" en esa tienda el despacho es 0 de verdad y el total es el total.
- Montos enteros en CLP con IVA. Masas en gramos. Fechas ISO 8601. carroUrl agrega esa línea al carro de la tienda con la cantidad calculada.
- Todo contenido pagado va fuera de "cotizacion", en "patrocinado", rotulado. Los links de afiliado llevan "afiliado": true. Nada pagado cambia el resultado.
- Las líneas que nombran el mismo ingrediente se compran juntas: la línea trae la cantidad sumada y "adiciones" con el texto y la cantidad de cada línea original.
- Errores: 400 con { "error": { "parametro", "mensaje" } } cuando falta receta o comuna o un parámetro es inválido. 429 con Retry-After si se supera el límite de tasa, que es el mismo para personas y agentes. Una línea que no se puede leer no bloquea las demás: aparece con "error" en "lineas".

## Reglas

- Precios referenciales en CLP con IVA; la fecha de lectura de cada tienda viene en "tiendas".
- Mismo trato y mismo límite de tasa para agentes y personas. No hay captchas.
- Nada se guarda en el servidor: cada cotización se calcula al momento.

## Páginas públicas

- Maltas: https://lupulario.royarzun.dev/maltas
- Lúpulos: https://lupulario.royarzun.dev/lupulos
- Levaduras: https://lupulario.royarzun.dev/levaduras
- Azúcares y adjuntos: https://lupulario.royarzun.dev/azucares-adjuntos
- Sales y químicos: https://lupulario.royarzun.dev/sales-quimicos
- Clarificantes y nutrientes: https://lupulario.royarzun.dev/clarificantes-nutrientes
- Especias: https://lupulario.royarzun.dev/especias
- Precio de un ingrediente en cada tienda, de más barata a más cara, con stock y fecha de lectura: una página por ingrediente, por ejemplo https://lupulario.royarzun.dev/maltas/pale-ale/weyermann. Las que tienen stock, o alternativas con stock, están en https://lupulario.royarzun.dev/sitemap.xml.
- Cómo funciona (cálculo, privacidad, afiliados): https://lupulario.royarzun.dev/como-funciona
- Quién es el lector de precios: https://lupulario.royarzun.dev/bot
- Cómo pedir que Lupulario sume una tienda: https://lupulario.royarzun.dev/para-tiendas
- Todas estas páginas responden en Markdown si la solicitud lleva la cabecera Accept: text/markdown.
- Recetas de la comunidad, por estilo y con el promedio de votos (en HTML; cada receta trae JSON-LD Recipe): https://lupulario.royarzun.dev/recetas. Cada receta publicada está en https://lupulario.royarzun.dev/sitemap-recetas.xml
- Agenda de eventos de cerveza en Chile (ferias, festivales, catas, cursos), por fecha, en HTML; cada ficha trae JSON-LD Event y un archivo de calendario en https://lupulario.royarzun.dev/agenda/{id}/calendario.ics: https://lupulario.royarzun.dev/agenda. Cada evento publicado está en https://lupulario.royarzun.dev/sitemap-eventos.xml