## Objetivo

Disponibilizar una base OpenAPI versionada para equipos de integración, tooling y futura generación de SDKs/documentación, alineada con las rutas reales `/api/...` servidas por la app Beacon.

## Artefactos disponibles

- Fichero fuente: `openapi/beacon.yaml`
- Endpoint público estático: [/docs/api/openapi.yaml](/docs/api/openapi.yaml)
- Landing de referencia API: [/docs/api](/docs/api)

## Cobertura actual

- billing
- stripe connect
- webhooks
- fiscal
- healthcheck de plataforma

## Cómo usarla hoy

1. Validar contratos request/response durante desarrollo de integraciones.
2. Generar clientes internos de prueba a partir de schemas estables.
3. Comparar diffs de la spec en cada release para detectar posibles breaking changes.
4. Cruzar el YAML con las páginas MDX cuando un payload operativo todavía esté evolucionando.

## Reglas de evolución

- Cambios breaking requieren estrategia de versionado explícita por endpoint o campo.
- Campos nuevos deben ser backward-compatible y documentados en changelog.
- Las operaciones críticas deben mantener semántica clara de errores y dejar explícito cuándo la deduplicación es interna en vez de un header público.

## Preparada para UI dedicada

La spec ya está organizada para adopción de Scalar o Redoc sin refactor estructural:

- tags funcionales;
- schemas reutilizables en `components`;
- resumen operacional por endpoint.

## Relación con tooling LLM

- Cada página API tiene markdown bruto en `/docs/raw/...`.
- `llms.txt` lista URLs canónicas y fuentes listas para LLM.
- Esto permite indexación controlada sin exponer infraestructura privada.

<Note title="Estado actual">La spec modela los endpoints públicos más estables expuestos hoy. Cuando un detalle todavía no está en YAML, considera la página MDX correspondiente como complemento obligatorio.</Note>