## Antes de começar

| Requisito | Porque é necessário |
| --- | --- |
| Conta Stripe existente | OAuth read_only e ingestão de pagamentos visíveis |
| Sessão Beacon autenticada como `OWNER` ou `ADMIN` | chamadas API autenticadas com contexto real de organização |
| URL pública HTTPS para webhooks | ingestão de eventos com assinatura |
| Ambiente de teste isolado | validação sem impacto em live |

<Warning title="Ambiente recomendado">Executa todo o quickstart em `test` antes de ativares `live`.</Warning>

## Mapa do fluxo end-to-end

1. Ligar Stripe Connect.
2. Registar e validar webhooks.
3. Criar checkout de subscrição.
4. Confirmar estado no dashboard.
5. Verificar emissão fiscal e observabilidade.

## Passo a passo

<Steps>
  <Step title="1) Ligar Stripe existente">Conclui OAuth `read_only` e valida ingestão visível no dashboard.</Step>
  <Step title="2) Configurar webhooks">Regista os endpoints Beacon na Stripe, guarda os secrets por ambiente e valida assinatura.</Step>
  <Step title="3) Criar checkout">Chama o endpoint real de checkout e redirecciona o utilizador para `redirectUrl`.</Step>
  <Step title="4) Confirmar resultado">Após o retorno do checkout, confirma a subscrição com `sessionId` ou com o checkout pendente.</Step>
  <Step title="5) Verificar operação">Confirma estado final no dashboard, webhook processado e sinais fiscais/operacionais.</Step>
</Steps>

## Exemplo 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>

## Validação final

- Checkout devolve `checkoutSessionId` e `redirectUrl`.
- `POST /api/billing/subscription/confirm` devolve `subscription` para a organização correcta.
- Webhook processado com `webhookEventId` e sem duplicados inesperados.
- Dashboard com estado consistente entre billing e operação.
- Alertas de observabilidade sem erros críticos.

## Troubleshooting rápido

| Sintoma | Diagnóstico provável | Ação imediata |
| --- | --- | --- |
| checkout criado mas estado não muda | confirmação pós-retorno em falta | chamar `POST /api/billing/subscription/confirm` e validar eventos |
| webhook rejeitado | assinatura inválida | rever signing secret e relógio do servidor |
| erro `409` | checkout pendente, subscrição activa ou bloqueio funcional | inspeccionar o estado actual antes de repetir |

<Tip title="Próximo passo">Depois do quickstart, segue para [Checklist go-live](/docs/get-started/go-live-checklist) e fecha critérios operacionais.</Tip>