API Reference

Referência funcional das rotas reais servidas pela app Beacon.

reference • updated 2026-03-17

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: subscrições, checkout e portal de cliente.
Stripe & Beacon Connect API: OAuth read_only para Stripe existente e push directo de plataformas.
Webhooks API: ingestão Stripe, deduplicação por event.id e replay manual por webhookEventId.
Fiscal API: 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
Erros	Payload com `ok`, `error`, `code` e, quando aplicável, `nextAction` e `fieldErrors`

OpenAPI

Usa 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.