Fiscal API

Beacon self-service fiscal onboarding, canonical setup-state, and issuance endpoints for PT operations.

reference • updated 2026-03-17

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

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

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