## Objetivo

Controlar onboarding fiscal, emisión, conciliación y estado canónico de setup sin exponer detalles internos del proveedor.

## Endpoints principales

| Endpoint | Función | Cuándo usar |
| --- | --- | --- |
| `POST /api/fiscal/engine/provision?org={slug}&mode={test\|live}` | inicia provisioning gestionado por Beacon | cuando la organización entra en un plan elegible o un admin quiere reanudar setup |
| `POST /api/fiscal/setup/at?org={slug}&mode={test\|live}` | guarda y valida credenciales AT | cuando el wizard pide `Configurar AT` en `live` |
| `POST /api/fiscal/tax-authority/series/communicate?org={slug}&mode={test\|live}` | comunica la serie por defecto | cuando `blockedSubcode = series_not_reported` |
| `PUT /api/fiscal/tax-authority/saft/automatic?org={slug}&mode={test\|live}` | activa SAF-T automático | cuando `blockedSubcode = saft_disabled` |
| `POST /api/fiscal/setup/self-heal?org={slug}&mode={test\|live}` | ejecuta una acción cerrada del wizard | cuando el CTA puede resolverse sin input extra |
| `POST /api/fiscal/setup/preview?org={slug}&mode={test\|live}` | genera un PDF determinista de vista previa | antes de la primera emisión real o para demos internas |
| `GET /api/fiscal/overview?org={slug}&mode={test\|live}` | estado fiscal agregado | monitorización diaria y handover |
| `GET /api/fiscal/documents?org={slug}&mode={test\|live}` | lista documentos fiscales | operación diaria e investigación |
| `POST /api/fiscal/documents?org={slug}&mode={test\|live}` | emite documentos fiscales manuales | tras eventos comerciales elegibles |
| `POST /api/fiscal/reconciliation?org={slug}&mode={test\|live}` | encola conciliación | cierre diario/mensual o incidentes |
| `GET /api/fiscal/setup-state?org={slug}&mode={test\|live}` | fuente única del estado fiscal | siempre que el frontend necesita CTA, bloqueo o readiness |

## Contrato de setup-state

- El endpoint devuelve un sobre `{ ok, state, context }`; el objeto funcional queda dentro de `state`.
- `state.state` devuelve el estado textual canónico (`ready`, `pending:*`, `blocked:<subcode>`).
- `state.blockedSubcode` permite CTAs claros como `Configurar AT`, `Comunicar serie` y `Activar SAF-T automático`.
- `state.cta`, `state.canRetry` y `state.nextRetryAt` existen para que el frontend renderice sin lógica privada.
- `state.issuanceContextOptions` devuelve las opciones públicas de establecimiento y serie por defecto para el asistente, sin una lectura paralela del catálogo.
- `state.profile`, `state.checklist`, `state.blockingReasons`, `state.wizardRequired` y `state.canIssueNow` exponen el progreso operativo actual.
- El flujo es white-label: el cliente nunca envía tokens, secretos ni endpoints del motor fiscal.
- La vista previa siempre devuelve un PDF determinista con la marca de agua `RASCUNHO - SEM VALOR FISCAL`.

## Flujo recomendado

<Steps>
  <Step title="1) Provisioning gestionado">Llama `engine/provision` sin tokens del cliente. Beacon crea o reanuda el contexto interno.</Step>
  <Step title="2) Leer setup-state">El frontend consulta `setup-state` y muestra el CTA exacto para el bloqueo actual.</Step>
  <Step title="3) Configurar AT en live">Usa `setup/at` para guardar credenciales cifradas y validar el acceso fiscal solo en `live`.</Step>
  <Step title="4) Resolver bloqueos canónicos">Usa `series/communicate`, `saft/automatic` o `setup/self-heal` hasta que `setup-state` devuelva `ready`.</Step>
  <Step title="5) Previsualizar y operar">Genera `setup/preview` sin efectos laterales y solo después usa `documents` y `reconciliation`.</Step>
</Steps>

## Ambientes

- `test` usa siempre flujo demo/sandbox, nunca debe hablar con la autoridad tributaria real, y trata la configuración AT como opcional en el wizard.
- En `test`, si el proveedor no devuelve todos los campos fiscales finales, Beacon sintetiza solo marcadores sandbox para que el PDF final siga saliendo en el template Beacon.
- `live` usa validaciones AT/SAF-T reales y exige todos los controles antes de activar emisión.

## blocked states más comunes

| `blockedSubcode` | CTA principal | Significado |
| --- | --- | --- |
| `at_credentials_invalid` | `Configurar AT` | han fallado las credenciales de la autoridad tributaria |
| `series_not_reported` | `Comunicar serie` | la serie por defecto aún no fue comunicada |
| `saft_disabled` | `Activar SAF-T automático` | el envío automático está desactivado |
| `customer_data_incomplete` | `Completar datos del cliente` | faltan datos fiscales o contexto por defecto |
| `provider_unavailable` | `Intentar más tarde` | indisponibilidad técnica temporal |

<Note title="Compliance">Usa siempre `setup-state` como fuente única de verdad antes de la primera emisión en `live`.</Note>