Skip to main content
POST
Download tax documents in batch
Say which documents to bundle with exactly one of taxDocumentIds and filters. With taxDocumentIds you choose the documents yourself; duplicate ids count once, and an id that is not one of your organization’s is reported in missing as NOT_FOUND. With filters every document that matches is bundled, using the same filters as List tax documents (environment included); at least one filter is required, so an empty body is never read as “everything”, and each range must end on or after its start. type chooses which file of each document goes in the zip: XML (the default) or PDF. A zip holds at most 1 000 XML files or 200 PDF files. A selection above the limit is rejected as a bad request, and a filter that matches more documents than the limit is rejected with TAX_DOCUMENT_BATCH_DOWNLOAD_LIMIT_EXCEEDED: narrow the filters, for example to a shorter date range, or select the documents yourself in smaller groups. The zip has one file per document, named by its NFSe number (NFSe-1042.xml), or by its RPS number (RPS-1-1042.xml) before it is authorized, or by its ID. Test-environment documents are prefixed with HOMOLOGACAO-, and when two documents would share a name the document’s ID is appended. It also holds manifest.csv, which lists every requested or matched document with its file name, IDs, NFSe and RPS numbers, status, environment, dates, customer, total value in reais and, for the ones left out, the reason. A document that has no file of the requested type yet, for example because it is not authorized yet, does not fail the request: it is left out of the zip and listed in missing with the reason FILE_NOT_AVAILABLE. The request fails only when no document has a file to include. The link in url expires after expiresInSeconds seconds (1 hour).

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of the organization.

Format: UUID

Body

application/json
​
type
enum<string>

Which file of each tax document to bundle: XML or PDF. Defaults to XML. A zip holds at most 1 000 XML files or 200 PDF files.

Available options:
PDF,
XML
Example:

"XML"

​
taxDocumentIds
string[]

Selection mode: the id of each tax document to bundle. Duplicates count once. At most 1 000 distinct ids for XML and 200 for PDF. Send either this or filters, never both.

Example: ["3d6f9a2b-1c4e-4f8a-9b7d-5e2c1a0f8b63","7a1c5e90-2b3d-4c6f-8e1a-9d4b0f2c7a35"]

Minimum array length: 1
Minimum string length: 1
​
filters
object

Filter mode: bundle every tax document that matches, using the same filters as List tax documents. At least one filter is required, and a filter that matches more than 1 000 documents (200 for PDF) is rejected. Send either this or taxDocumentIds, never both.

Response

Successful response

The zip with the files of the requested tax documents, and what was left out of it.

​
fileName
string
required

Suggested name of the zip file.

Example:

"nfse-xml-2026-10-20_14-30-05.zip"

​
url
string
required

Temporary link to download the zip. Opening it saves the file. It stops working after expiresInSeconds seconds.

Example:

"https://downloads.example.com/nfse-xml-2026-10-20_14-30-05.zip?signature=abc123"

​
expiresInSeconds
number
required

For how long url works, in seconds, counted from this response.

Example:

3600

​
total
number
required

Tax documents the request resolved to: the distinct ids you sent (selection mode), or the documents the filters matched (filter mode).

Example:

3

​
included
number
required

Files inside the zip, besides manifest.csv.

Example:

2

​
missing
object[]
required

Every requested or matched tax document that is not in the zip, and why. Empty when the zip holds all of them. They are also listed in the zip's manifest.csv.

Example: