API Reference

Functional reference for the real routes served by the Beacon app.

reference • updated 2026-03-17

How to use this reference

This reference is organized by domain and documents the current routes exactly as implemented in the repository.

Endpoint groups

Billing API: subscriptions, checkout, and customer portal.
Stripe & Beacon Connect API: read-only OAuth for existing Stripe and direct platform push.
Webhooks API: Stripe intake, event.id deduplication, and manual replay by webhookEventId.
Fiscal API: documents, reconciliation, and setup state.

Global conventions

Topic	Rule
Base host	`https://app.beacon.pt/api` in `live` and `https://test.beacon.pt/api` in `test`
Authentication	`Authorization: Bearer <beacon_session_token>` on authenticated JSON routes
Context	`org=<organization_slug>` on organization-scoped routes
Mode	`mode=test
Errors	Payload includes `ok`, `error`, `code`, and optionally `nextAction` and `fieldErrors`

OpenAPI

Use OpenAPI spec for the partial contract currently modeled in YAML. The spec follows /api/...; operational details not yet modeled there are documented in the MDX pages in this section.