## Objetivo

Controlar onboarding fiscal, emissão, reconciliação e estado canónico de setup sem expor detalhes internos do provider.

## Endpoints principais

| Endpoint | Função | Quando usar |
| --- | --- | --- |
| `POST /api/fiscal/engine/provision?org={slug}&mode={test\|live}` | inicia provisioning gerido pela Beacon | quando a organização entra em plano elegível ou o admin quer retomar setup |
| `POST /api/fiscal/setup/at?org={slug}&mode={test\|live}` | guarda e valida credenciais AT | quando o wizard pedir `Configurar AT` em `live` |
| `POST /api/fiscal/tax-authority/series/communicate?org={slug}&mode={test\|live}` | comunica a série default | quando `blockedSubcode = series_not_reported` |
| `PUT /api/fiscal/tax-authority/saft/automatic?org={slug}&mode={test\|live}` | activa SAF-T automático | quando `blockedSubcode = saft_disabled` |
| `POST /api/fiscal/setup/self-heal?org={slug}&mode={test\|live}` | executa acção fechada do wizard | quando o CTA pode ser resolvido sem input extra |
| `POST /api/fiscal/setup/preview?org={slug}&mode={test\|live}` | gera PDF determinístico de pré-visualização | antes da primeira emissão real ou para demo interna |
| `GET /api/fiscal/overview?org={slug}&mode={test\|live}` | visão agregada de estado fiscal | monitorização diária e handover operacional |
| `GET /api/fiscal/documents?org={slug}&mode={test\|live}` | lista documentos fiscais | operação diária e investigação |
| `POST /api/fiscal/documents?org={slug}&mode={test\|live}` | emissão manual de documento fiscal | após evento comercial elegível |
| `POST /api/fiscal/reconciliation?org={slug}&mode={test\|live}` | enfileira reconciliação de discrepâncias | fecho diário/mensal ou incidente |
| `GET /api/fiscal/setup-state?org={slug}&mode={test\|live}` | fonte única do estado fiscal | sempre que o frontend precisa de decidir CTA, bloqueio ou readiness |

## Contrato de setup-state

- O endpoint devolve um envelope `{ ok, state, context }`; o objecto funcional está dentro de `state`.
- `state.state` contém o estado textual canónico (`ready`, `pending:*`, `blocked:<subcode>`).
- `state.blockedSubcode` simplifica UX para CTAs como `Configurar AT`, `Comunicar série` e `Ativar SAF-T automático`.
- `state.cta`, `state.canRetry` e `state.nextRetryAt` existem para o frontend renderizar sem lógica própria.
- `state.issuanceContextOptions` devolve as opções públicas de estabelecimento e série default para o wizard, sem uma leitura paralela de catálogo.
- `state.profile`, `state.checklist`, `state.blockingReasons`, `state.wizardRequired` e `state.canIssueNow` expõem o progresso operacional actual.
- O fluxo é white-label: o cliente nunca envia tokens, segredos ou endpoints do motor fiscal.
- A pré-visualização devolve sempre um PDF determinístico com marca de água `RASCUNHO - SEM VALOR FISCAL`.

## Fluxo recomendado

<Steps>
  <Step title="1) Provisioning gerido">Chama `engine/provision` sem tokens do cliente. A Beacon cria ou retoma o contexto interno da organização.</Step>
  <Step title="2) Ler setup-state">O frontend consulta `setup-state` e mostra o CTA certo para o bloqueio atual.</Step>
  <Step title="3) Configurar AT em live">Usa `setup/at` para guardar credenciais cifradas e validar o acesso fiscal apenas em `live`.</Step>
  <Step title="4) Resolver bloqueios canónicos">Usa `series/communicate`, `saft/automatic` ou `setup/self-heal` até `setup-state` devolver `ready`.</Step>
  <Step title="5) Pré-visualizar e operar">Gera `setup/preview` sem efeitos laterais e só depois usa `documents` e `reconciliation`.</Step>
</Steps>

## Ambientes

- `test` usa sempre fluxo de demonstração/sandbox, nunca deve comunicar com a AT real, e trata a configuração AT como opcional no wizard.
- Em `test`, se o provider não devolver todos os campos fiscais finais, a Beacon sintetiza apenas marcadores sandbox suficientes para renderizar o PDF final no template Beacon.
- `live` usa validações AT/SAF-T reais e exige todos os controlos antes de ativar emissão.

## blocked states mais comuns

| `blockedSubcode` | CTA principal | Significado |
| --- | --- | --- |
| `at_credentials_invalid` | `Configurar AT` | as credenciais AT falharam |
| `series_not_reported` | `Comunicar série` | a série default ainda não foi comunicada |
| `saft_disabled` | `Ativar SAF-T automático` | o envio automático está desligado |
| `customer_data_incomplete` | `Completar dados do cliente` | faltam dados fiscais/contexto default |
| `provider_unavailable` | `Tentar mais tarde` | indisponibilidade técnica temporária |

<Note title="Conformidade">Usa sempre `setup-state` como fonte única de verdade antes da primeira emissão em `live`.</Note>