## Como usar esta referência

A referência está organizada por domínio funcional e descreve as rotas actuais da repo, tal como são servidas pela app Beacon.

## Grupos de endpoints

- [Billing API](/docs/api/billing): subscrições, checkout e portal de cliente.
- [Stripe & Beacon Connect API](/docs/api/stripe-connect): OAuth read_only para Stripe existente e push directo de plataformas.
- [Webhooks API](/docs/api/webhooks): ingestão Stripe, deduplicação por `event.id` e replay manual por `webhookEventId`.
- [Fiscal API](/docs/api/fiscal): documentos, reconciliação e estado de configuração.

## Convenções globais

| Tema | Regra |
| --- | --- |
| Base host | `https://app.beacon.pt/api` em `live` e `https://test.beacon.pt/api` em `test` |
| Autenticação | `Authorization: Bearer <beacon_session_token>` nas rotas JSON autenticadas |
| Contexto | `org=<organization_slug>` nas rotas por organização |
| Modo | `mode=test|live`, limitado pelo hostname do ambiente |
| Erros | Payload com `ok`, `error`, `code` e, quando aplicável, `nextAction` e `fieldErrors` |

## OpenAPI

Usa [OpenAPI Spec](/docs/api/openapi-spec) para consumir o contrato parcial actualmente modelado. A spec segue as rotas `/api/...`; detalhes operacionais ainda não modelados ficam documentados nas páginas MDX deste grupo.

<Warning title="Segurança">Estas rotas dependem de sessão Beacon e, na prática, dos papéis `OWNER` ou `ADMIN`. Nunca publiques tokens reais nem uses `mode=live` fora do host de produção.</Warning>