Fiscal API

Endpoints del onboarding fiscal self-service Beacon, setup-state canónico y emisión en contexto PT.

reference • updated 2026-03-17

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

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

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