Fiscal Documents

Record a fiscal document

Record a fiscal document — an NFS-e, a guia, a comprovante, a declaração or a recibo — in its kind's initial state: `RASCUNHO` for an NFS-e, `EMITIDO` for every other kind.

Core stores **references only**. The XML and the PDF live in the tenant backend's object store; a `storage_ref` names the object and carries its sha256. Requires an `Idempotency-Key` header: a create has no prior state to be idempotent on.

Raises: 404: ACCOUNT_NOT_FOUND 409: IDEMPOTENCY_KEY_REUSED 422: INVALID_FISCAL_KIND, INVALID_REFERENCE, or a model validation error (including any field the model does not declare)

Parâmetros

Corpo da requisição

CreateFiscalDocumentRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Move a fiscal document to its next state

Move a fiscal document along its kind's state machine — for an NFS-e, `RASCUNHO → EM_PROCESSAMENTO → AUTORIZADA | REJEITADA`, then `AUTORIZADA → CANCELADA | SUBSTITUIDA`.

⭐ **A replay is a 200 no-op, never an error.** Repeating a transition that already happened — or asking for one the current state does not allow — returns the document unchanged with `applied: false` and a `noop_reason`. A provider callback is delivered more than once as a matter of course.

A rejection must carry **both** `reason` (the text shown to the user) and `provider_code` (the technical code support needs). An NFS-e entering `AUTORIZADA` must carry its 50-character `chave`, which is unique per tenant.

Raises: 404: FISCAL_DOCUMENT_NOT_FOUND (unknown and foreign ids are the same miss) 409: CHAVE_CONFLICT (the chave is recorded against another document) 422: INVALID_FISCAL_STATE, REJECTION_INCOMPLETE, CHAVE_REQUIRED, CHAVE_IMMUTABLE, CHAVE_NOT_APPLICABLE, INVALID_CHAVE, INVALID_REFERENCE

Parâmetros

Corpo da requisição

FiscalTransitionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas