Fiscal API

Fiscal documents are legal artifacts, not usage-summary invoices. Reads require fiscal:read, are organization-scoped, and stay reachable even when production credit is exhausted.

List documents

GET/v1/fiscal/nfse

Query params

Field	Type	Notes
`limit`required	integer	Maximum number of items to return. Defaults to 20; maximum 100. range 1..100
`starting_after`	string	Opaque cursor from the previous response next_cursor.
`status`	"pending" \| "authorized" \| "rejected" \| "blocked" \| "canceled" \| "substituted"	Optional fiscal document status filter.
`source_kind`	"consumption_period" \| "subscription_term"	Optional taxable-event source filter.

Response

Field	Type	Notes
`object`required	"list"
`data`required	object[]
`has_more`required	boolean
`next_cursor`required	string \| null

Retrieve a document

GET/v1/fiscal/nfse/{'{id}'}

Response

Field	Type	Notes
`id`required	string
`object`required	"fiscal_document"
`organization_id`required	string
`status`required	"pending" \| "authorized" \| "rejected" \| "blocked" \| "canceled" \| "substituted"
`source_kind`required	"consumption_period" \| "subscription_term"
`source_id`required	string
`serie`required	string
`numero`required	integer	range -9007199254740991..9007199254740991
`chave_acesso`required	string \| null
`amount_brl`required	string
`competence_date`required	string<ISO-8601> \| null
`receipt_date`required	string<ISO-8601> \| null
`cancellation_deadline_at`required	string<ISO-8601> \| null
`rejection_cstat`required	string \| null
`rejection_reason`required	string \| null
`danfse_available`required	boolean
`xml_available`required	boolean
`created_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updated_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Download artifacts

Authorized documents expose 15-minute presigned URLs for the DANFSE PDF and authorized NFS-e XML. If an artifact is not ready, the API returns fiscal_document_not_ready.

GET/v1/fiscal/nfse/{'{id}'}/danfse

GET/v1/fiscal/nfse/{'{id}'}/xml

Response

Field	Type	Notes
`object`required	"fiscal_document_download"
`fiscal_document_id`required	string
`artifact`required	"danfse" \| "xml"
`url`required	string
`expires_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$