OpenAPI spec

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
• Landing de referencia 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.