## Goal

Control fiscal onboarding, issuance, reconciliation, and canonical setup state without exposing internal provider details.

## Primary endpoints

| Endpoint | Function | Typical usage |
| --- | --- | --- |
| `POST /api/fiscal/engine/provision?org={slug}&mode={test\|live}` | starts Beacon-managed provisioning | when the organization becomes eligible or an admin wants to resume setup |
| `POST /api/fiscal/setup/at?org={slug}&mode={test\|live}` | stores and validates TA credentials | when the wizard asks for `Configure TA` in `live` |
| `POST /api/fiscal/tax-authority/series/communicate?org={slug}&mode={test\|live}` | communicates the default series | when `blockedSubcode = series_not_reported` |
| `PUT /api/fiscal/tax-authority/saft/automatic?org={slug}&mode={test\|live}` | enables automatic SAF-T | when `blockedSubcode = saft_disabled` |
| `POST /api/fiscal/setup/self-heal?org={slug}&mode={test\|live}` | runs a closed wizard action | when the CTA can be resolved without extra input |
| `POST /api/fiscal/setup/preview?org={slug}&mode={test\|live}` | generates a deterministic preview PDF | before the first live issuance or for internal demos |
| `GET /api/fiscal/overview?org={slug}&mode={test\|live}` | aggregate fiscal status | daily monitoring and operational handover |
| `GET /api/fiscal/documents?org={slug}&mode={test\|live}` | list fiscal documents | daily operations and investigation |
| `POST /api/fiscal/documents?org={slug}&mode={test\|live}` | issue manual fiscal documents | after eligible commercial events |
| `POST /api/fiscal/reconciliation?org={slug}&mode={test\|live}` | queue reconciliation | daily/month-end close or incident response |
| `GET /api/fiscal/setup-state?org={slug}&mode={test\|live}` | single source of fiscal truth | whenever the frontend needs the next CTA, block reason, or readiness |

## setup-state contract

- The endpoint returns an envelope `{ ok, state, context }`; the functional object is nested under `state`.
- `state.state` returns the canonical text state (`ready`, `pending:*`, `blocked:<subcode>`).
- `state.blockedSubcode` lets the UI map clean CTAs such as `Configure TA`, `Communicate series`, and `Enable automatic SAF-T`.
- `state.cta`, `state.canRetry`, and `state.nextRetryAt` exist so the frontend can render without private logic.
- `state.issuanceContextOptions` returns the public default store and series options for the wizard, with no parallel catalog read.
- `state.profile`, `state.checklist`, `state.blockingReasons`, `state.wizardRequired`, and `state.canIssueNow` expose current operational progress.
- The flow is white-label: customers never submit provider tokens, secrets, or endpoints.
- Preview always returns a deterministic PDF with the `RASCUNHO - SEM VALOR FISCAL` watermark.

## Recommended flow

<Steps>
  <Step title="1) Managed provisioning">Call `engine/provision` without client tokens. Beacon creates or resumes the internal organization context.</Step>
  <Step title="2) Read setup-state">The frontend reads `setup-state` and renders the exact CTA for the current block.</Step>
  <Step title="3) Configure TA in live">Use `setup/at` to store encrypted tax authority credentials and validate access only in `live`.</Step>
  <Step title="4) Resolve canonical blockers">Use `series/communicate`, `saft/automatic`, or `setup/self-heal` until `setup-state` returns `ready`.</Step>
  <Step title="5) Preview and operate">Generate `setup/preview` with zero side effects and only then use `documents` and `reconciliation`.</Step>
</Steps>

## Environments

- `test` always uses a demo/sandbox flow, must never call the real tax authority, and treats TA setup as optional in the wizard.
- In `test`, if the provider omits final fiscal compliance fields, Beacon synthesizes sandbox-only markers so the final PDF still renders with the Beacon template.
- `live` uses real TA/SAF-T validations and requires all controls before issuance activation.

## Common blocked states

| `blockedSubcode` | Main CTA | Meaning |
| --- | --- | --- |
| `at_credentials_invalid` | `Configure TA` | tax authority credentials failed |
| `series_not_reported` | `Communicate series` | the default series was not reported yet |
| `saft_disabled` | `Enable automatic SAF-T` | automatic submission is disabled |
| `customer_data_incomplete` | `Complete customer data` | fiscal data or default context is missing |
| `provider_unavailable` | `Try again later` | temporary technical outage |

<Note title="Compliance">Always use `setup-state` as the single source of truth before the first `live` issuance.</Note>