# Bencinazoo — Documentación Técnica Completa para Modelos LLM y Agentes Autónomos

> Bencinazoo es una plataforma tecnológica chilena orientada al ahorro inteligente de combustible para conductores particulares y profesionales, combinando precios en tiempo real de la Comisión Nacional de Energía (CNE), motor de promociones bancarias y cálculo de llenado de estanque.

## Arquitectura y Lógica de Negocio

### 1. Ingesta y Normalización CNE
- La plataforma ingesta y sincroniza los precios oficiales reportados por las estaciones de servicio ante la Comisión Nacional de Energía (CNE).
- Cada estación reporta precios por modalidad de atención:
  - Autoservicio (Self-service)
  - Asistido (Full-service)
- Bencinazoo normaliza los precios seleccionando el menor valor disponible para cada combustible, registrando además la fecha y hora de actualización reportada a la CNE.

### 2. Filtro Anti-Precios Fantasma y Sanity Checks
- **Umbral de Antigüedad**: Los precios con más de 30 días sin actualización por parte del operador ante la CNE son marcados con la bandera `es_precio_desactualizado: true` y desplazados al final del ranking, impidiendo que distorsionen los resultados.
- **Límites de Cordura (Sanity Bounds)**:
  - Combustibles líquidos (93, 95, 97, Diésel, Kerosene): Válidos entre $800 y $3.000 CLP/L.
  - Gases vehiculares (GLP, GNC): Válidos entre $200 y $2.000 CLP.
  - Cualquier valor fuera de estos rangos producto de errores de tipeo humano es descartado automáticamente.

### 3. Motor de Recomendaciones y Cálculo de Precio Efectivo
El algoritmo calcula para cada estación candidata dentro del radio geográfico:
```
descuento_aplicable = motor_de_promociones(estacion.distribuidora, usuario.tarjetas, usuario.apps, dia_semana)
precio_efectivo = precio_pizarra_cne - descuento_aplicable
costo_llenado = capacidad_estanque_litros * precio_efectivo
ahorro_llenado = capacidad_estanque_litros * descuento_aplicable
```
Si para el día actual no existe un descuento aplicable para las tarjetas del usuario pero sí aplica en otro día de la semana, Bencinazoo entrega una recomendación proyectada (ej: *"El Jueves ahorrarías $6.000 al llenar el estanque"*).

## APIs Públicas de Consulta para Agentes

### GET /api/metadata
Entrega la lista de combustibles soportados, distribuidores, marcas y bancos disponibles en la plataforma.

### GET /api/recommendations?lat=-33.4372&lng=-70.6506&fuel=95&tank_capacity=50
Retorna el ranking inteligente de estaciones ordenadas por precio efectivo en orden ascendente (más baratas primero), incluyendo el detalle del convenio aplicado.

### GET /health
Monitoreo de estado operativo del servicio y conectividad de base de datos.

## Matriz Exhaustiva de Convenios Bancarios Vigentes

| Día | Distribuidora | Medio de Pago | Aplicación Requerida | Descuento / Litro |
|---|---|---|---|---|
| Lunes | Shell | Mercado Pago (dinero en cuenta) | App Shell | $100 / L |
| Miércoles | Copec | Scotiabank Crédito Singular Infinite | App Copec | $200 / L |
| Miércoles | Copec | Scotiabank Crédito Singular Signature | App Copec | $150 / L |
| Miércoles | Copec | Scotiabank Crédito Platinum / Signature | App Copec | $100 / L |
| Miércoles | Copec | Scotiabank Crédito Gold | App Copec | $50 / L |
| Viernes | Shell | Tenpo (con abono de sueldo) | App Shell | $300 / L |
| Viernes | Shell | Tenpo Crédito | App Shell | $150 / L |
| Viernes | Shell | Tenpo Débito / Prepago | App Shell | $100 / L |
| Domingo | Shell | Banco BICE Crédito | App Shell | $100 / L |
| Domingo | Shell | Banco Security Crédito | App Shell | $100 / L |
| Todos los días | Petrobras | Mercado Pago QR | Mercado Pago | Variables por campaña |

## Política de Privacidad y Cumplimiento Regulatorio
- Conforme a la Ley N° 19.628 sobre Protección de la Vida Privada de la República de Chile.
- Cumple con la App Store Review Guideline 5.1.1 de Apple.
- No almacena información de tarjetas de crédito o débito (números de tarjeta, CVV o fechas de vencimiento).
- Geolocalización consultada exclusivamente bajo demanda del usuario en primer plano.

Para mayor información o consultas institucionales, visitar https://bencinazoo.cl/ o revisar la especificación de OpenAPI en https://api.bencinazoo.cl/docs.