## Pré-requisitos

- Organização em plano pago elegível.
- Owner/admin com acesso ao ambiente certo (`test` ou `live`).
- Setup-state acessível e sem segredos manuais do cliente.

## Passo a passo

<Steps>
  <Step title="1) Preparar motor fiscal">Executa o provisioning gerido pela Beacon e confirma `setup-state`.</Step>
  <Step title="2) Configurar AT em live">Usa `POST /api/fiscal/setup/at?org=<slug>&mode=live` para guardar credenciais cifradas e validar acesso apenas em `live`.</Step>
  <Step title="3) Configurar perfil e contexto">Preenche o perfil fiscal e usa `state.issuanceContextOptions` de `GET /api/fiscal/setup-state` para confirmar estabelecimento e série default.</Step>
  <Step title="4) Resolver bloqueios">Usa `series/communicate`, `saft/automatic` e `setup/self-heal` até o ambiente ficar em `ready`.</Step>
  <Step title="5) Testar emissão">Gera `setup/preview`, emite documentos de teste em `test` e valida a primeira emissão controlada em `live`.</Step>
</Steps>

## Controlo de qualidade antes de live

1. Confirmar que o frontend usa apenas `GET /api/fiscal/setup-state?org=<slug>&mode=<modo>` para decidir CTAs e ler `state.issuanceContextOptions`.
2. Verificar que o frontend lê o estado funcional a partir do campo `state` do response, sem inventar endpoints paralelos.
3. Verificar reconciliação entre eventos Stripe e documentos fiscais emitidos.
4. Garantir runbooks de provisioning bloqueado, rotação de KEK e backlog fiscal.

## Endpoint canónico para o frontend

Usa sempre `GET /api/fiscal/setup-state?org=<slug>&mode=<modo>`. O response público actual é um envelope `{ ok, state, context }`.

## Erros frequentes

| Sinal | Causa | Mitigação |
| --- | --- | --- |
| `blocked:at_credentials_invalid` | credenciais AT inválidas | reconfigurar AT e correr diagnóstico |
| `blocked:series_not_reported` | série default ainda não comunicada | comunicar série e voltar a validar |
| `blocked:provider_unavailable` | indisponibilidade transitória | aguardar `nextRetryAt` e repetir |

<Tip title="Boa prática">Usa `test` para demonstração e sandbox; nesse ambiente a AT é opcional no wizard. Reserva `live` para a validação final com AT real.</Tip>

<Note title="Pré-visualização">O PDF de `setup/preview` é sempre um rascunho determinístico sem efeitos laterais e com a marca `RASCUNHO - SEM VALOR FISCAL`.</Note>
<Note title="Sandbox final">Em `test`, a emissão final continua a sair no template Beacon; se faltarem campos finais do provider, a Beacon sintetiza marcadores sandbox sem falar com a AT real.</Note>