## Prerrequisitos

- Organización en un plan de pago elegible.
- Owner/admin operando en el modo correcto (`test` o `live`).
- setup-state disponible y sin secretos manuales del cliente.

## Paso a paso

<Steps>
  <Step title="1) Preparar motor fiscal">Ejecuta el provisioning gestionado por Beacon y confirma `setup-state`.</Step>
  <Step title="2) Configurar AT en live">Usa `POST /api/fiscal/setup/at?org=<slug>&mode=live` para guardar credenciales cifradas y validar el acceso solo en `live`.</Step>
  <Step title="3) Configurar perfil y contexto">Completa el perfil fiscal y usa `state.issuanceContextOptions` de `GET /api/fiscal/setup-state` para confirmar establecimiento y serie por defecto.</Step>
  <Step title="4) Resolver bloqueos">Usa `series/communicate`, `saft/automatic` y `setup/self-heal` hasta que el entorno llegue a `ready`.</Step>
  <Step title="5) Probar emisión">Genera `setup/preview`, emite documentos en `test` y valida la primera emisión controlada en `live`.</Step>
</Steps>

## Control de calidad antes de live

1. Confirmar que el frontend usa solo `GET /api/fiscal/setup-state?org=<slug>&mode=<mode>` para CTAs y `state.issuanceContextOptions`.
2. Verificar que el frontend lee el estado funcional desde el campo `state` del response, sin endpoints paralelos.
3. Verificar conciliación entre eventos Stripe y documentos fiscales emitidos.
4. Garantizar runbooks para provisioning bloqueado, rotación de KEK y backlog fiscal.

## Endpoint canónico para frontend

Usa siempre `GET /api/fiscal/setup-state?org=<slug>&mode=<mode>`. El response público actual es un sobre `{ ok, state, context }`.

## Errores frecuentes

| Señal | Causa | Mitigación |
| --- | --- | --- |
| `blocked:at_credentials_invalid` | credenciales AT inválidas | reconfigurar AT y repetir diagnóstico |
| `blocked:series_not_reported` | la serie por defecto no fue comunicada | comunicar la serie y volver a validar |
| `blocked:provider_unavailable` | indisponibilidad temporal | esperar `nextRetryAt` y reintentar |

<Tip title="Buena práctica">Usa `test` para demos y validación sandbox; en ese modo el wizard trata la AT como opcional. Reserva `live` para la validación final con AT real.</Tip>

<Note title="Vista previa">El PDF de `setup/preview` siempre es determinista, sin efectos laterales y con la marca `RASCUNHO - SEM VALOR FISCAL`.</Note>
<Note title="PDF final sandbox">En `test`, la emisión final sigue saliendo con el template Beacon; si faltan campos finales del proveedor, Beacon sintetiza marcadores sandbox sin hablar con la AT real.</Note>