Como funciona a API de notas tomadas do Ambiente Nacional
· 6 min de leitura
A API de consulta de NFS-e recebidas do Ambiente Nacional funciona por sequência: você informa o último NSU (número sequencial único) conhecido, e ela devolve os documentos fiscais distribuídos a partir dali, associados ao CNPJ consultado.
Parâmetros de consulta
A chamada precisa do CNPJ do tomador e do último NSU já processado por quem consulta: a API não devolve “tudo desde o início” a cada chamada, e sim o que é novo desde aquele ponto. Isso exige que quem integra guarde, do próprio lado, qual foi o último NSU processado com sucesso.
Formato de retorno
O retorno traz os documentos em XML (ou JSON, dependendo do endpoint), incluindo tanto a emissão original quanto eventos relacionados, como cancelamento. Cada chamada devolve um lote limitado de documentos (dezenas, não milhares), o que significa repetir a consulta em sequência até não haver mais nada novo desde o último NSU.
Limitações conhecidas
A consulta é organizada por CNPJ, não por município. Não existe um parâmetro para restringir o retorno a um prestador ou cidade específica dentro da mesma chamada; esse tipo de filtro precisa ser aplicado depois, do lado de quem consome os dados. O tamanho limitado do lote por chamada também significa que picos de volume exigem múltiplas chamadas em sequência, não uma única consulta completa.
Perguntas frequentes
É possível filtrar a consulta por município específico?
Não diretamente na chamada: a API devolve os documentos do CNPJ consultado independentemente do município do prestador. Filtrar por município é um processamento que acontece depois, sobre o resultado já recebido.
Preciso guardar o NSU eu mesmo entre uma chamada e outra?
Sim, ao integrar diretamente: é responsabilidade de quem consome a API manter esse controle, já que a consulta seguinte depende do NSU processado na anterior. Veja mais sobre esse cuidado em erros e códigos de retorno comuns em APIs de notas fiscais.
Manter esse controle de NSU corretamente, chamada após chamada, é justamente o tipo de detalhe que consome tempo de um time de TI. A IntegroBR NFS-e Recebidas cuida dessa mecânica por trás: você escolhe o período que quer monitorar, e a IntegroBR entrega as notas prontas, via painel, API ou webhook.