Fiscal API

Endpoints do onboarding fiscal self-service Beacon, setup-state canónico e emissão em contexto PT.

reference • updated 2026-03-17

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

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

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