OpenAPI spec

Objetivo

Disponibilizar una base OpenAPI versionada para equipos de integración, tooling y futura generación de SDKs/documentación.

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
• observability

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.

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.
• Operaciones críticas deben mantener semántica clara de errores e idempotencia.

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.