Paginação

A API da Nuvem Fiscal contém endpoints que retornam uma lista de dados, como por exemplo ListarNfse, ListarNfe ou ListarCnpj, usados para obter uma lista de NFS-e, NF-e ou uma lista de estabelecimentos comerciais, respectivamente.

Esses endpoints - cuja identificação geralmente inicia com a palavra "Listar" - podem oferecer opções de filtros específicos, mas todos eles oferecem um conjunto de parâmetros comuns, além de um comportamento similar.

Os parâmetros devem ser passados na query string da URL. As listagens sempre retornam um número limitado de dados (10 por padrão), independente dos filtros fornecidos. Se você precisar de mais de 10 registros, deve efetuar a paginação dos dados, pedindo à API os próximos dados.

Parâmetros

Os seguintes parâmetros estão disponíveis em todas as listagens:

$top

Informa o número de objetos a serem retornados na resposta. O valor deve estar entre 1 e 100, e caso não informado o valor padrão é 10.

$skip

Informa o número de objetos a serem ignorados na resposta. Caso não informado o valor padrão é 0. Use esse parâmetro para retornar uma "página", ou seja, se você informar 10 neste parâmetro, a resposta irá ignorar os 10 primeiros objetos e a resposta incluirá dados do objeto 11 (décimo primeiro) em diante. Se você informar 20 neste parâmetro, a resposta incluirá dados do objeto 21 (vigésimo primeiro) em diante.

$inlinecount

É um parâmetro booleano que indica se você deseja que o número total de objetos seja incluído na resposta. O número total de objetos independerá dos parâmetros $top e $skip. Ou seja, ele irá retornar o número total de objetos que atende o filtro, independente da paginação. A inclusão desta informação pode deixar a resposta do endpoint mais lenta, portanto use somente quando realmente necessário.

info

O endpoint ListarCnpj não suporta o parâmetro $inlinecount.

Exemplos

A URL a seguir irá listar as Notas Fiscais Eletrônicas (NF-e) emitidas via Nuvem Fiscal para o CNPJ 46.363.985/0001-10 no ambiente de homologação. Como nenhum parâmetro de paginação foi incluído, irá retornar apenas as 10 primeiras notas:

GET https://api.nuvemfiscal.com.br/nfe?cpf_cnpj=46363985000110&ambiente=homologacao

Já a URL a seguir irá listar 20 notas, ignorando as 100 primeiras. Ou seja, a resposta incluirá as notas 101 a 120:

GET https://api.nuvemfiscal.com.br/nfe?cpf_cnpj=46363985000110&ambiente=homologacao&$top=20&$skip=100

Resposta

A resposta dos endpoints de listagem sempre será um objeto JSON com pelo menos a propriedade data. É essa propriedade que conterá os objetos listados:

{
    "data": [
       <dados da resposta>
    ]
}

Caso o parâmetro $inlinecount seja incluído com valor true na URL, o número total de registros será também incluído na propriedade @count:

{
    "@count": 512,
    "data": [
       <dados da resposta>
    ]
}