# AutoRiesgo

> Reportes de riesgo vehicular por patente chilena. Datos de revisión técnica (PRT), multas, TAG, SOAP, propietario y más para due diligence al comprar autos usados en Chile.

## Summary

AutoRiesgo.cl permite consultar información de vehículos por patente (placa patente chilena). Ofrecemos:
- Vista previa gratuita (datos básicos de PRT + más).
- Informes completos pagos con detalles legales, multas, historial, etc.

La API está optimizada para uso directo por LLMs, AI agents y automatizaciones (sin intervención humana).

## API para Agentes de IA, LLMs y MCP

Soportamos acceso programático directo. No uses scraping del sitio web; usa los endpoints de API.

### Endpoints clave

**1. https://api.autoriesgo.cl/api/v1/report/lookup** (público limitado, sin clave - para descubrimiento ligero)

GET https://api.autoriesgo.cl/api/v1/report/lookup?patente=BCYT91

- Sin API key, sin Cloudflare Turnstile.
- **Solo** usa datos gratuitos de PRT (nuestra base de datos propia). Nunca llama a fuentes pagas como Boostr.
- Muy estrictamente limitado:
  - 1 solicitud por 60 segundos **por patente**.
  - 1 solicitud por 60 segundos **por IP** (secundario, para prevenir enumeración).
- Respuestas frescas o cacheadas de PRT.
- Muy conveniente para agentes con herramientas limitadas (solo GET/browse_page): usa browse_page en la URL completa con query param.
- Uso: experimentación ocasional o cuando un LLM responde a una consulta real de usuario ("¿algún problema con esta patente BCYT91?").

Ejemplo (curl):

```bash
curl "https://api.autoriesgo.cl/api/v1/report/lookup?patente=BCYT91"
```

Ejemplo para agentes con browse_page:

```text
browse_page("https://api.autoriesgo.cl/api/v1/report/lookup?patente=BCYT91")
# luego parsea el JSON devuelto como datos del vehículo
```

**2. https://api.autoriesgo.cl/api/v1/report/preview** (recomendado para uso serio de agentes)

POST https://api.autoriesgo.cl/api/v1/report/preview

- Con header `X-Api-Key: TU_CLAVE` (solicita una clave enviando email a soporte@autoriesgo.cl).
- Bypass de Turnstile.
- Límites más generosos (layered):
  - 5 solicitudes por 60 segundos **por patente**.
  - 5 solicitudes por 60 segundos **por clave API** (secundario).
- Puede usar fuentes adicionales (Boostr fallback cuando no hay PRT).
- Proporciona atribución (logs por key prefix + IP) y es el path usado por integraciones oficiales y futuro MCP.
- Prefiere siempre este para producción/uso real de agentes.

Ejemplo (curl):

```bash
curl -X POST https://api.autoriesgo.cl/api/v1/report/preview \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_CLAVE_AQUI" \
  -d '{"patente": "BCYT91"}'
```

### Formato y normalización de patentes

La API normaliza automáticamente la patente de entrada:

- Convierte a mayúsculas.
- Elimina espacios, guiones, puntos y caracteres no alfanuméricos.
- Soporta shorthand de 5 caracteres (ej. ABC12 → ABC012).
- Patrones chilenos válidos:
  - ABCD12 (autos nuevos)
  - AB1234 (autos antiguos)
  - ABC123 (motocicletas)
  - ABC12 (shorthand)

Si el input no es un formato chileno válido después de normalizar, devuelve error 422 con mensaje claro.

Ejemplos de entrada que se normalizan a BCYT91: "bcy t91", "BCYT-91", "bcyt91", "BcyT91".

Siempre envía patentes normalizadas cuando sea posible.

### Autenticación

- **Público (/lookup)**: sin clave.
- **Con clave (/preview)**: envía header `X-Api-Key` (case-insensitive, pero usa `X-Api-Key` en ejemplos).
  - No uses Authorization: Bearer para esta clave (solo X-Api-Key).
  - La clave es compartida inicialmente; contacta para claves por cliente.

Obtén tu clave: soporte@autoriesgo.cl (menciona uso para agentes/LLM/MCP).

### Rate limits y manejo de errores

- Todos los endpoints devuelven `Retry-After` header en respuestas 429.
- El body incluye el tiempo exacto: "Rate limit exceeded for patente. Try again in 60 seconds." (o "for IP" / "for API key").
- Respeta siempre los límites y el header Retry-After.
- El path público está **deliberadamente crippleado** para prevenir scraping masivo. Úsalo solo para uso ligero.
- Para uso serio o alto volumen: usa el path con clave + contacta para límites dedicados.

### Respuesta típica

```json
{
  "patente": "BCYT91",
  "vehicle_data": {
    "make": "HYUNDAI",
    "model": "SONATA",
    "year": 2015,
    "type": "AUTOMOVIL",
    ...
    "prt": {
      "certificate": "...",
      "date": "18-03-2026",
      "status": "A",
      ...
    },
    "source": "prt",
    ...
  }
}
```

Ver el esquema completo en la OpenAPI.

### Ejemplos de código para LLMs / tool calling

**Python (httpx o requests):**

```python
import httpx

# Lookup público (limitado) - GET for convenience
async with httpx.AsyncClient() as client:
    r = await client.get(
        "https://api.autoriesgo.cl/api/v1/report/lookup",
        params={"patente": "BCYT91"}
    )
    print(r.json())

# Con clave (recomendado)
headers = {"X-Api-Key": "TU_CLAVE"}
r = await client.post(
    "https://api.autoriesgo.cl/api/v1/report/preview",
    json={"patente": "BCYT91"},
    headers=headers
)
```

**TypeScript / fetch:**

```ts
const res = await fetch("https://api.autoriesgo.cl/api/v1/report/lookup?patente=BCYT91", {
  method: "GET",
});
const data = await res.json();
```

Para tool calling (OpenAI, Anthropic, etc.):
- Tool name: get_vehicle_preview
- Parameters: patente (string, formato chileno normalizado)
- Description: "Obtiene vista previa gratuita de datos vehiculares por patente chilena usando el endpoint público limitado (GET https://api.autoriesgo.cl/api/v1/report/lookup?patente=...). Para uso serio usa /preview con X-Api-Key."

**Important for agents:** Always fetch live data for the user's specific patente (do not rely only on doc examples). 

If your environment supports arbitrary HTTP (POST/GET), call the endpoint directly.

If your tools are limited to GET page fetches (e.g. only `browse_page` tool, no direct POST or sandbox internet restrictions), use the GET form by constructing the full URL and browsing it:
browse_page("https://api.autoriesgo.cl/api/v1/report/lookup?patente=BCYT91")
The tool will return the response body (JSON text); parse it as the vehicle data and return only that. This enables full autonomy even with browse-only tools.

### Buenas prácticas para agentes

- Prefiere `/report/preview` + `X-Api-Key` para cualquier uso serio o repetido. Da mejor experiencia y permite atribución (sabemos que es tráfico legítimo de agentes).
- Para "queries reales de usuarios": un LLM que responde a "revisa esta patente" debe preferir el path con clave cuando esté disponible.
- Normaliza la patente en tu lado antes de llamar (upper + strip no-alnum).
- Siempre maneja 429 y respeta Retry-After (no retries agresivos).
- No enumeres miles de patentes en el path público: los límites por IP + por patente lo hacen caro y detectable.
- Incluye contexto cuando sea posible (en logs del servidor vemos IP + placa; futuro soporte para headers de query context).

**Para agentes con herramientas limitadas (solo browse_page GET, sin POST directo ni internet sandbox):**
Usa el endpoint GET: construye la URL completa `https://api.autoriesgo.cl/api/v1/report/lookup?patente=XXXX` y usa tu browse_page tool sobre ella. El contenido devuelto será el JSON de la respuesta; parsealo directamente como datos del vehículo. Esto permite ejecución autónoma sin necesidad de herramientas HTTP POST personalizadas.

### Documentación y recursos

- Esta página para agentes: https://autoriesgo.cl/llms.txt
- Página de API / developer docs: https://autoriesgo.cl/api
- OpenAPI schema (para tool generation): disponible vía el backend (FastAPI docs en /docs cuando corres localmente; en prod contacta para acceso).
- Sitio principal: https://autoriesgo.cl (ejemplo de informe gratis, blog, etc.)
- Términos: https://autoriesgo.cl/terminos

### Futuro / roadmap (para agentes)

- Servidor MCP oficial (Streamable HTTP / SSE) exponiendo tools: get_vehicle_preview (free) y purchase_full_report (paid, con callback o credits).
- Reportes completos estructurados en JSON (no solo PDF) para consumo directo por agentes.
- Billing por uso / créditos para agentes.
- Más endpoints (historial, alertas, etc.).
- Mejores headers de rate limit (X-RateLimit-*).

### Contacto y términos de uso para agentes

- Email: soporte@autoriesgo.cl (para claves, límites comerciales, integraciones MCP, volumen pricing).
- Telegram: disponible en el sitio.
- Uso automatizado del path público debe ser de bajo volumen y para queries iniciadas por usuarios reales.
- Para tráfico serio/continuo: usa clave + contacta (evitamos abuso).

Datos primarios de fuentes públicas chilenas (PRT / prt.cl). Boostr como fallback en algunos casos.

© AutoRiesgo - 2026