Fiscal API

Ver como Markdown

Fiscal API

Endpoints de emissão fiscal, reconciliação e governança operacional em contexto PT.

reference • updated 2026-03-15

Objetivo

Controlar emissão fiscal, reconciliação e estado de setup para garantir conformidade contínua sem bloquear a operação comercial.

Endpoints principais

Endpoint	Função	Quando usar
`GET /v1/fiscal/overview`	visão agregada de estado fiscal	monitorização diária e handover operacional
`POST /v1/fiscal/documents`	emissão de documento fiscal	após evento comercial elegível
`POST /v1/fiscal/reconciliation`	reconciliação de discrepâncias	fecho diário/mensal ou incidente
`GET /v1/fiscal/setup-state`	validação de readiness fiscal	antes de go-live e após alterações de configuração

Pré-requisitos de emissão

Perfil fiscal da organização validado.
Séries e sequências ativas no ambiente correto (test ou live).
Integração com provider fiscal ativa e monitorizada.

Fluxo de emissão recomendado

11) Verificar setup
Consulta setup-state e bloqueia emissão quando houver pendências críticas.
22) Emitir documento
Chama documents com payload consistente e idempotente.
33) Confirmar persistência
Regista identificadores fiscais e estado final por documento.
44) Reconciliar
Executa reconciliation para fechar desvios e pendências.

Erros típicos

Código	Causa comum	Mitigação
`400`	payload fiscal incompleto	validar campos obrigatórios antes do submit
`409`	conflito de sequência/série	sincronizar estado de série e repetir com idempotência
`422`	regra fiscal não satisfeita	rever tipo de documento, regime e dados de cliente
`503`	indisponibilidade transitória do provider	retry com backoff e alerta operacional

Controlos recomendados

Alertas para backlog fiscal e taxa de falha por organização.
Reconciliação diária com janela de correção definida.
Auditoria de alterações em séries, perfis e permissões.