OpenAPI Spec

Objetivo

Disponibilizar uma base OpenAPI versionada para consumo por equipas de integração, tooling e geração de SDKs/documentação, alinhada às rotas reais /api/... da app Beacon.

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
• healthcheck de plataforma

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.
4. Cruzar a spec com estas páginas MDX quando um endpoint ainda expõe payload operacional em evolução.

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 descrever explicitamente quando a deduplicação é interna em vez de ser um header público.

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.