OpenAPI Spec

Objetivo

Disponibilizar uma base OpenAPI versionada para consumo por equipas de integração, tooling e geração de SDKs/documentação.

Artefactos disponíveis

• Ficheiro fonte: openapi/beacon.yaml
• Endpoint público estático: /docs/api/openapi.yaml
• Página de referência API: /docs/api

Cobertura atual (MVP expandido)

• billing
• stripe connect
• webhooks
• fiscal
• observability

Como usar hoje

1. Validar contratos de request/response durante desenvolvimento de integrações.
2. Gerar clientes internos de teste com base em schemas estáveis.
3. Comparar diffs da spec em cada release para identificar breaking changes.

Padrões de evolução

• Alterações breaking exigem versionamento explícito de endpoint ou campo.
• Campos novos devem ser backward-compatible e documentados no changelog.
• Operações críticas devem manter exemplos de erro e semântica de idempotência.

Preparação para UI dedicada

A estrutura atual foi organizada para suportar renderização futura com Scalar ou Redoc sem refatoração estrutural de conteúdo:

• tags por domínio funcional;
• schemas reutilizáveis em components;
• descrição operacional por endpoint.

Relação com LLM tooling

• Cada página API tem fonte em markdown bruto via /docs/raw/....
• O endpoint llms.txt lista URLs canónicas e respetivas versões LLM.
• Isto permite indexação controlada sem expor infraestrutura interna.