Pagination and limits

Cursor of each list, limit of 120 requests per minute and maximum body size.

Cursor pagination

Lists that can grow use a cursor: you request a page, store the cursor that came back and send it to request the next one. The names change between routes. This comes from the two parts of the product (received documents existed before issuance), and the contract does not change, so check the table:

Route	Cursor parameter	Items in	Next cursor in	`limite` (default / max.)
`GET /v1/documents`	`cursor`	`itens`	`proximoCursor`	20 / 100
`GET /v1/nfse`	`cursor`	`dados`	`proximo_cursor`	50 / 100
`GET /v1/lotes`	`cursor`	`dados`	`proximo_cursor`	20 / 100
`GET /v1/lotes/{id}/itens`	`cursor`	`dados`	`proximo_cursor`	100 / 500
`GET /v1/webhooks/{id}/entregas`	`cursor`	`entregas`	`proximo_cursor`	50 / 200
`GET /v1/eventos`	`apos`	`eventos`	`proximo_cursor`	100 / 1000

GET /v1/companies and GET /v1/webhooks are not paginated: they return the whole list.

Rules that apply to all of them:

Treat the cursor as an opaque value. Store it and send it back exactly as it came. Do not interpret it, build it or compare it. The internal format can change.
Stop when the next cursor is null. A page with fewer items than limite, or even an empty one, does not mean the end: with a status filter, the page can be smaller and still have a next cursor.
GET /v1/eventos is different: proximo_cursor always comes, even on an empty page. It is a growing log: store the last cursor and read from it again later. See Events.
In the issuance, batch, webhook and event routes, an invalid cursor is 400 parametro_invalido. In /v1/eventos, a cursor older than the 90-day retention is 410 cursor_vencido, with cursor_mais_antigo to continue.
limite out of range: in /v1/nfse it is adjusted into the range, with no error; in the other routes it is 400.

Rate limit

120 requests per minute, per API key, in a fixed 60-second window aligned with the clock. Going over the limit returns 429. There is no Retry-After or X-RateLimit-* header: wait for the minute to turn over and repeat the same request.

A POST /v1/lotes counts as one call, whatever the number of items. For volume, use a batch.
To track invoices, use a webhook. Querying an invoice every second uses up the limit and achieves nothing.

Body size

Up to 2 MB per request. POST /v1/lotes accepts up to 30 MB in JSON and a spreadsheet of up to 20 MB.