NFS-e Nacional Recebidas

Além de emitir, a API permite consultar as NFS-e que foram emitidas contra a sua empresa no ambiente nacional. Quando a receita informa que uma nota foi emitida tendo o seu CNPJ como tomador, a Focus recebe o XML completo do documento e o disponibiliza para consulta. Esse recurso existe apenas no padrão Nacional (/v2/nfsens_recebidas) — a NFS-e municipal não tem notas recebidas.

📘
Recebidas ≠ Emitidas
Estas operações são de leitura das notas que outros prestadores emitiram contra você — não têm relação com as notas que você emite. Todas usam o recurso nfsens_recebidas (plural), separado do /v2/nfsen de emissão.

Como funciona a consulta incremental

A API foi desenhada para você buscar só o que ainda não conhece, sem reprocessar tudo a cada chamada:

Campo versao: cada nota recebida tem um número versao único e crescente por CNPJ. Guarde apenas o maior valor já visto; na próxima busca, informe-o para receber somente as notas mais novas.
Lote de 100: a consulta devolve no máximo 100 notas por requisição. Para pegar as demais, repita a chamada avançando o versao.
Cabeçalhos de apoio na resposta:
- X-Total-Count — total de registros existentes (incluindo os que ficaram fora do lote de 100).
- X-Max-Version — a maior versao retornada no lote; use-a como ponto de partida (versao) da próxima busca.

📘
Guarde um número por CNPJ
Todo o controle de "o que já baixei" se resume a armazenar o último X-Max-Version por CNPJ. É o que torna a sincronização incremental — sem ele, você relê as mesmas notas.

Operações

Consultar notas recebidas (lote)

GET /v2/nfsens_recebidas — lista as notas recebidas contra um CNPJ.

cnpj (obrigatório) — CNPJ da empresa recebedora.
versao (opcional) — retorna apenas notas com versao maior que o valor informado.
completa (opcional) — com valor 1, devolve os dados completos do XML; sem ela, devolve uma versão resumida/simplificada.

Consultar uma nota específica

Cada nota é identificada pela sua chave de acesso, e o formato é escolhido pela extensão na URL:

JSON: GET /v2/nfsens_recebidas/{chave}.json — dados da nota em JSON.
XML: GET /v2/nfsens_recebidas/{chave}.xml — o XML do documento.
PDF (DANFSe): GET /v2/nfsens_recebidas/{chave}.pdf — o documento visual.
HTML (DANFSe): GET /v2/nfsens_recebidas/{chave} (DANFSe HTML) — versão em HTML da DANFSe.

📘
O PDF vem por redirecionamento
.../{chave}.pdf redireciona para o endereço onde o arquivo está salvo. Se sua biblioteca HTTP não seguir redirecionamentos automaticamente, leia a URL final no cabeçalho Location da resposta.

Reenviar notificação

POST /v2/nfsens_recebidas/{chave}/hook — reaciona os webhooks cadastrados para a nota recebida (útil para recuperar notificações perdidas ou em testes).

Resumo das operações

Operação	Método + rota
Consultar (lote, incremental)	`GET /v2/nfsens_recebidas?cnpj=`
Consultar em JSON	`GET /v2/nfsens_recebidas/{chave}.json`
Consultar em XML	`GET /v2/nfsens_recebidas/{chave}.xml`
Baixar PDF da DANFSe	`GET /v2/nfsens_recebidas/{chave}.pdf`
DANFSe em HTML	`GET /v2/nfsens_recebidas/{chave}`
Reenviar notificação	`POST /v2/nfsens_recebidas/{chave}/hook`

Fonte: documentação da API Focus NFe — operações de NFS-e Nacional Recebidas (/reference/nfsen-recebidas e sub-operações). Endpoints, parâmetros e cabeçalhos conforme publicados (v2.0).