## Antes de empezar

| Requisito | Por qué es necesario |
| --- | --- |
| Cuenta Stripe existente | OAuth read-only e ingestión de pagos visibles |
| Sesión Beacon autenticada como `OWNER` o `ADMIN` | operaciones API autenticadas con contexto real de organización |
| URL pública HTTPS para webhooks | ingesta segura de eventos |
| Entorno de test aislado | validación sin impacto en live |

<Warning title="Entorno recomendado">Ejecuta todo el quickstart en `test` antes de activar `live`.</Warning>

## Mapa del flujo end-to-end

1. Conectar Stripe.
2. Registrar y validar webhooks.
3. Crear checkout de suscripción.
4. Confirmar estado final en dashboard.
5. Validar señales fiscales y de observabilidad.

## Paso a paso

<Steps>
  <Step title="1) Conectar Stripe existente">Completa OAuth `read-only` y valida la ingestión visible en el dashboard.</Step>
  <Step title="2) Configurar webhooks">Registra los endpoints Beacon en Stripe, guarda los secrets por entorno y valida la firma.</Step>
  <Step title="3) Crear checkout">Llama al endpoint real de checkout y redirige al usuario a `redirectUrl`.</Step>
  <Step title="4) Confirmar resultado">Tras el retorno del checkout, confirma la suscripción con `sessionId` o con el checkout pendiente.</Step>
  <Step title="5) Validar operación">Comprueba estado final en dashboard, procesamiento del webhook y señales fiscales/operativas.</Step>
</Steps>

## Ejemplo API

<Tabs>
  <Tab label="curl">
```bash
curl -X POST "https://test.beacon.pt/api/billing/subscription/checkout?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"plan":"plus","billingCycle":"monthly"}'
```
  </Tab>
  <Tab label="node">
```ts
const response = await fetch(
  "https://test.beacon.pt/api/billing/subscription/checkout?org=acme&mode=test",
  {
  method: "POST",
  headers: {
    Authorization: "Bearer <beacon_session_token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan: "plus",
    billingCycle: "monthly",
  }),
});
```
  </Tab>
</Tabs>

## Validación final

- Checkout devuelve `checkoutSessionId` y `redirectUrl`.
- `POST /api/billing/subscription/confirm` devuelve `subscription` para la organización correcta.
- El procesamiento del webhook guarda `webhookEventId` sin duplicados inesperados.
- Estado de dashboard coherente con la línea temporal operativa.
- Sin alertas críticas en observabilidad.

## Troubleshooting rápido

| Síntoma | Diagnóstico probable | Acción inmediata |
| --- | --- | --- |
| checkout creado pero estado no cambia | falta confirmación post-retorno | llamar `POST /api/billing/subscription/confirm` y validar eventos |
| webhook rechazado | firma inválida | revisar secret y desfase de reloj |
| conflicto `409` | checkout pendiente, suscripción activa o bloqueo de dominio | inspeccionar el estado actual antes de reintentar |

<Tip title="Siguiente paso">Después del quickstart, sigue el [Checklist de go-live](/docs/get-started/go-live-checklist) para cerrar criterios operativos.</Tip>