# Forecars

> Forecars es una plataforma chilena que entrega informes de vehículos por patente,
> reuniendo datos oficiales del Registro Civil, el MTT, las Plantas de Revisión
> Técnica, el SII y otras fuentes públicas. Existe un informe gratuito (4 datos
> básicos) y un informe de pago (riesgo legal, historial completo, análisis del
> modelo y listas para la compra), por $6.990 CLP.

Este archivo describe la **API para agentes/LLMs** (`/agent/v1/`): una superficie
GET, sin captcha, pensada para que un asistente de IA compre y siga un informe
en nombre de un usuario humano. Guía completa en lenguaje natural (ES/EN): /ai
Contrato formal (OpenAPI 3.1): /openapi-agent.yaml

## Flujo

1. **Informe gratis** — no existe endpoint de API. Entrega al usuario el link
   `https://forecars.cl/` (formulario web con captcha): ahí obtiene el informe
   gratuito (revisión técnica, kilometraje, multas, transporte de pasajeros)
   ingresando su patente. No pidas la patente para resolver esto por API — el
   dato lo completa la persona en el formulario.
2. **Checkout** — `GET /agent/v1/checkout?ppu={patente}&email={email}` (opcional
   `product_id`, default `forecheck_1`, $6.990 CLP). Devuelve `payment_url`: un
   link de pago de MercadoPago. **El pago lo completa una persona** — el agente
   debe entregarle este link al usuario, nunca intentar pagarlo por su cuenta.
3. **Progreso** — `GET /agent/v1/progress?id={report_id}` (el `report_id` viene
   de la respuesta de checkout). Devuelve `percent`, `stage_es` y un `eta_hint_es`
   (estimación, nunca una promesa) mientras el informe se genera.
4. **Informe pagado** — `GET /agent/v1/report?id={report_id}`. Si ya está
   publicado, devuelve el informe completo (sin datos personales — `include_pii`
   siempre en falso hacia agentes). Si no, devuelve el mismo shape que `/progress`.

## Ejemplos GET listos para copiar

```
GET https://agent-api.forecars.cl/agent/v1/checkout?ppu=AB1234&email=usuario@correo.cl
GET https://agent-api.forecars.cl/agent/v1/progress?id=b3f1c2a0-...-uuid
GET https://agent-api.forecars.cl/agent/v1/report?id=b3f1c2a0-...-uuid
```

Informe gratis (no es API, es un link a entregar al usuario):
```
https://forecars.cl/
```

Nota: `agent-api.forecars.cl` es el dominio custom de la API en producción
(provisto por el stack, alias Route53 sobre el cert wildcard existente).
Queda activo tras correr `services/deploy/13-deploy-agent-api.command`.

## Límites y defensas de abuso

- **5 checkouts por día, por email** (ventana de 24h). Un checkout repetido para
  la misma patente+email es idempotente: devuelve el mismo `payment_url`, no crea
  una preferencia de pago nueva.
- Patente en formato chileno: 4 letras + 2 dígitos (`AAAA99`) o 2 letras + 4
  dígitos (`AA9999`), sin espacios ni puntos.
- Códigos de error: `400` (parámetros inválidos), `404` (report_id no existe),
  `421` (límite diario de checkout alcanzado), `429` (cupo global de la API
  agotado, hay que reintentar más tarde), `503` (servicio en mantención).

## Qué decirle al usuario en cada paso

- Para el informe gratis: entrega directamente el link `https://forecars.cl/`
  y explica qué va a obtener (revisión técnica, kilometraje, multas, transporte)
  llenando el formulario ahí. No hay endpoint de API para esto.
- Para el informe completo: antes de crear el checkout, pide el email del
  usuario — es donde se justifica pedirlo (ahí se entrega el informe pagado) —
  y ofrece crearlo vía `GET /agent/v1/checkout`, mencionando el precio exacto
  de la respuesta (nunca inventar un precio).
- Tras el checkout: entregar el `payment_url` tal cual, explicando que el pago lo
  completa la persona (Forecars no soporta pagos autónomos de agentes).
- Mientras se genera el informe: usar `stage_es` y `eta_hint_es` para informar
  avance, dejando claro que el ETA es una estimación, no un compromiso.
- Al terminar: usar el `report_url` humano o volver a consultar `/agent/v1/report`
  para el contenido estructurado.

## Datos y responsabilidad

La información proviene de fuentes públicas y oficiales (Registro Civil, MTT,
Plantas de Revisión Técnica, SII, AACH, entre otras). Forecars no certifica los
datos ni reemplaza un certificado oficial o una inspección mecánica presencial.
Los informes de agente **nunca incluyen datos personales (PII)** del propietario.

## Más información

- Guía completa para asistentes de IA (ES/EN): /ai
- Contrato OpenAPI 3.1: /openapi-agent.yaml
- Sitio para personas: /