## Cómo usar esta referencia

La referencia está organizada por dominio y documenta las rutas actuales exactamente como están implementadas en la repo.

## Grupos de endpoints

- [Billing API](/docs/api/billing): suscripciones, checkout y portal de cliente.
- [Stripe & Beacon Connect API](/docs/api/stripe-connect): OAuth read-only para Stripe existente y push directo de plataformas.
- [Webhooks API](/docs/api/webhooks): ingesta Stripe, deduplicación por `event.id` y replay manual por `webhookEventId`.
- [Fiscal API](/docs/api/fiscal): documentos, conciliación y estado de configuración.

## Convenciones globales

| Tema | Regla |
| --- | --- |
| Host base | `https://app.beacon.pt/api` en `live` y `https://test.beacon.pt/api` en `test` |
| Autenticación | `Authorization: Bearer <beacon_session_token>` en rutas JSON autenticadas |
| Contexto | `org=<organization_slug>` en rutas con alcance por organización |
| Modo | `mode=test|live`, limitado por el hostname de la petición |
| Errores | Payload con `ok`, `error`, `code` y, cuando aplica, `nextAction` y `fieldErrors` |

## OpenAPI

Usa [OpenAPI spec](/docs/api/openapi-spec) para consumir el contrato parcial modelado hoy en YAML. La spec sigue `/api/...`; los detalles operativos todavía no modelados allí quedan documentados en las páginas MDX de esta sección.

<Warning title="Seguridad">Estas rutas dependen de sesión Beacon y, en la práctica, de membresía `OWNER` o `ADMIN`. Nunca publiques tokens reales ni uses `mode=live` fuera del host de producción.</Warning>