## 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](/docs/api/openapi.yaml)
- Página de referência API: [/docs/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.

<Note title="Estado actual">A spec modela os endpoints públicos actuais mais estáveis. Quando um detalhe operacional ainda não está no YAML, considera a página MDX correspondente como complemento obrigatório.</Note>