## Antes de começar

- A app Stripe do Beacon tem de estar registada como **Extension**.
- `STRIPE_EXTENSION_ENABLED=true` no ambiente.
- A conta Stripe já existe e deve ser autorizada por um `OWNER` ou `ADMIN` da organização Beacon.
- O runtime correcto deve estar seleccionado: `https://test.beacon.pt` para `mode=test` e `https://app.beacon.pt` para `mode=live`.

<Note title="Pré-requisito duro">O Beacon exige `scope=read_only` no callback OAuth. Se a Stripe não devolver `read_only`, a ligação é abortada e fica registado o erro operativo `stripe_oauth_extension_required`.</Note>

## Fluxo recomendado

<Steps>
  <Step title="1) Iniciar OAuth">No Dashboard Beacon, abre `Integrações` e dispara `POST /api/stripe/oauth/start?org=<slug>&mode=<modo>`.</Step>
  <Step title="2) Autorizar conta existente">A Stripe apresenta o consentimento OAuth da conta existente. O Beacon não cria contas novas.</Step>
  <Step title="3) Validar callback">A Stripe regressa a `GET /api/stripe/oauth/callback?code=...&state=...`. O Beacon valida `state`, troca o `code` por token e confirma que o `scope` inclui `read_only`.</Step>
  <Step title="4) Confirmar ingestão">A ligação passa a `ACTIVE` e o Beacon começa a ingerir apenas os pagamentos e movimentos visíveis nessa conta Stripe.</Step>
</Steps>

## O que fica claro neste modelo

- O Beacon **não** controla pagamentos e **não** cria contas Stripe.
- O Beacon só ingere o que é **visível** na conta ligada.
- Se a charge original estiver na conta Stripe de uma plataforma third-party, a visibilidade pode ser apenas parcial.
- Nesses casos, a `Sale` fiscal completa só sobe quando chega **Beacon Connect** ou dados equivalentes.

## Depois da ligação

1. Confirmar que o dashboard mostra a conta ligada como Stripe existente via OAuth.
2. Verificar ingestão de `charge.succeeded`, refunds, disputes e, quando aplicável, `transfer` / `payout`.
3. Validar se os casos `destination charge` aparecem como parciais até chegar enriquecimento suficiente.

## Erros comuns

| Sinal | Causa provável | Ação |
| --- | --- | --- |
| OAuth bloqueado no arranque | `STRIPE_EXTENSION_ENABLED=false` | activar a flag e confirmar que a app Stripe está registada como Extension |
| Callback falha com erro operativo | a Stripe não devolveu `read_only` | corrigir registo Extension na Stripe; o Beacon não faz fallback funcional por `read_write` |
| Pagamento entra mas sem `Sale` completa | visibilidade parcial da conta ligada | enviar Beacon Connect com linhas, buyer e seller fiscais |
| `transfer` / `payout` sem charge visível | destination charge ou fluxo controlado por plataforma | tratar como parcial e enriquecer por Beacon Connect |

## Beacon Connect no mesmo fluxo

- `POST /api/platform-connect/verify-mapping`
- `POST /api/platform-connect/payments`
- `POST /api/platform-connect/refunds`
- `POST /api/platform-connect/disputes`

Cada plataforma usa um segredo próprio e um mapping `externalOrgRef -> organizationId` criado na consola admin do Beacon.