## Prerequisites

- Organization on an eligible paid plan.
- Owner/admin operating in the correct mode (`test` or `live`).
- setup-state available with no manual customer secrets.

## Step-by-step

<Steps>
  <Step title="1) Prepare fiscal engine">Run Beacon-managed provisioning and confirm `setup-state`.</Step>
  <Step title="2) Configure TA in live">Use `POST /api/fiscal/setup/at?org=<slug>&mode=live` to store encrypted credentials and validate access only in `live`.</Step>
  <Step title="3) Configure profile and context">Fill the fiscal profile and use `state.issuanceContextOptions` from `GET /api/fiscal/setup-state` to confirm the default establishment and series.</Step>
  <Step title="4) Clear blocked states">Use `series/communicate`, `saft/automatic`, and `setup/self-heal` until the environment reaches `ready`.</Step>
  <Step title="5) Test issuance">Generate `setup/preview`, issue documents in `test`, and validate the first controlled issuance in `live`.</Step>
</Steps>

## Quality gate before live

1. Confirm the frontend relies only on `GET /api/fiscal/setup-state?org=<slug>&mode=<mode>` for CTAs and `state.issuanceContextOptions`.
2. Verify the frontend reads the functional state from the `state` field in the response, without parallel endpoints.
3. Verify reconciliation between Stripe events and issued fiscal documents.
4. Ensure runbooks exist for stuck provisioning, KEK rotation, and fiscal backlog.

## Canonical frontend endpoint

Always use `GET /api/fiscal/setup-state?org=<slug>&mode=<mode>`. The current public response is an envelope `{ ok, state, context }`.

## Frequent errors

| Signal | Cause | Mitigation |
| --- | --- | --- |
| `blocked:at_credentials_invalid` | invalid TA credentials | reconfigure TA and rerun diagnostics |
| `blocked:series_not_reported` | default series not reported yet | communicate the series and validate again |
| `blocked:provider_unavailable` | temporary outage | wait for `nextRetryAt` and retry |

<Tip title="Good practice">Use `test` for demos and sandbox validation; in that mode the wizard treats TA as optional. Reserve `live` for the final TA-backed validation.</Tip>

<Note title="Preview">The `setup/preview` PDF is always deterministic, side-effect free, and marked `RASCUNHO - SEM VALOR FISCAL`.</Note>
<Note title="Final sandbox PDF">In `test`, final issuance still renders with the Beacon template; when provider compliance fields are missing, Beacon synthesizes sandbox-only markers without calling the real tax authority.</Note>